summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3doc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3doc.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3doc.dtx64
1 files changed, 38 insertions, 26 deletions
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}
%