[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: broadened the documentation about \ExpandArgs somewhat (cdfd27f7)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : develop
Link       : https://github.com/latex3/latex2e/commit/cdfd27f7fcbe5814f02661522dcd8f5f1cb78981

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

commit cdfd27f7fcbe5814f02661522dcd8f5f1cb78981
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Fri Jan 7 00:46:23 2022 +0100

    broadened the documentation about \ExpandArgs somewhat


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

cdfd27f7fcbe5814f02661522dcd8f5f1cb78981
 base/doc/usrguide3.tex | 37 ++++++++++++++++++++++++++++---------
 1 file changed, 28 insertions(+), 9 deletions(-)

diff --git a/base/doc/usrguide3.tex b/base/doc/usrguide3.tex
index 01196801..f31fbad1 100644
--- a/base/doc/usrguide3.tex
+++ b/base/doc/usrguide3.tex
@@ -794,14 +794,10 @@ also the actual payload code and in case of commands declared with
 about the argument signature.
 
 
-\section{Preconstructing command names}
+\section[Preconstructing command names \\ (or otherwise expanding arguments)]
+        {Preconstructing command names (or otherwise expanding arguments)}
 \label{sec:preconstructing-csnames}
 
-\begin{decl}
-  |\UseName|  \arg{string} \\
-  |\ExpandArgs| \arg{spec} \arg{cmd} \arg{string1} \dots
-\end{decl}
-
 When declaring new commands with \cs{NewDocumentCommand} or
 \cs{NewCommandCopy} or similar, it is sometimes necessary to
 ``construct'' the csname. As a general mechanism the L3 programming
@@ -810,15 +806,20 @@ it if \cs{ExplSyntaxOn} is not active (and mixing programming and user
 interface level commands is not a good approach anyhow). We therefore
 offer a mechanism to access this ability using CamelCase naming.
 
+\begin{decl}
+  |\UseName|  \arg{string} \\
+  |\ExpandArgs| \arg{spec} \arg{cmd} \arg{arg1} \dots
+\end{decl}
+
 \cs{UseName} turns the \meta{string} directly into a csname and
 then executes it: this is equivalent to the long-standing
 \LaTeXe{} internal command \cs{@nameuse}, or the L3 programming
 equivalent \cs{use:c}. \cs{ExpandArgs} takes a \meta{spec} which
-describes how to expand the \meta{strings}, carries out these
+describes how to expand the \meta{arguments}, carries out these
 operations then executes the \meta{cmd}. The \meta{spec} uses
 the descriptions offered by the L3 programming layer, and the
 relevant \cs{exp_args:N...} function must exist. Common cases will
-have a \meta{spec} of \texttt{c} or \texttt{cc}: see below.
+have a \meta{spec} of \texttt{c}, \texttt{cc} or \texttt{Nc}: see below.
 
 As an example, the following declaration provides a method to generate
 copyedit commands:
@@ -835,7 +836,7 @@ copyedit commands:
 \end{verbatim}
 Given that declaration you can then write
 \verb/\newcopyedit{note}[blue]/ which defines the command \cs{note}
-and corresponding counter for you.
+and the corresponding counter for you.
 
 A second example is to copy a command by string name using
 \cs{NewCommandCopy}: here we might need to construct both command
@@ -845,6 +846,24 @@ names.
   {\ExpandArgs{cc}\NewCommandCopy{saved#1}{#1}}
 \end{verbatim}
 
+In the \meta{spec} each \texttt{c} stands for one argument that is
+turned into a `\texttt{c}'ommand. An \texttt{n} represents a
+`\texttt{n}'ormal argument that is not altered and \texttt{N} stands for
+a `\texttt{N}'ormal argument which is also left unchanged, but one
+consisting only of a single token (and usually unbraced). Thus, to
+construct a command from a string only for the second argument of
+\cs{NewCommandCopy} you would write
+\begin{verbatim}
+\ExpandArgs{Nc}\NewCommandCopy\mysectionctr{c at section}
+\end{verbatim}
+There are several other single letters supported in the L3 programming
+layer that \emph{could} be used in the \meta{spec} to manipulate
+arguments in other ways.  If you are interested take a look at the
+\enquote{Argument expansion} section in the L3 programming layer
+documentation in \texttt{interface3.pdf}.
+
+
+
 \section{Expandable floating point (and other) calculations}
 
 The \LaTeX3 programming layer which is part of the format offers a