[latex3-commits] [git/LaTeX3-latex3-latex2e] cmd2: Add usrguide3 (92ee6571)

Joseph Wright joseph.wright at morningstar2.co.uk
Wed Dec 2 16:50:55 CET 2020

Repository : https://github.com/latex3/latex2e
On branch  : cmd2
Link       : https://github.com/latex3/latex2e/commit/92ee6571c2cd6db78f11f10351e6d5c7f29ea5bf


commit 92ee6571c2cd6db78f11f10351e6d5c7f29ea5bf
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Dec 2 15:50:19 2020 +0000

    Add usrguide3


 base/build.lua         |   1 +
 base/changes.txt       |   5 +
 base/doc/usrguide3.tex | 677 +++++++++++++++++++++++++++++++++++++++++++++++++
 base/manifest.txt      |   1 +
 4 files changed, 684 insertions(+)

diff --git a/base/build.lua b/base/build.lua
index 187f7f00..cde31b50 100644
--- a/base/build.lua
+++ b/base/build.lua
@@ -109,6 +109,7 @@ typesetfiles   =
+    "usrguide3.tex",
diff --git a/base/changes.txt b/base/changes.txt
index 6e6a82ec..568c7595 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.
+2020-11-25  Joseph Wright  <Joseph.Wright at latex-project.org>
+        * usrguide3.tex
+          New file to document ltcmd
 2020-10-26  Frank Mittelbach  <Frank.Mittelbach at latex-project.org>
 	* ltmiscen.dtx (subsection{Environments}):
