[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: a bit more docu on \ExpandNc and friends (cdc831ca)

[Frank Mittelbach]

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

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

commit cdc831ca47c09f59a0f2a43b785882c6fe010750
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Mon Jan 3 00:57:02 2022 +0100

    a bit more docu on \ExpandNc and friends


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

cdc831ca47c09f59a0f2a43b785882c6fe010750
 base/doc/usrguide3.tex | 53 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/base/doc/usrguide3.tex b/base/doc/usrguide3.tex
index 7d12958a..abe73b8d 100644
--- a/base/doc/usrguide3.tex
+++ b/base/doc/usrguide3.tex
@@ -34,10 +34,10 @@
 \usepackage{csquotes}
 
 \title{New \LaTeX\ methods for authors (starting 2020)}
-\author{\copyright~Copyright 2020-2021, \LaTeX\ Project Team.\\
+\author{\copyright~Copyright 2020-2022, \LaTeX\ Project Team.\\
    All rights reserved.}
 
-\date{2021-12-28}
+\date{2022-01-03}
 
 \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
 \NewDocumentCommand\marg{m}{\arg{#1}}
@@ -240,6 +240,11 @@ defined.
    same name.  This should be used sparingly.
 \end{itemize}
 
+If the \meta{cmd} can't be provided as a single token but needs
+\enquote{constructing}, you can use \cs{ExpandNc} as explained in
+Section~\ref{sec:preconstructing-csnames} which also gives an example
+in which this is needed.
+
 \begin{decl}
   |\NewDocumentEnvironment|     \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\
   |\RenewDocumentEnvironment|   \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\
@@ -729,22 +734,62 @@ specification then an error is issued.
 
 \section{Copying and showing (robust) commands}
 
+If you want to (slightly) alter an existing command you may want to
+save the current definition under a new name and then use that in a
+new definition. If the existing command is robust, then the old trick of
+using the low-level \cs{let} for this doesn't work, because it only
+copies the top-level definition, but not the part that actually does
+the work. As most \LaTeX{} commands are nowadays robust, \LaTeX{}
+now offers some high-level declarations for this instead.
+
 \begin{decl}
   |\NewCommandCopy|       \arg{cmd} \arg{existing-cmd} \\
   |\RenewCommandCopy|     \arg{cmd} \arg{existing-cmd} \\
   |\DeclareCommandCopy|   \arg{cmd} \arg{existing-cmd}
 \end{decl}
 
-\emph{documentation to write}
+This copies the definition of \meta{existing-cmd} to \meta{cmd}. After
+this \meta{existing-cmd} can be redefined and \meta{cmd}
+still works! This allows you to then provide a new definition for
+\meta{existing-cmd} that makes use of \meta{cmd} (i.e., of its old
+definition). For example, after
+\begin{verbatim}
+  \NewCommandCopy\LaTeXorig\LaTeX
+  \RenewDocumentCommand\LaTeX{}{\textcolor{blue}{\LaTeXorig}}
+\end{verbatim}
+all \LaTeX{} logos generated with \cs{LaTeX} will come out in blue
+(assuming you have a color package loaded).
+
+The differences between \cs{New...} and \cs{Renew...} are as
+elsewhere: i.e., you get an error depending on whether or not
+\meta{cmd} already exists, or in case of \cs{Declare...} it is copied
+regardless. Note that there is no \cs{Provide...} declaration, because
+that would be of limited value.
+
+
+If the \meta{cmd} or \meta{existing-cmd} can't be provided as a single
+token but need \enquote{constructing}, you can use \cs{ExpandNc},
+\cs{ExpandNNc}, or \cs{ExpandNcc} as explained in
+Section~\ref{sec:preconstructing-csnames}.
+
+
+
 
 \begin{decl}
   |\ShowCommand|       \arg{cmd}
 \end{decl}
 
-\emph{documentation to write}
+This displays the meaning of the \meta{cmd} on the terminal and then
+stops (just like the primitive \cs{show}). The difference is that it
+correctly shows the meaning of more complex commands, e.g., in case of
+robusts commands it displays not only the top-level definition but
+also the actual payload code and in case of commands declared with
+\cs{NewDocumentCommand}, etc.\ it also gives you detailed information
+about the argument signature.
 
 
 \section{Preconstructing command names}
+\label{sec:preconstructing-csnames}
 
 \begin{decl}
   |\Expandc|               \arg{string} \\