☰

自定义段落的章节式引用

tag-icon • tag-icon cross-referencing environments environment-variables
自定义段落的章节式引用

我正在编写一个系统需求规范文档 (SRS)，其中包含具有自定义格式的文本块形式的需求。我创建了一个 latex 环境来格式化这样的块，下面是代码：

\documentclass{article}
\usepackage[most]{tcolorblox}

%param1 project name (was used to name the counter but because usually it is a macro 
%                     in the invoaction it breakes the \newcounter command)
%param2 function
\newcommand{\makereqtype}[2]{ \newcounter{#2-cnt} }
%param1: project name
%param2: function
\NewDocumentEnvironment{requirement}{mm}
{
    \begin{tcolorbox}[boxrule=0pt,frame hidden,sharp corners,enhanced,borderline west={1pt}{0pt}{black}]
    \texttt{#1.\uppercase{#2}.\arabic{#2-cnt}}\\
    }{\stepcounter{#2-cnt}
    \end{tcolorbox}%
}

%That is invoked in the text like this:
\begin{document}
\makereqtype{PROJECT\_NAME}{FUNCTION1} %% do this only once

%% For each requirement of functionality FUNCTION1 do:
\begin{requirement}{PROJECT\_NAME}{FUNCTION1}
requirement stuff
\end{requirement}
\begin{requirement}{PROJECT\_NAME}{FUNCTION1}
requirement stuff
\end{requirement}
\end{document}

输出如下： 在此处输入图片描述 基本思想是将文本格式化为图像中的形式，每次在文本中使用环境时，都会使用自动递增的数字。这种方法有两个问题，我不知道如何解决：

  1. 我制作的两个自定义命令非常微妙，如果参数不是文本而是乳胶函数（例如\uppercase{projectname}，或缩写包中缩写的扩展\ac{prj}）或其他东西（比如说FUNCTION1我使用FUNCTION\_NAME
  2. 最大的问题是我想使用标签来引用要求，就像引用乳胶章节一样。但是当您引用标签时，我想要需求的全名，例如PROJECT_NAME.FUNCTION1.5。我不知道如何优雅地做到这一点，我使用乳胶计数器尝试了 4 个小时，但没有取得太大成功。

你有什么建议吗？

答案1

将代码片段转换为MWE所需的步骤：

  1. 添加\documentclass{article}和document环境。
  2. \usepackage[tcolorblox]-> \usepackage{tcolorblox}。
  3. \usepackage{tcolorblox}-> \usepackage{tcolorbox}。
  4. \newcommand{\makereqtype}[2]{ \newcounter{#2-cnt} }-> \newcommand{\makreqtype}[2]{ \newcounter{#2-cnt} }。
  5. 添加\tcbuselibrary{most}。

请下次更轻松地帮助您！

我思考这可以满足您的大部分要求。我不确定是否有任何东西可以为您提供完全可靠的解决方案，以满足您的需求。

\makereqtype{<name>}{<project>}{<function>}

这或多或少和以前一样。<project>并且<function>可能需要一次扩展（或不需要）。例如，

\newcommand* \bob {BoB}
\makereqtype{projA}{PROJECT\_NAME}{FUNCTION1}
\makereqtype{projB}{PROJECT\_NAME}{FUNCTION2}
\makereqtype{studyX}{studyX}{thing1}
\makereqtype{bobb}{\bob}{\bob}

然后你需要说

\makereqcrefformats{<name>}{<project>}{<function>}

生成交叉引用格式。同样，参数 2 和 3 可以容纳简单的宏等。例如，

\makereqcrefformats{projA}{PROJECT\_NAME}{FUNCTION1}
\makereqcrefformats{projB}{PROJECT\_NAME}{FUNCTION2}
\makereqcrefformats{studyX}{studyX}{thing1}
\makereqcrefformats{bobb}{\bob}{\bob}

然后您可以使用

\begin{<name>}[label=<label>]
    ....
\end{<name>}

像以前一样生成需求本身，并\cref{}获取所需格式的交叉引用。例如，

\begin{projA}[label=req:pfa]
  requirement stuff
\end{projA}
\begin{projA}[label=req:pfc]
  requirement stuff
\end{projA}
\begin{projA}[label=req:pfb]
  requirement stuff
\end{projA}
\begin{projB}[label=req:pba]
  xx
\end{projB}
\begin{projB}[label=req:pbb]
  xx
\end{projB}
\begin{studyX}[label=req:sxa]
  xx
\end{studyX}
\begin{studyX}[label=req:sxb]
  xx
\end{studyX}
\begin{bobb}[label=req:boba]
  xx
\end{bobb}
\begin{bobb}[label=req:bobb]
  xx
\end{bobb}


Refer to \cref{req:pfa}.
\Cref{req:pfa,req:pfb} must be satisfied \emph{prior} to birth for the eligibility criteria to be met.


\Cref{req:pbb,req:pba,req:sxa,req:sxb,req:boba,req:bobb} show nothing whatsoever.

产生以下结果

定制交叉引用

\documentclass{article}
% ateb https://tex.stackexchange.com/a/702340/ i gwestiwn Jhonathan Asimov: https://tex.stackexchange.com/q/702283/
\usepackage{tcolorbox}
\tcbuselibrary{most}
\usepackage{cleveref}

\ExplSyntaxOn
\cs_new_protected:Nn \makereq_crefformats:nnn
{
  \crefformat{#1}{##2#2.#3.##1##3}
  \Crefformat{#1}{##2#2.#3.##1##3}
  \crefrangeformat{#1}{#2.#3.##3##1##4--##5##2##6}
  \Crefrangeformat{#1}{#2.#3.##3##1##4--##5##2##6}
  \crefmultiformat{#1}{#2.#3.##2##1##3}{ ~ and~##2##1##3}{, ~ ##2##1##3}{ ~ and~##2##1##3}
  \Crefmultiformat{#1}{#2.#3.##2##1##3}{ ~ and~##2##1##3}{, ~ ##2##1##3}{ ~ and~##2##1##3}
  \crefrangemultiformat{#1}{#2.#3.##3##1##4--##5##2##6}{ ~ and~##3##1##4--##5##2##6}{, ~ ##3##1##4--##5##2##6}{ ~ and~##3##1##4--##5##2##6}
  \Crefrangemultiformat{#1}{#2.#3.##3##1##4--##5##2##6}{ ~ and~##3##1##4--##5##2##6}{, ~ ##3##1##4--##5##2##6}{ ~ and~##3##1##4--##5##2##6}
}
\cs_generate_variant:Nn \makereq_crefformats:nnn { noo }
\cs_new_eq:NN \makereqcrefformats \makereq_crefformats:noo
\ExplSyntaxOff

\NewDocumentCommand \makereqtype { m  m m }
{% ateb https://tex.stackexchange.com/a/702340/ i gwestiwn Jhonathan Asimov: https://tex.stackexchange.com/q/702283/
  \NewTColorBox
  [
    auto counter,
    crefname={#2.#3}{#2.#3},
    Crefname={#2.#3}{#2.#3},
%     /tcb/label type=#1,
%     /tcb/label is label,
  ]{#1}{ O {} }
  {%
    boxrule=0pt,
    titlerule=0pt,
    coltitle=black,
    colbacktitle=black!5,
    colback=black!5,
    sharp corners,
    enhanced,
    borderline west={1pt}{0pt}{black},
    title={#2.\MakeUppercase{#3}.\thetcbcounter},
    fonttitle=\ttfamily,
    ##1,
  }%
}
\begin{document}
\newcommand* \bob {BoB}
\makereqtype{projA}{PROJECT\_NAME}{FUNCTION1}
\makereqtype{projB}{PROJECT\_NAME}{FUNCTION2}
\makereqtype{studyX}{studyX}{thing1}
\makereqtype{bobb}{\bob}{\bob}
\makereqcrefformats{projA}{PROJECT\_NAME}{FUNCTION1}
\makereqcrefformats{projB}{PROJECT\_NAME}{FUNCTION2}
\makereqcrefformats{studyX}{studyX}{thing1}
\makereqcrefformats{bobb}{\bob}{\bob}

\begin{projA}[label=req:pfa]
  requirement stuff
\end{projA}
\begin{projA}[label=req:pfc]
  requirement stuff
\end{projA}
\begin{projA}[label=req:pfb]
  requirement stuff
\end{projA}
\begin{projB}[label=req:pba]
  xx
\end{projB}
\begin{projB}[label=req:pbb]
  xx
\end{projB}
\begin{studyX}[label=req:sxa]
  xx
\end{studyX}
\begin{studyX}[label=req:sxb]
  xx
\end{studyX}
\begin{bobb}[label=req:boba]
  xx
\end{bobb}
\begin{bobb}[label=req:bobb]
  xx
\end{bobb}


Refer to \cref{req:pfa}.
\Cref{req:pfa,req:pfb} must be satisfied \emph{prior} to birth for the eligibility criteria to be met.


\Cref{req:pbb,req:pba,req:sxa,req:sxb,req:boba,req:bobb} show nothing whatsoever.
\end{document}

答案2

我会为交叉引用所需的标签添加一个可选参数。

请注意，您应该使用\MakeUppercase，而不是\uppercase。

\documentclass{article}
\usepackage[most]{tcolorbox}

\newcommand{\makereqtype}[2]{%
  \newcounter{#2-cnt}%
  %\setcounter{#2-cnt}{-1}% uncomment if you want to start from 0
}

%param1: project name
%param2: function
\NewDocumentEnvironment{requirement}{mmo}{%
  \begin{tcolorbox}[
    boxrule=0pt,
    frame hidden,
    sharp corners,
    enhanced,
    borderline west={1pt}{0pt}{black}
  ]
  \ExpandArgs{c}\renewcommand{the#2-cnt}{#1.\MakeUppercase{#2}.\arabic{#2-cnt}}%
  \refstepcounter{#2-cnt}\IfValueT{#3}{\label{#3}}%
  \texttt{\UseName{the#2-cnt}}\\
}{\end{tcolorbox}}

%That is invoked in the text like this:
\begin{document}

\makereqtype{PROJECT\_NAME}{FUNCTION1} %% do this only once

%% For each requirement of functionality FUNCTION1 do:
\begin{requirement}{PROJECT\_NAME}{FUNCTION1}
requirement stuff
\end{requirement}

\begin{requirement}{PROJECT\_NAME}{FUNCTION1}[foo]
requirement stuff
\end{requirement}

\ref{foo}

\end{document}

如果希望编号从 0 开始，请取消注释定义中的该行\makereqtype。

在这个应用程序中，使用可扩展版本是有意义的\MakeUppercase。

\documentclass{article}
\usepackage[most]{tcolorbox}

\newcommand{\makereqtype}[2]{%
  \newcounter{#2-cnt}%
  %\setcounter{#2-cnt}{-1}% uncomment if you want to start from 0
}

\ExplSyntaxOn
\cs_new_eq:NN \ExpMakeUppercase \text_uppercase:n
\ExplSyntaxOff

%param1: project name
%param2: function
\NewDocumentEnvironment{requirement}{mmo}{%
  \begin{tcolorbox}[
    boxrule=0pt,
    frame hidden,
    sharp corners,
    enhanced,
    borderline west={1pt}{0pt}{black}
  ]
  \ExpandArgs{c}\renewcommand{the#2-cnt}{#1.\ExpMakeUppercase{#2}.\arabic{#2-cnt}}%
  \refstepcounter{#2-cnt}\IfValueT{#3}{\label{#3}}%
  \texttt{\UseName{the#2-cnt}}\\
}{\end{tcolorbox}}

%That is invoked in the text like this:
\begin{document}

\makereqtype{PROJECT\_NAME}{FUNCTION1} %% do this only once

%% For each requirement of functionality FUNCTION1 do:
\begin{requirement}{PROJECT\_NAME}{FUNCTION1}
requirement stuff
\end{requirement}

\begin{requirement}{PROJECT\_NAME}{FUNCTION1}[foo]
requirement stuff
\end{requirement}

\ref{foo}

\end{document}

在此处输入图片描述

您可能想要添加

\newcommand{\projref}[1]{\texttt{\ref{#1}}}

并将交叉引用称为\projref{foo}。

相关内容