[latex3-commits] [git/LaTeX3-latex3-latex3] xparse: Initial text for l3cmd docs (d6d2a9e7a)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : xparse
Link       : https://github.com/latex3/latex3/commit/d6d2a9e7a2f932af9577b1c5b81a438b314e9e3c

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

commit d6d2a9e7a2f932af9577b1c5b81a438b314e9e3c
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Tue Mar 10 14:06:41 2020 +0000

    Initial text for l3cmd docs


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

d6d2a9e7a2f932af9577b1c5b81a438b314e9e3c
 l3kernel/doc/source3body.tex |   2 +
 l3kernel/l3cmd.dtx           | 117 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 119 insertions(+)

diff --git a/l3kernel/doc/source3body.tex b/l3kernel/doc/source3body.tex
index 4edd3d5b6..82094b1b3 100644
--- a/l3kernel/doc/source3body.tex
+++ b/l3kernel/doc/source3body.tex
@@ -499,4 +499,6 @@ used on top of \LaTeXe{} if \cs{outer} tokens are used in the arguments.
 \clist_gput_right:Nn \g_docinput_clist { l3deprecation.dtx }
 \ExplSyntaxOff
 
+\DocInput{l3cmd}
+
 \endinput
diff --git a/l3kernel/l3cmd.dtx b/l3kernel/l3cmd.dtx
index dfe3a74ce..e84dc09e1 100644
--- a/l3kernel/l3cmd.dtx
+++ b/l3kernel/l3cmd.dtx
@@ -51,6 +51,123 @@
 %
 % \begin{documentation}
 %
+% \section{Creating document commands}
+%
+% Document commands should be created using the tools provided by this module:
+% \cs{NewDocumentCommand}, etc.\@, in almost all cases. This allows clean
+% separation of document-level syntax from code-level interfaces. Users have
+% a need to create new document commands, and as such a significant amount of
+% documentation for \pkg{l3cmd} is provided as part of \texttt{usrguide3}. Here,
+% additional material aimed at programmers is provided
+%
+% \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 \enquote{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-delimter |<| 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{variable}{\ProcessedArgument}
+%   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}
+% \end{variable}
+%
+% \subsection{Access to the argument specification}
+%
+% The argument specifications for document commands and environments are
+% available for examination and use.
+%
+% \begin{function}{\GetDocumentCommandArgSpec, \GetDocumentEnvironmentArgSpec}
+%   \begin{syntax}
+%     \cs{GetDocumentCommandArgSpec} \meta{function}
+%     \cs{GetDocumentEnvironmentArgSpec} \meta{environment}
+%   \end{syntax}
+%   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.
+% \end{function}
+%
+% \begin{function}
+%   {\ShowDocumentCommandArgSpec,  \ShowDocumentEnvironmentArgSpec}
+%   \begin{syntax}
+%     \cs{ShowDocumentCommandArgSpec} \meta{function}
+%     \cs{ShowDocumentEnvironmentArgSpec} \meta{environment}
+%   \end{syntax}
+%   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{function}
+%
 % \end{documentation}
 %
 % \begin{implementation}