[latex3-commits] [git/LaTeX3-latex3-latex2e] cmd: More text for usrguide3 (71c63603)

[Joseph Wright]

Repository : https://github.com/latex3/latex2e
On branch  : cmd
Link       : https://github.com/latex3/latex2e/commit/71c63603d0b889384695ce78d9fd6e03e9fc08f6

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

commit 71c63603d0b889384695ce78d9fd6e03e9fc08f6
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Nov 25 13:49:45 2020 +0000

    More text for usrguide3
    
    This will leave just the code to go into ltcmd.


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

71c63603d0b889384695ce78d9fd6e03e9fc08f6
 base/doc/usrguide3.tex | 104 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)

diff --git a/base/doc/usrguide3.tex b/base/doc/usrguide3.tex
index 53306031..4731f6b4 100644
--- a/base/doc/usrguide3.tex
+++ b/base/doc/usrguide3.tex
@@ -570,4 +570,108 @@ available:
     in the standard version.
 \end{itemize}
 
+\subsection{Details about argument delimiters}
+
+In normal (non-expandable) commands, the delimited types look for the
+initial delimiter by peeking ahead (using \pkg{expl3}'s |\peek_...|
+functions) looking for the delimiter token.  The token has to have the
+same meaning and `shape' of the token defined as delimiter.
+There are three possible cases of delimiters: character tokens, control
+sequence tokens, and active character tokens.  For all practical purposes
+of this description, active character tokens will behave exactly as
+control sequence tokens.
+
+\subsubsection{Character tokens}
+
+A character token is characterised by its character code, and its meaning
+is the category code~(|\catcode|).  When a command is defined, the meaning
+of the character token is fixed into the definition of the command and
+cannot change.  A command will correctly see an argument delimiter if
+the open delimiter has the same character and category codes as at the
+time of the definition.  For example in:
+\begin{verbatim}
+  \NewDocumentCommand { \foobar } { D<>{default} } {(#1)}
+  \foobar <hello> \par
+  \char_set_catcode_letter:N <
+  \foobar <hello>
+\end{verbatim}
+the output would be:
+\begin{verbatim}
+  (hello)
+  (default)<hello>
+\end{verbatim}
+as the open-delimiter |<| changed in meaning between the two calls to
+|\foobar|, so the second one doesn't see the |<| as a valid delimiter.
+Commands assume that if a valid open-delimiter was found, a matching
+close-delimiter will also be there.  If it is not (either by being
+omitted or by changing in meaning), a low-level \TeX{} error is raised
+and the command call is aborted.
+
+\subsubsection{Control sequence tokens}
+
+A control sequence (or control character) token is characterised by is
+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,
+it will be detected as delimiter whenever the control sequence name
+is found in the document regardless of its current definition.
+For example in:
+\begin{verbatim}
+  \cs_set:Npn \x { abc }
+  \NewDocumentCommand { \foobar } { D\x\y{default} } {(#1)}
+  \foobar \x hello\y \par
+  \cs_set:Npn \x { def }
+  \foobar \x hello\y
+\end{verbatim}
+the output would be:
+\begin{verbatim}
+  (hello)
+  (hello)
+\end{verbatim}
+with both calls to the command seeing the delimiter |\x|.
+
+\subsection{Creating new argument processors}
+
+\begin{decl}
+  |\ProcessedArgument| 
+\end{decl}
+Argument processors allow manipulation of a grabbed argument before it is
+passed to the underlying code. New processor implementations may be created
+as functions which take one trailing argument, and which leave their result in
+the \cs{ProcessedArgument} variable. For example, \cs{ReverseBoolean} is
+defined as
+\begin{verbatim}
+  \cs_new_protected:Npn \ReverseBoolean #1
+    {
+      \bool_if:NTF #1
+        { \tl_set:Nn \ProcessedArgument { \c_false_bool } }
+        { \tl_set:Nn \ProcessedArgument { \c_true_bool } }
+    }
+\end{verbatim}
+
+\subsection{Access to the argument specification}
+
+The argument specifications for document commands and environments are
+available for examination and use.
+
+\begin{decl}
+  |\GetDocumentCommandArgSpec| \arg{function}
+  |\GetDocumentEnvironmentArgSpec| \arg{environment}
+\end{decl}
+These functions transfer the current argument specification for the
+requested \meta{function} or \meta{environment} into the token list
+variable \cs{ArgumentSpecification}. If the \meta{function} or
+\meta{environment} has no known argument specification then an error
+is issued. The assignment to \cs{ArgumentSpecification} is local to
+the current \TeX{} group.
+
+\begin{decl}
+  |\ShowDocumentCommandArgSpec| \arg{function}
+  |\ShowDocumentEnvironmentArgSpec| \arg{environment}
+\end{decl}
+These functions show the current argument specification for the
+requested \meta{function} or \meta{environment} at the terminal. If
+the \meta{function} or \meta{environment} has no known argument
+specification then an error is issued.
+
 \end{document}