[latex3-commits] [git/LaTeX3-latex3-latex3] master: Clarify documentation of c-type and v-type arguments (fixes #457) (5ff07ad)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/5ff07ad7221eb44a9309ff2e9dfeb122f9584dcd

>---------------------------------------------------------------

commit 5ff07ad7221eb44a9309ff2e9dfeb122f9584dcd
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Sun Apr 29 14:58:26 2018 -0400

    Clarify documentation of c-type and v-type arguments (fixes #457)


>---------------------------------------------------------------

5ff07ad7221eb44a9309ff2e9dfeb122f9584dcd
 l3kernel/expl3.dtx    |   13 ++++++-------
 l3kernel/l3basics.dtx |   21 +++++++++++++--------
 l3kernel/l3expan.dtx  |   47 ++++++++++++++++++++++++++++++++++++-----------
 3 files changed, 55 insertions(+), 26 deletions(-)

diff --git a/l3kernel/expl3.dtx b/l3kernel/expl3.dtx
index 840bc54..29fe897 100644
--- a/l3kernel/expl3.dtx
+++ b/l3kernel/expl3.dtx
@@ -575,11 +575,11 @@
 % arguments before passing it to the base function:
 % \begin{description}
 %   \item[c] Character string used as a command name.\\ The argument (a
-%     token or braced token list) must, when fully expanded, produce a
-%     sequence of characters which is then used to construct a command
-%     name (\emph{via}~\tn{csname} \ldots \tn{endcsname}).
-%     This command name is the
-%     single token that is passed to the function as the argument. Hence
+%     token or braced token list) is \emph{fully expanded}; the result
+%     must be a sequence of characters which is then used to construct a
+%     command name (\emph{via}~\tn{csname} \ldots \tn{endcsname}).  This
+%     command name is a single token that is passed to the function as
+%     the argument. Hence
 %     \begin{quote}
 %       \cs{seq_gpush:cV} |{ g_file_name_seq }| \cs{l_tmpa_tl}
 %     \end{quote}
@@ -587,8 +587,7 @@
 %     \begin{quote}
 %       \cs{seq_gpush:NV} |\g_file_name_seq| \cs{l_tmpa_tl}.
 %     \end{quote}
-%     Remember that \texttt{c} arguments are \emph{fully expanded} by
-%     \TeX{} when creating csnames. This means that (a) the entire
+%     Full expansion means that (a) the entire
 %     argument must be expandable and (b) any variables are
 %     converted to their content. So the preceding examples are also
 %     equivalent to
diff --git a/l3kernel/l3basics.dtx b/l3kernel/l3basics.dtx
index f61ee75..622b5c1 100644
--- a/l3kernel/l3basics.dtx
+++ b/l3kernel/l3basics.dtx
@@ -704,14 +704,19 @@
 %   \begin{syntax}
 %     \cs{use:c} \Arg{control sequence name}
 %   \end{syntax}
-%   Converts the given \meta{control sequence name} into a single
-%   control sequence token. This process requires two expansions.
-%   The content for \meta{control sequence name} may be literal
-%   material or from other expandable functions. The
-%   \meta{control sequence name} must, when fully expanded, consist
-%   of character tokens which are not active: typically
-%   of category code $10$ (space), $11$ (letter)
-%   or $12$ (other), or a mixture of these.
+%   Expands the \meta{control sequence name} until only characters
+%   remain, and then converts this into a control sequence. This process
+%   requires two expansions.  As in other \texttt{c}-type arguments the
+%   \meta{control sequence name} must, when fully expanded, consist of
+%   character tokens, typically a mixture of category code $10$ (space),
+%   $11$ (letter) and $12$ (other).
+%   \begin{texnote}
+%     Protected macros that appear in a \texttt{c}-type argument are
+%     expanded despite being protected; \cs{exp_not:n} also has no
+%     effect.  An internal error occurs if non-characters or active
+%     characters remain after full expansion, as the conversion to a
+%     control sequence is not possible.
+%   \end{texnote}
 % \end{function}
 %
 % As an example of the \cs{use:c} function, both
diff --git a/l3kernel/l3expan.dtx b/l3kernel/l3expan.dtx
index 710a17f..a132d6c 100644
--- a/l3kernel/l3expan.dtx
+++ b/l3kernel/l3expan.dtx
@@ -290,14 +290,20 @@
 %   \end{syntax}
 %   This function absorbs two arguments (the \meta{function} name and
 %   the \meta{tokens}). The \meta{tokens} are expanded until only characters
-%   remain, and are then turned into a control sequence. (An internal error
-%   occurs if non-characters remain, as the conversion is not possible.)
+%   remain, and are then turned into a control sequence.
 %   The result is inserted into the input stream \emph{after} reinsertion
 %   of the \meta{function}. Thus the \meta{function} may take more than
 %   one argument: all others are left unchanged.
 %
 %   The |:cc| variant constructs the \meta{function} name in the same
 %   manner as described for the \meta{tokens}.
+%   \begin{texnote}
+%     Protected macros that appear in a \texttt{c}-type argument are
+%     expanded despite being protected; \cs{exp_not:n} also has no
+%     effect.  An internal error occurs if non-characters or active
+%     characters remain after full expansion, as the conversion to a
+%     control sequence is not possible.
+%   \end{texnote}
 % \end{function}
 %
 % \begin{function}[EXP]{\exp_args:No}
@@ -328,13 +334,19 @@
 %   \end{syntax}
 %   This function absorbs two arguments (the \meta{function} name and
 %   the \meta{tokens}). The \meta{tokens} are expanded until only characters
-%   remain, and are then turned into a control sequence. (An internal error
-%   occurs if non-characters remain, as the conversion is not possible.)
+%   remain, and are then turned into a control sequence.
 %   This control sequence should
 %   be the name of a \meta{variable}.   The content of the \meta{variable} are
 %   recovered and placed inside braces into the input stream \emph{after}
 %   reinsertion of the \meta{function}. Thus the \meta{function} may take more
 %   than one argument: all others are left unchanged.
+%   \begin{texnote}
+%     Protected macros that appear in a \texttt{v}-type argument are
+%     expanded despite being protected; \cs{exp_not:n} also has no
+%     effect.  An internal error occurs if non-characters or active
+%     characters remain after full expansion, as the conversion to a
+%     control sequence is not possible.
+%   \end{texnote}
 % \end{function}
 %
 % \begin{function}[EXP]{\exp_args:Nf}
@@ -606,10 +618,16 @@
 %     \cs{exp_not:c} \Arg{tokens}
 %   \end{syntax}
 %   Expands the \meta{tokens} until only characters remain, and then
-%   converts this into a control sequence. (An internal error occurs if
-%   non-characters remain, as the conversion is not possible.)
+%   converts this into a control sequence.
 %   Further expansion of this control sequence is then inhibited using
 %   \cs{exp_not:N}.
+%   \begin{texnote}
+%     Protected macros that appear in a \texttt{c}-type argument are
+%     expanded despite being protected; \cs{exp_not:n} also has no
+%     effect.  An internal error occurs if non-characters or active
+%     characters remain after full expansion, as the conversion to a
+%     control sequence is not possible.
+%   \end{texnote}
 % \end{function}
 %
 % \begin{function}[EXP]{\exp_not:n}
@@ -617,9 +635,10 @@
 %     \cs{exp_not:n} \Arg{tokens}
 %   \end{syntax}
 %   Prevents expansion of the \meta{tokens} in an |x|-type argument.  In
-%   other cases (input stream or |o| or |f| arguments) the \meta{tokens}
-%   continue being expanded.
-%   The argument of \cs{exp_not:n} \emph{must} be surrounded by braces.
+%   all other cases the \meta{tokens} continue to be expanded, for
+%   example in the input stream or in other types of arguments such as
+%   \texttt{c}, \texttt{f}, \texttt{v}.  The argument of \cs{exp_not:n}
+%   \emph{must} be surrounded by braces.
 %   \begin{texnote}
 %     This is the \eTeX{} \tn{unexpanded} primitive.  In an
 %     |x|-expanding definition (\cs{cs_new:Npx}), \cs{exp_not:n}~|{#1}|
@@ -650,10 +669,16 @@
 %   \end{syntax}
 %   Expands the \meta{tokens} until only characters remains, and then
 %   converts this into a control sequence which should be a \meta{variable}
-%   name. (An internal error occurs if
-%   non-characters remain, as the conversion is not possible.)
+%   name.
 %   The content of the \meta{variable} is recovered, and further
 %   expansion in |x|-type arguments is prevented using \cs{exp_not:n}.
+%   \begin{texnote}
+%     Protected macros that appear in a \texttt{v}-type argument are
+%     expanded despite being protected; \cs{exp_not:n} also has no
+%     effect.  An internal error occurs if non-characters or active
+%     characters remain after full expansion, as the conversion to a
+%     control sequence is not possible.
+%   \end{texnote}
 % \end{function}
 %
 % \begin{function}[EXP]{\exp_not:f}