[latex3-commits] [git/LaTeX3-latex3-latex3] scan-quark: Correct the documentation of \__kernel_quark_new_ functions (a643c31b3)
Bruno Le Floch
bruno at le-floch.fr
Wed May 6 11:07:06 CEST 2020
Repository : https://github.com/latex3/latex3
On branch : scan-quark
Link : https://github.com/latex3/latex3/commit/a643c31b3aec04474b03b5cec686349522be07f4
>---------------------------------------------------------------
commit a643c31b3aec04474b03b5cec686349522be07f4
Author: Bruno Le Floch <bruno at le-floch.fr>
Date: Wed May 6 11:02:53 2020 +0200
Correct the documentation of \__kernel_quark_new_ functions
>---------------------------------------------------------------
a643c31b3aec04474b03b5cec686349522be07f4
l3kernel/l3kernel-functions.dtx | 132 +++++++++++++++++++---------------------
1 file changed, 61 insertions(+), 71 deletions(-)
diff --git a/l3kernel/l3kernel-functions.dtx b/l3kernel/l3kernel-functions.dtx
index 6ac286a0d..19682bf36 100644
--- a/l3kernel/l3kernel-functions.dtx
+++ b/l3kernel/l3kernel-functions.dtx
@@ -334,107 +334,97 @@
% \cs{__kernel_quark_new_test:N} \cs[no-index]{\meta{name}:\meta{arg spec}}
% \end{syntax}
% Defines a quark-test function \cs[no-index]{\meta{name}:\meta{arg spec}}
-% which tests if its argument is \cs[no-index]{q\meta{namespace}_recursion_tail},
+% which tests if its argument is \cs[no-index]{q__\meta{namespace}_recursion_tail},
% then acts accordingly, as described below for each possible
% \meta{arg spec}.
%
-% The \meta{arg spec} \emph{must} be one of the options listed
-% below. Both \cs[no-index]{q\meta{namespace}_recursion_tail}
-% and \cs[no-index]{q\meta{namespace}_recursion_stop}
-% should be valid quarks, defined with \cs{quark_new:N}, and
-% \meta{namespace} should be the name space to be used internally
-% in the definition of auxiliaries (for example |__module|), obtained
-% for instance as |@@| when using \pkg{l3docstrip}.
-%
-% \cs{__kernel_quark_new_test:N} can define $6$ different
-% types of quark-test functions. Which one is defined depends on
-% the \meta{arg spec} of the given function:
+% The \meta{namespace} is determined as the first (nonempty)
+% |_|-delimited word in \meta{name} and is used internally
+% in the definition of auxiliaries. The function
+% \cs{__kernel_quark_new_test:N} does \emph{not} define
+% the \cs[no-index]{q__\meta{namespace}_recursion_tail} and
+% \cs[no-index]{q__\meta{namespace}_recursion_stop} quarks.
+% They should be manually defined with \cs{quark_new:N}.
+%
+% There are $6$ different types of quark-test functions. Which one is
+% defined depends on the \meta{arg spec}, which \emph{must} be one of
+% the options listed now. Four of them are modeled after
+% \cs[no-index]{quark_if_recursion_tail:(N|n)} and
+% \cs[no-index]{quark_if_recursion_tail_do:(N|n)n}.
% \begin{description}
% \def\makelabel#1{\texttt{#1}}
% \item[n] defines \cs[no-index]{\meta{name}:n} such that it
-% checks if |#1| contains only \cs[no-index]{q\meta{namespace}_recursion_tail}, and
-% if so consumes all tokens up to \cs[no-index]{q\meta{namespace}_recursion_stop}
+% checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_recursion_tail}, and
+% if so consumes all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop}
% (\emph{c.f.}~\cs{quark_if_recursion_tail_stop:n}).
% \item[nn] defines \cs[no-index]{\meta{name}:nn} such that it
-% checks if |#1| contains only \cs[no-index]{q\meta{namespace}_recursion_tail}, and
-% if so consumes all tokens up to \cs[no-index]{q\meta{namespace}_recursion_stop},
+% checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_recursion_tail}, and
+% if so consumes all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop},
% then executes the code |#2| after that
% (\emph{c.f.}~\cs{quark_if_recursion_tail_stop_do:nn}).
-% \item[nN] defines \cs[no-index]{\meta{name}:nN} such that it
-% checks if |#1| contains only \cs[no-index]{q\meta{namespace}_recursion_tail}, and
-% if so uses the \cs[no-index]{\meta{type}_map_break:} function |#2|
-% (\emph{c.f.}~\cs{quark_if_recursion_tail_break:nN}).
-% \cs[no-index]{q\meta{namespace}_recursion_stop} is not used in this case.
% \item[N] defines \cs[no-index]{\meta{name}:N} such that it
-% checks if |#1| is \cs[no-index]{q\meta{namespace}_recursion_tail}, and if so consumes
-% all tokens up to \cs[no-index]{q\meta{namespace}_recursion_stop}
+% checks if |#1| is \cs[no-index]{q__\meta{namespace}_recursion_tail}, and if so consumes
+% all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop}
% (\emph{c.f.}~\cs{quark_if_recursion_tail_stop:N}).
% \item[Nn] defines \cs[no-index]{\meta{name}:Nn} such that it
-% checks if |#1| is \cs[no-index]{q\meta{namespace}_recursion_tail}, and if so consumes
-% all tokens up to \cs[no-index]{q\meta{namespace}_recursion_stop}, then executes
+% checks if |#1| is \cs[no-index]{q__\meta{namespace}_recursion_tail}, and if so consumes
+% all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop}, then executes
% the code |#2| after that
% (\emph{c.f.}~\cs{quark_if_recursion_tail_stop_do:Nn}).
+% \end{description}
+% The last two are modeled after
+% \cs[no-index]{quark_if_recursion_tail_break:(n|N)N}, and in those
+% cases the quark \cs[no-index]{q__\meta{namespace}_recursion_stop} is
+% not used (and thus needs not be defined).
+% \begin{description}
+% \def\makelabel#1{\texttt{#1}}
+% \item[nN] defines \cs[no-index]{\meta{name}:nN} such that it
+% checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_recursion_tail}, and
+% if so uses the \cs[no-index]{\meta{type}_map_break:} function |#2|.
% \item[NN] defines \cs[no-index]{\meta{name}:NN} such that it
-% checks if |#1| is \cs[no-index]{q\meta{namespace}_recursion_tail}, and if so uses
-% the \cs[no-index]{\meta{type}_map_break:} function |#2|
-% (\emph{c.f.}~\cs{quark_if_recursion_tail_break:NN}).
-% \cs[no-index]{q\meta{namespace}_recursion_stop} is not used in this case.
+% checks if |#1| is \cs[no-index]{q__\meta{namespace}_recursion_tail}, and if so uses
+% the \cs[no-index]{\meta{type}_map_break:} function |#2|.
% \end{description}
% Any other signature, as well as a function without signature
% are errors, and in such case the definition is aborted.
-%
-% \cs{__kernel_quark_new_test:N} does \emph{not} define
-% the \cs[no-index]{q\meta{namespace}_recursion_tail} and
-% \cs[no-index]{q\meta{namespace}_recursion_stop}.
-% They should be manually defined with \cs{quark_new:N}.
% \end{function}
%
% \begin{function}{\__kernel_quark_new_conditional:Nn}
% \begin{syntax}
-% \cs{__kernel_quark_new_conditional:Nn} \cs[no-index]{\meta{name}:\meta{arg spec}} \Arg{conditions}
-% \end{syntax}
-% Defines a quark conditional \cs[no-index]{\meta{name}:\meta{arg spec}}
-% which tests if its argument is the \cs[no-index]{\meta{test-quark}},
-% and executes the appropriate \meta{condition}. \meta{conditions} is
-% a comma-separated list of one or more of |p|, |T|, |F|, and |TF|, and
-% defines one function for each \meta{condition} as described for
-% \cs{prg_new_conditional:Npnn}.
-% The \meta{name} of the function should indicate the \meta{namespace}
-% (module) and the name of the quark being tested. The name should
-% be of the form:
-% \begin{verbatim}
-% \__<module>_quark_if_<name>:<signature>
-% \end{verbatim}
-% where |<module>| is the identifier of the current module and |<name>|
-% is the name of the quark to be tested. The function will be defined
-% to test for the quark \cs[no-index]{q__<module>_<name>}.
-%
-% The \meta{arg spec} \emph{must} be one of the options listed
-% below. \cs[no-index]{\meta{test-quark}}
-% should be a valid quark, defined with \cs{quark_new:N}, and
-% \meta{namespace} should be the name space to be used internally
-% in the definition of auxiliaries (for example |__module|).
-%
-% \cs{__kernel_quark_new_conditional:Nn} can define $2$ different
-% types of quark-test functions. Which one is defined depends on
-% the \meta{arg spec} of the given function:
+% \cs{__kernel_quark_new_conditional:Nn} \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:\meta{arg spec}} \Arg{conditions}
+% \end{syntax}
+% Defines a collection of quark conditionals that test if their
+% argument is the quark \cs[no-index]{q__\meta{namespace}_\meta{name}}
+% and perform suitable actions. The \meta{conditions} are a
+% comma-separated list of one or more of |p|, |T|, |F|, and |TF|, and
+% one conditional is defined for each \meta{condition} in the list, as
+% described for \cs{prg_new_conditional:Npnn}. The conditionals are
+% defined using \cs{prg_new_conditional:Npnn}, so that their name is
+% obtained by adding |p|, |T|, |F|, or |TF| to the base name
+% \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:\meta{arg spec}}.
+%
+% The first argument of \cs{__kernel_quark_new_conditional:Nn} must
+% contain |_quark_if_| and |:|, as these markers are used to determine
+% the \meta{name} of the quark
+% \cs[no-index]{q__\meta{namespace}_\meta{name}} to be tested. This
+% quark should be manually defined with \cs{quark_new:N}, as
+% \cs{__kernel_quark_new_conditional:Nn} does \emph{not} define it.
+%
+% The function \cs{__kernel_quark_new_conditional:Nn} can define $2$
+% different types of quark conditionals. Which one is defined depends
+% on the \meta{arg spec}, which \emph{must} be one of the following
+% options, modeled after \cs[no-index]{quark_if_nil:(N|n)(TF)}.
% \begin{description}
% \def\makelabel#1{\texttt{#1}}
-% \item[n] defines \cs[no-index]{\meta{name}:n(TF)} such that it
-% checks if |#1| contains only \cs[no-index]{\meta{test-quark}}, and
+% \item[n] defines \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:n(TF)} such that it
+% checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_\meta{name}}, and
% executes the proper conditional branch.
-% (\emph{c.f.}~\cs[no-index]{quark_if_nil:n(TF)}).
-% \item[N] defines \cs[no-index]{\meta{name}:N(TF)} such that it
-% checks if |#1| is \cs[no-index]{\meta{test-quark}}, and
+% \item[N] defines \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:N(TF)} such that it
+% checks if |#1| is \cs[no-index]{q__\meta{namespace}_\meta{name}}, and
% executes the proper conditional branch.
-% (\emph{c.f.}~\cs[no-index]{quark_if_nil:N(TF)}).
% \end{description}
% Any other signature, as well as a function without signature
% are errors, and in such case the definition is aborted.
-%
-% \cs{__kernel_quark_new_conditional:Nn} does \emph{not} define
-% the \cs[no-index]{\meta{test-quark}}.
-% It~should be manually defined with \cs{quark_new:N}.
% \end{function}
%
% \begin{variable}{\c__kernel_randint_max_int}
More information about the latex3-commits
mailing list.