diff --git a/base/doc/usrguide3.tex b/base/doc/usrguide3.tex
new file mode 100644
index 00000000..4731f6b4
--- /dev/null
+++ b/base/doc/usrguide3.tex
@@ -0,0 +1,677 @@
+% \iffalse meta-comment
+% Copyright (C) 2020
+% The LaTeX3 Project and any individual authors listed elsewhere
+% in this file.
+% This file is part of the LaTeX base system.
+% -------------------------------------------
+% It may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3c
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+%    http://www.latex-project.org/lppl.txt
+% and version 1.3c or later is part of all distributions of LaTeX
+% version 2008 or later.
+% This file has the LPPL maintenance status "maintained".
+% The list of all files belonging to the LaTeX base distribution is
+% given in the file `manifest.txt'. See also `legal.txt' for additional
+% information.
+% The list of derived (unpacked) files belonging to the distribution
+% and covered by LPPL is defined by the unpacking scripts (with
+% extension .ins) which are part of the distribution.
+% \fi
+% Filename: usrguide3.tex
+\title{\LaTeX3 methods for authors}
+\author{\copyright~Copyright 2020, \LaTeX\ Project Team.\\
+   All rights reserved.}
+\date{Released 2020-11-20}
+% Fix a 'feature'
+\renewcommand \verbatim at font {\normalfont \ttfamily}
+\LaTeXe{} was released in 1994 and added a number of then-new concepts to
+\LaTeX{}. These are described in \texttt{usrguide}, which has largely remained
+unchanged. Since then, the \LaTeX{} team have worked on a number of ideas,
+firstly a programming language for \LaTeX{} (\pkg{expl3}) and then a range of
+tools for document authors which build on that language. Here, we describe
+\emph{stable} and \emph{widely-usable} concepts that have resulted from that
+work. These `new' ideas have been transferred from development packages
+into the \LaTeXe{} kernel. As such, they are now available to \emph{all}
+\LaTeX{} users and have the \emph{same stability} as any other part of the
+kernel. The fact that `behind the scenes' they are built on \pkg{expl3}
+is useful for the development team, but is not directly important to users.
+\section{Creating document commands and environments}
+Creating document commands and environments using the \LaTeX3 toolset is based
+around the idea that a common set of descriptions can be used to cover almost
+all argument types used in real documents. Thus parsing is reduced to a simple
+description of which arguments a command takes: this description provides the
+`glue' between the document syntax and the implementation of the
+First, we will describe the argument types, then move on to explain how these
+can be used to create both document commands and environments. Various more
+specialised features are then described, which allow an even richer application
+of a simple interface set up.
+The details here are intended to help users create document commands in
+general. More technical detail, suitable for \TeX{} programmers, is included
+in \texttt{interface3}.
+\subsection{Describing argument types}
+In order to allow each argument to be defined independently, the parser does
+not simply need to know the number of arguments for a function, but also the
+nature of each one. This is done by constructing an \emph{argument
+specification}, which defines the number of arguments, the type of each
+argument and any additional information needed for the parser to read the user
+input and properly pass it through to internal functions.
+The basic form of the argument specifier is a list of letters, where each
+letter defines a type of argument. As will be described below, some of the
+types need additional information, such as default values. The argument types
+can be divided into two, those which define arguments that are mandatory
+(potentially raising an error if not found) and those which define optional
+arguments. The mandatory types
+  \item[\texttt{m}] A standard mandatory argument, which can either be a single token
+    alone or multiple tokens surrounded by curly braces |{}|. Regardless of the
+    input, the argument will be passed to the internal code without the outer
+    braces. This is the type specifier for a normal \TeX{} argument.
+  \item[\texttt{r}] Given as \texttt{r}\meta{token1}\meta{token2}, this denotes a
+    `required' delimited argument, where the delimiters are
+    \meta{token1} and \meta{token2}. If the opening delimiter \meta{token1} is
+    missing, the default marker |-NoValue-| will be inserted after a suitable
+    error.
+  \item[\texttt{R}] Given as \texttt{R}\meta{token1}\meta{token2}\marg{default},
+    this is a `required' delimited argument as for~\texttt{r},
+    but it has a user-definable recovery \meta{default} instead of
+    |-NoValue-|.
+  \item[\texttt{v}] Reads an argument `verbatim', between the following
+    character and its next occurrence, in a way similar to the argument
+    of the \LaTeXe{} command \cs{verb}. Thus a \texttt{v}-type argument
+    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.
+  \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
+    Section~\ref{sec:cmd:body} for details.
+The types which define optional arguments are:
+  \item[\texttt{o}] A standard \LaTeX{} optional argument, surrounded with square
+    brackets, which will supply the special |-NoValue-| marker if not given
+    (as described later).
+  \item[\texttt{d}] Given as \texttt{d}\meta{token1}\meta{token2}, an optional
+    argument which is delimited by \meta{token1} and \meta{token2}. As with
+    \texttt{o}, if no value is given the special marker |-NoValue-| is
+    returned.
+  \item[\texttt{O}] Given as \texttt{O}\marg{default}, is like \texttt{o}, but returns
+    \meta{default} if no value is given.
+  \item[\texttt{D}] Given as \texttt{D}\meta{token1}\meta{token2}\marg{default}, it is
+    as for \texttt{d}, but returns \meta{default} if no value is given.
+    Internally, the \texttt{o}, \texttt{d} and \texttt{O} types are
+    short-cuts to an appropriated-constructed \texttt{D} type argument.
+  \item[\texttt{s}] An optional star, which will result in a value
+    \cs{BooleanTrue} if a star is present and \cs{BooleanFalse}
+    otherwise (as described later).
+  \item[\texttt{t}] An optional \meta{token}, which will result in a value
+    \cs{BooleanTrue} if \meta{token} is present and \cs{BooleanFalse}
+    otherwise. Given as \texttt{t}\meta{token}.
+  \item[\texttt{e}] Given as \texttt{e}\marg{tokens}, a set of optional
+    \emph{embellishments}, each of which requires a \emph{value}.
+    If an embellishment is not present, |-NoValue-| is returned.  Each
+    embellishment gives one argument, ordered as for the list of
+    \meta{tokens} in the argument specification.  All \meta{tokens}
+    must be distinct.
+  \item[\texttt{E}] As for \texttt{e} but returns one or more \meta{defaults}
+    if values are not given: \texttt{E}\marg{tokens}\marg{defaults}. See
+    Section~\ref{sec:cmd:embellishment} for more details.
+\subsection{Modifying argument descriptions}
+In addition to the argument \emph{types} discussed above, the argument
+description also gives special meaning to three other characters.
+First, \texttt{+} is used to make an argument long (to accept paragraph
+tokens). In contrast to \cs{newcommand}, this applies on an
+argument-by-argument basis. So modifying the example to `|s o o +m O{default}|'
+means that the mandatory argument is now \cs{long}, whereas the optional
+arguments are not.
+Secondly, \texttt{!} is used to control whether spaces are allowed before
+optional arguments. There are some subtleties to this, as \TeX{} itself
+has some restrictions on where spaces can be `detected': more detail
+is given in Section~\ref{sec:cmd:opt-space}.
+Finally, the character \texttt{>} is used to declare so-called
+`argument processors', which can be used to modify the contents of an
+argument before it is passed to the macro definition. The use of argument
+processors is a somewhat advanced topic, (or at least a less commonly used
+feature) and is covered in Section~\ref{sec:cmd:processors}.
+\subsection{Creating document commands and environments}
+  |\NewDocumentCommand|     \arg{cmd} \arg{arg spec} \arg{code} \\
+  |\RenewDocumentCommand|   \arg{cmd} \arg{arg spec} \arg{code} \\
+  |\ProvideDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
+  |\DeclareDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
+This family of commands are used to create a \meta{cmd}. The argument
+specification for the function is given by \meta{arg spec}, and the command
+uses the \meta{code} with |#1|, |#2|, etc.\ replaced by the arguments found
+by the parser.
+An example:
+  \NewDocumentCommand\chapter{s o m}
+    {%
+      \IfBooleanTF{#1}
+        {\typesetstarchapter{#3}}
+        {\typesetnormalchapter{#2}{#3}}%
+    }
+would be a way to define a \cs{chapter} command which would essentially behave
+like the current \LaTeXe{} command (except that it would accept an optional
+argument even when a \texttt{*} was parsed). The \cs{typesetnormalchapter}
+could test its first argument for being |-NoValue-| to see if an optional
+argument was present. (See Section~\ref{sec:cmd:special} for details of
+\cs{IfBooleanTF} and testing for |-NoValue-|.)
+The difference between the \cs{New\ldots} \cs{Renew\ldots}, \cs{Provide\ldots}
+and \cs{Declare\ldots} versions is the behaviour if \meta{function} is already
+ \item \cs{NewDocumentCommand} will issue an error if \meta{command}
+   has already been defined.
+ \item \cs{RenewDocumentCommand} will issue an error if \meta{command}
+   has not previously been defined.
+ \item \cs{ProvideDocumentCommand} creates a new definition for
+   \meta{function} only if one has not already been given.
+ \item \cs{DeclareDocumentCommand} will always create the new
+   definition, irrespective of any existing \meta{command} with the
+   same name.  This should be used sparingly.
+  |\NewDocumentEnvironment|     \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\
+  |\RenewDocumentEnvironment|   \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\
+  |\ProvideDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\
+  |\DeclareDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\
+These commands work in the same way as \cs{NewDocumentCommand}, etc.\@, but
+create environments (\cs{begin}\arg{env} \ldots{}
+\cs{end}\arg{environment}). Both the \meta{beg-code} and \meta{end-code}
+may access the arguments as defined by \meta{arg spec}. The arguments will be
+given following \cs{begin}\arg{environment}.
+\subsection{Optional arguments}
+When an optional argument is followed by a mandatory argument with the same
+delimiter, the parser issues a warning because the optional argument could not
+be omitted by the user, thus becoming in effect mandatory. This can apply to
+\texttt{o}, \texttt{d}, \texttt{O}, \texttt{D}, \texttt{s}, \texttt{t},
+\texttt{e}, and \texttt{E} type arguments followed by \texttt{r} or
+\texttt{R}-type required arguments.
+The default for \texttt{O}, \texttt{D} and \texttt{E} arguments can be
+the result of grabbing another argument. Thus for example
+  \NewDocumentCommand\foo{O{#2} m}
+would use the mandatory argument as the default for the leading optional
+\subsection{Spacing and optional arguments}
+\TeX{} will find the first argument after a function name irrespective of any
+intervening spaces. This is true for both mandatory and optional arguments. So
+|\foo[arg]| and \verb*|\foo [arg]| are equivalent. Spaces are also ignored when
+collecting arguments up to the last mandatory argument to be collected (as it
+must exist). So after
+  \NewDocumentCommand\foo{m o m}{ ... }
+the user input |\foo{arg1}[arg2]{arg3}| and \verb*|\foo{arg1} [arg2] {arg3}|
+will both be parsed in the same way.
+The behavior of optional arguments \emph{after} any mandatory arguments is
+selectable. The standard settings will allow spaces here, and thus with
+  \NewDocumentCommand\foobar{m o}{ ... }
+both |\foobar{arg1}[arg2]| and \verb*|\foobar{arg1} [arg2]| will find an
+optional argument. This can be changed by giving the modified |!| in the
+argument specification:
+  \NewDocumentCommand\foobar{m !o}{ ... }
+where \verb*|\foobar{arg1} [arg2]| will not find an optional argument.
+There is one subtly here due to the difference in handling by \TeX{} of
+`control symbols', where the command name is made up of a single
+character, such as `\texttt{\textbackslash\textbackslash}'.
+Spaces are not ignored by \TeX{} here,
+and thus it is possible to require an optional argument directly follow such a
+command. The most common example is the use of \texttt{\textbackslash\textbackslash}
+in \pkg{amsmath} environments, which in the terms here would be defined as
+  \NewDocumentCommand\\{!s !o}{ ... }
+The \texttt{E}-type argument allows one default value per test token. This is
+achieved by giving a list of defaults for each entry in the list, for example:
+  E{^_}{{UP}{DOWN}}
+If the list of default values is \emph{shorter} than the list of test tokens,
+the special |-NoValue-| marker will be returned (as for the \texttt{e}-type
+argument). Thus for example
+  E{^_}{{UP}}
+has default \texttt{UP} for the |^| test character, but will return the
+|-NoValue-| marker as a default for |_|. This allows mixing of explicit
+defaults with testing for missing values.
+\subsection{Testing special values}
+Optional arguments make use of dedicated variables to return information about
+the nature of the argument received.
+  |\IfNoValueTF| \arg{arg} \arg{true code} \arg{false code} \\
+  |\IfNoValueT|  \arg{arg} \arg{true code} \arg{false code} \\
+  |\IfNoValueF|  \arg{arg} \arg{true code} \arg{false code}
+The \cs{IfNoValue(TF)} tests are used to check if \meta{argument} (|#1|,
+|#2|, \emph{etc.}) is the special |-NoValue-| marker For example
+  \NewDocumentCommand\foo{o m}
+    {%
+      \IfNoValueTF {#1}
+        {\DoSomethingJustWithMandatoryArgument{#2}}
+        {\DoSomethingWithBothArguments{#1}{#2}}%
+    }
+will use a different internal function if the optional argument
+is given than if it is not present.
+Note that three tests are available, depending on which outcome
+branches are required: \cs{IfNoValueTF}, \cs{IfNoValueT} and
+As the \cs{IfNoValue(TF)} tests are expandable, it is possible to
+test these values later, for example at the point of typesetting or
+in an expansion context.
+It is important to note that |-NoValue-| is constructed such that it
+will \emph{not} match the simple text input |-NoValue-|, i.e.~that
+  \IfNoValueTF{-NoValue-}
+will be logically \texttt{false}.
+When two optional arguments follow each other (a syntax we typically
+discourage), it can make sense to allow users of the command to
+specify only the second argument by providing an empty first
+argument.  Rather than testing separately for emptiness and for
+|-NoValue-| it is then best to use the argument type~|O| with an
+empty default value, and simply test for emptiness using the
+\pkg{expl3} conditional \cs{tl_if_blank:nTF} or its \pkg{etoolbox}
+analogue \cs{ifblank}.
+  |\IfValueTF| \arg{arg} \arg{true code} \arg{false code} \\
+  |\IfValueT|  \arg{arg} \arg{true code} \arg{false code} \\
+  |\IfValueF|  \arg{arg} \arg{true code} \arg{false code}
+The reverse form of the \cs{IfNoValue(TF)} tests are also available
+as \cs{IfValue(TF)}. The context will determine which logical
+form makes the most sense for a given code scenario.
+  |\BooleanFalse|  \\
+  |\BooleanTrue|
+The \texttt{true} and \texttt{false} flags set when searching for
+an optional character (using \texttt{s} or \texttt{t\meta{char}}) have
+names which are accessible outside of code blocks.
+  |\IfBooleanTF| \arg{arg} \arg{true code} \arg{false code} \\
+  |\IfBooleanT|  \arg{arg} \arg{true code} \arg{false code} \\
+  |\IfBooleanF|  \arg{arg} \arg{true code} \arg{false code}
+Used to test if \meta{argument} (|#1|, |#2|, \emph{etc.}) is
+\cs{BooleanTrue} or \cs{BooleanFalse}. For example
+  \NewDocumentCommand\foo{sm}
+    {%
+      \IfBooleanTF {#1}
+        {\DoSomethingWithStar{#2}}
+        {\DoSomethingWithoutStar{#2}}%
+    }
+checks for a star as the first argument, then chooses the action to
+take based on this information.
+\subsection{Argument processors}
+Argument processor are applied to an argument \emph{after} it has been grabbed
+by the underlying system but before it is passed to \meta{code}. An argument
+processor can therefore be used to regularise input at an early stage, allowing
+the internal functions to be completely independent of input form. Processors
+are applied to user input and to default values for optional arguments, but
+\emph{not} to the special |-NoValue-| marker.
+Each argument processor is specified by the syntax \texttt{>}\marg{processor}
+in the argument specification. Processors are applied from right to left, so
+  >{\ProcessorB} >{\ProcessorA} m
+would apply \cs{ProcessorA} followed by \cs{ProcessorB} to the tokens grabbed
+by the \texttt{m} argument.
+  |\SplitArgument| \arg{number} \arg{token(s)}
+This processor splits the argument given at each occurrence of the
+\meta{tokens} up to a maximum of \meta{number} tokens (thus
+dividing the input into $\text{\meta{number}} + 1$ parts).
+An error is given if too many \meta{tokens} are present in the
+input. The processed input is placed inside
+$\text{\meta{number}} + 1$ sets of braces for further use.
+If there are fewer than \arg{number} of \arg{tokens} in the argument
+then |-NoValue-| markers are added at the end of the processed
+  \NewDocumentCommand \foo
+    {>{\SplitArgument{2}{;}} m}
+    {\InternalFunctionOfThreeArguments#1}
+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.
+Spaces are trimmed at each end of each item parsed.
+  |\SplitList| \arg{token(s)}
+This processor splits the argument given at each occurrence of the
+\meta{token(s)} where the number of items is not fixed. Each item is
+then wrapped in braces within |#1|. The result is that the
+processed argument can be further processed using a mapping function
+(see below).
+  \NewDocumentCommand \foo
+    {>{\SplitList{;}} m}
+    {\MappingFunction#1}
+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.
+Spaces are trimmed at each end of each item parsed.
+  |\ProcessList| \arg{list} \arg{function}
+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
+  \NewDocumentCommand \foo
+    {>{\SplitList{;}} m}
+    {\ProcessList{#1}{\SomeDocumentCommand}}
+  |\ReverseBoolean|
+This processor reverses the logic of \cs{BooleanTrue} and
+\cs{BooleanFalse}, so that the example from earlier would become
+  \NewDocumentCommand\foo{>{\ReverseBoolean} s m}
+   {%
+      \IfBooleanTF#1
+        {\DoSomethingWithoutStar{#2}}
+        {\DoSomethingWithStar{#2}}%
+    }
+  |\TrimSpaces|
+Removes any leading and trailing spaces (tokens with character code~$32$
+and category code~$10$) for the ends of the argument. Thus for example
+declaring a function
+  \NewDocumentCommand\foo
+    {>{\TrimSpaces} m}
+    {\showtokens{#1}}
+and using it in a document as
+  \foo{ hello world }
+will show \texttt{hello world} at the terminal, with the space at each
+end removed. \cs{TrimSpaces} will remove multiple spaces from the ends of
+the input in cases where these have been included such that the standard
+\TeX{} conversion of multiple spaces to a single space does not apply.
+\subsection{Body of an environment}
+While environments |\begin|\marg{environment} \dots{} |\end|\marg{environment}
+are typically used in cases where the code implementing the \meta{environment}
+does not need to access the contents of the environment (its `body'),
+it is sometimes useful to have the body as a standard argument.
+This is achieved by ending the argument specification with~\texttt{b}, which is
+a dedicated argument type for this situation. For instance
+  \NewDocumentEnvironment{twice}
+    {O{\ttfamily} +b}
+    {#2#1#2} {}
+  \begin{twice}[\itshape]
+    Hello world!
+  \end{twice}
+typesets `Hello world!{\itshape Hello world!}'.
+The prefix |+| is used to allow multiple paragraphs in the environment's body.
+Argument processors can also be applied to \texttt{b}~arguments. By default,
+spaces are trimmed at both ends of the body: in the example there would
+otherwise be spaces coming from the ends the lines after |[\itshape]| and
+|world!|. Putting the prefix |!| before \texttt{b} suppresses space-trimming.
+When \texttt{b} is used in the argument specification, the last argument of
+\cs{NewDocumentEnvironment}, which consists of an \meta{end code} to insert at
+|\end|\marg{environment}, is redundant since one can simply put that code at
+the end of the \meta{start code}. Nevertheless this (empty) \meta{end code}
+must be provided.
+Environments that use this feature can be nested.
+\subsection{Fully-expandable document commands}
+Document commands created using \cs{NewDocumentCommand}, etc.\@, are normally
+created so that they do not expand unexpectedly. This is done using engine
+features, so is more powerful than \LaTeXe{}'s \cs{protect} mechanism. There
+are \emph{very rare} occasion when it may be useful to create functions using a
+expansion-only grabber. This imposes a number of restrictions on the
+nature of the arguments accepted by a function, and the code it implements.
+This facility should only be used when \emph{absolutely necessary}.
+  |\NewExpandableDocumentCommand|     \arg{cmd} \arg{arg spec} \arg{code} \\
+  |\RenewExpandableDocumentCommand|   \arg{cmd} \arg{arg spec} \arg{code} \\
+  |\ProvideExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
+  |\DeclareExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
+This family of commands is used to create a document-level \meta{function},
+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
+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).
+Parsing arguments by pure expansion imposes a number of restrictions on
+both the type of arguments that can be read and the error checking
+  \item The last argument (if any are present) must be one of the
+    mandatory types \texttt{m}, \texttt{r} or \texttt{R}.
+  \item The `verbatim' argument type \texttt{v} is not available.
+  \item Argument processors (using \texttt{>}) are not available.
+  \item It is not possible to differentiate between, for example
+    |\foo[| and |\foo{[}|: in both cases the \texttt{[} will be
+    interpreted as the start of an optional argument. As a
+    result, checking for optional arguments is less robust than
+    in the standard version.
+\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:
+  \NewDocumentCommand { \foobar } { D<>{default} } {(#1)}
+  \foobar <hello> \par
+  \char_set_catcode_letter:N <
+  \foobar <hello>
+the output would be:
+  (hello)
+  (default)<hello>
+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:
+  \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
+the output would be:
+  (hello)
+  (hello)
+with both calls to the command seeing the delimiter |\x|.
+\subsection{Creating new argument processors}
+  |\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
+  \cs_new_protected:Npn \ReverseBoolean #1
+    {
+      \bool_if:NTF #1
+        { \tl_set:Nn \ProcessedArgument { \c_false_bool } }
+        { \tl_set:Nn \ProcessedArgument { \c_true_bool } }
+    }
+\subsection{Access to the argument specification}
+The argument specifications for document commands and environments are
+available for examination and use.
+  |\GetDocumentCommandArgSpec| \arg{function}
+  |\GetDocumentEnvironmentArgSpec| \arg{environment}
+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.
+  |\ShowDocumentCommandArgSpec| \arg{function}
+  |\ShowDocumentEnvironmentArgSpec| \arg{environment}
+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.
diff --git a/base/manifest.txt b/base/manifest.txt
index f3c8f2b2..0cf27343 100644
--- a/base/manifest.txt
+++ b/base/manifest.txt
@@ -38,6 +38,7 @@
 % fntguide.tex    --  Guide to font selection.
 % modguide.tex    --  Guide to modifying and distributing LaTeX.
 % usrguide.tex    --  User guide for this release.
+% usrguide3.tex   --  User guide for expl3-based methods.
 % ltnews01.tex    --  What was new in the release dated 1994/06.
 % ltnews02.tex    --  What was new in the release dated 1994/12.

More information about the latex3-commits mailing list.