From f713ac513a897193c8b6ac8e34d55d8490fe270f Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
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

