[latex3-commits] [latex3/latex2e] develop: Refinements to description of \NewDocumentCommand, etc. (issue #853) (abf96e9b)
github at latex-project.org
github at latex-project.org
Fri Jun 9 08:16:31 CEST 2023
Repository : https://github.com/latex3/latex2e
On branch : develop
Link : https://github.com/latex3/latex2e/commit/abf96e9b88d2d3916711f723e352c3529d345321
>---------------------------------------------------------------
commit abf96e9b88d2d3916711f723e352c3529d345321
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Fri Jun 9 07:16:31 2023 +0100
Refinements to description of \NewDocumentCommand, etc. (issue #853)
>---------------------------------------------------------------
abf96e9b88d2d3916711f723e352c3529d345321
base/changes.txt | 5 +++++
base/doc/usrguide.tex | 29 +++++++++++++++--------------
2 files changed, 20 insertions(+), 14 deletions(-)
diff --git a/base/changes.txt b/base/changes.txt
index b1c06078..86fda4e1 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,11 @@ completeness or accuracy and it contains some references to files that
are not part of the distribution.
================================================================================
+2023-06-09 Joseph Wright <Joseph.Wright at latex-project.org>
+
+ * usrguide.txt
+ Various refinements to descriptions of \NewDocumentCommand, etc.
+
================================================================================
All changes above are only part of the development branch for the next release.
================================================================================
diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex
index 42d5e401..5577be9f 100644
--- a/base/doc/usrguide.tex
+++ b/base/doc/usrguide.tex
@@ -142,7 +142,7 @@ arguments. The mandatory types
is read between two identical characters, which cannot be any of |%|, |\|,
|#|, |{|, |}| or \verb*| |. The verbatim argument can also be enclosed
between braces, |{| and |}|. A command with a verbatim argument will
- produce an error when it appears within an argument of another function.
+ produce an error when it appears within an argument of another command.
\item[\texttt{b}] Only suitable in the argument specification of an
environment, it denotes the body of the environment, between
|\begin|\marg{environment} and |\end|\marg{environment}. See
@@ -244,7 +244,7 @@ defined.
\item \cs{RenewDocumentCommand} will issue an error if \meta{cmd}
has not previously been defined.
\item \cs{ProvideDocumentCommand} creates a new definition for
- \meta{function} only if one has not already been given.
+ \meta{cmd} only if one has not already been given.
\item \cs{DeclareDocumentCommand} will always create the new
definition, irrespective of any existing \meta{cmd} with the
same name. This should be used sparingly.
@@ -619,7 +619,8 @@ Spaces are trimmed at each end of each item parsed.
The \texttt{E} argument type is somewhat special, because with a single
\texttt{E} in the command declaration you may end up with several
arguments in a command (one formal argument per embellishment token).
-Therefore, when an argument processor is applied to an \texttt{E}-type
+Therefore, when an argument processor is applied to an
+\texttt{e}/\texttt{E}-type
argument, all the arguments pass through that processor before being fed
to the \meta{code}. For example, this command
\begin{verbatim}
@@ -640,9 +641,9 @@ processed argument can be further processed using a mapping function
\NewDocumentCommand \foo {>{\SplitList{;}} m}
{\MappingFunction#1}
\end{verbatim}
-If only a single character \meta{token} is used for the split, any
-category code $13$ (active) character matching the \meta{token} will
-be replaced before the split takes place.
+If only a single character \meta{token} is used for the split, it will
+take account of the possibility that the \meta{token} has been made active
+(category code~$13$) and will split at such tokens.
Spaces are trimmed at each end of each item parsed. Exactly one set
of braces will be stripped if an entire item is surrounded by them,
i.e.~the following inputs and outputs result (each separte item as
@@ -658,11 +659,11 @@ a,{b}c ==> {a}{{b}c}
\end{verbatim}
\begin{decl}
- |\ProcessList| \arg{list} \arg{function}
+ |\ProcessList| \arg{list} \arg{cmd}
\end{decl}
To support \cs{SplitList}, the function \cs{ProcessList} is available
-to apply a \meta{function} to every entry in a \meta{list}. The
-\meta{function} should absorb one argument: the list entry. For example
+to apply a \meta{cmd} to every entry in a \meta{list}. The
+\meta{cmd} should absorb one argument: the list entry. For example
\begin{verbatim}
\NewDocumentCommand \foo {>{\SplitList{;}} m}
{\ProcessList{#1}{\SomeDocumentCommand}}
@@ -751,10 +752,10 @@ This facility should only be used when \emph{necessary}.
|\ProvideExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
|\DeclareExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code}
\end{decl}
-This family of commands is used to create a document-level \meta{function},
+This family of commands is used to create a document-level \meta{cmd},
which will grab its arguments in a fully-expandable manner. The
argument specification for the function is given by \meta{arg spec},
-and the function will execute \meta{code}. In general, \meta{code} will
+and the \meta{cmd} will execute \meta{code}. In general, \meta{code} will
also be fully expandable, although it is possible that this will
not be the case (for example, a function for use in a table might
expand so that \cs{omit} is the first non-expandable non-space token).
@@ -832,7 +833,7 @@ and the command call is aborted.
\subsubsection{Control sequence tokens}
-A control sequence (or control character) token is characterized by is
+A control sequence (or control character) token is characterized by
its name, and its meaning is its definition.
A token cannot have two different meanings at the same time.
When a control sequence is defined as delimiter in a command,
@@ -885,7 +886,7 @@ available for examination and use.
|\GetDocumentCommandArgSpec| \arg{cmd} \\
|\GetDocumentEnvironmentArgSpec| \arg{environment}
\end{decl}
-These functions transfer the current argument specification for the
+These commands transfer the current argument specification for the
requested \meta{cmd} or \meta{environment} into the token list
variable \cs{ArgumentSpecification}. If the \meta{cmd} or
\meta{environment} has no known argument specification then an error
@@ -896,7 +897,7 @@ the current \TeX{} group.
|\ShowDocumentCommandArgSpec| \arg{cmd} \\
|\ShowDocumentEnvironmentArgSpec| \arg{environment}
\end{decl}
-These functions show the current argument specification for the
+These commands show the current argument specification for the
requested \meta{cmd} or \meta{environment} at the terminal. If
the \meta{cmd} or \meta{environment} has no known argument
specification then an error is issued.
More information about the latex3-commits
mailing list.