From f713ac513a897193c8b6ac8e34d55d8490fe270f Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Tue, 12 Apr 2022 03:04:20 +0000 Subject: CTAN sync 202204120304 --- macros/latex/contrib/l3kernel/l3doc.dtx | 64 +++++++++++++++++++-------------- 1 file changed, 38 insertions(+), 26 deletions(-) (limited to 'macros/latex/contrib/l3kernel/l3doc.dtx') diff --git a/macros/latex/contrib/l3kernel/l3doc.dtx b/macros/latex/contrib/l3kernel/l3doc.dtx index e3251058b3..0db227edf9 100644 --- a/macros/latex/contrib/l3kernel/l3doc.dtx +++ b/macros/latex/contrib/l3kernel/l3doc.dtx @@ -85,7 +85,7 @@ and all files in that bundle must be distributed together. % require you to do updates, if the class changes.}} % % \author{\Team} -% \date{Released 2022-02-24} +% \date{Released 2022-04-10} % \maketitle % \tableofcontents % @@ -361,69 +361,81 @@ and all files in that bundle must be distributed together. % \subsection{Describing functions in the documentation} % % \DescribeEnv{function} +% \DescribeEnv{variable} +% Two heavily-used environments are defined to describe \pkg{expl3} functions +% and variables. If describing a variable, use the latter environment; it +% behaves identically to the \env{function} environment. % \DescribeEnv{syntax} -% Two heavily-used environments are defined to describe the syntax of -% \pkg{expl3} functions and variables. +% Both of the above environments are typically combined with the \env{syntax} +% environment, to describe their syntax. % \begin{framed} % \vspace{-\baselineskip} % \begin{verbatim} -% \begin{function}{\function_one:, \function_two:} +% \begin{function}{\package_function_one:N, \package_function_two:n} % \begin{syntax} -% |\foo_bar:| \Arg{meta} \meta{test_1} +% \cs{package_function_one:N} \meta{cs} +% \cs{package_function_two:n} \marg{Argument} % \end{syntax} -% \meta{description} +% Descriptive text here ... % \end{function} % \end{verbatim} % \hrulefill % \par % \hspace*{0.25\textwidth} % \begin{minipage}{0.5\textwidth} -% \begin{function}{\function_one:, \function_two:} +% \begin{function}{\package_function_one:N, \package_function_two:n} % \begin{syntax} -% |\foo_bar:| \Arg{meta} \meta{test_1} +% \cs[no-index]{package_function_one:N} \meta{cs} +% \cs[no-index]{package_function_two:n} \marg{Argument} % \end{syntax} -% \meta{description} +% \emph{Descriptive text here …} % \end{function} % \end{minipage} % \end{framed} % % Function environments take an optional argument to indicate whether -% the function(s) it describes are expandable or restricted-expandable -% or defined in conditional forms. Use |EXP|, |rEXP|, |TF|, |pTF|, or |noTF| for -% this; note that |pTF| implies |EXP| since predicates must always be -% expandable, and that |noTF| means that the function without |TF| -% should be documented in addition to |TF|. As an example: +% the function(s) it describes are expandable (use |EXP|) or +% restricted-expandable (use |rEXP|) or defined in conditional forms +% (use |TF|, |pTF|, or |noTF|). Note that |pTF| implies |EXP| since +% predicates must always be expandable, and that |noTF| means that the +% function without |TF| should be documented in addition to |TF|. For +% the conditional forms |TF| and |pTF|, the argument of the +% \env{function} environment is \emph{not} in fact a command that +% exists: in the example below, \cs[no-index]{tl_if_empty:N} does not +% exist, but its conditional forms \cs{tl_if_empty:NT}, +% \cs{tl_if_empty:NF}, \cs{tl_if_empty:NTF} and predicate form +% \cs{tl_if_empty_p:N} exist: % \begin{framed} % \vspace{-\baselineskip} % \begin{verbatim} -% \begin{function}[pTF]{\cs_if_exist:N} +% \begin{function}[pTF]{\tl_if_empty:N, \tl_if_empty:c} % \begin{syntax} -% \cs{cs_if_exist_p:N} \meta{cs} +% \cs{tl_if_empty_p:N} \meta{tl~var} +% \cs{tl_if_empty:NTF} \meta{tl~var} \Arg{true code} \Arg{false code} % \end{syntax} -% \meta{description} +% Tests if the \meta{token list variable} is entirely empty +% (\emph{i.e.}~contains no tokens at all). % \end{function} % \end{verbatim} % \hrulefill % \par % \hspace*{0.25\textwidth} % \begin{minipage}{0.5\textwidth} -% \begin{function}[pTF]{\cs_if_exist:N} +% \begin{function}[pTF]{\tl_if_empty:N, \tl_if_empty:c} % \begin{syntax} -% \cs{cs_if_exist_p:N} \meta{cs} +% \cs{tl_if_empty_p:N} \meta{tl~var} +% \cs{tl_if_empty:NTF} \meta{tl~var} \Arg{true code} \Arg{false code} % \end{syntax} -% \meta{description} +% Tests if the \meta{token list variable} is entirely empty +% (\emph{i.e.}~contains no tokens at all). % \end{function} % \end{minipage} % \end{framed} % -% \DescribeEnv{variable} -% If you are documenting a variable instead of a function, use the -% \env{variable} environment instead; it behaves identically to the -% \env{function} environment above. -% % \DescribeEnv{texnote} % This environment is used to call out sections within \env{function} -% and similar that are only of interest to seasoned \TeX{} developers. +% and similar environments that are only of interest to seasoned +% \TeX{} developers. % % \subsection{Describing functions in the implementation} % -- cgit v1.2.3