[latex3-commits] [git/LaTeX3-latex3-latex3] master: Tighten up xparse doc [ci skip] (def884c)

Joseph Wright joseph.wright at morningstar2.co.uk
Mon Mar 4 14:54:38 CET 2019


Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/def884c1f1bbf4b0d14811f1438f499d96feae6b

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

commit def884c1f1bbf4b0d14811f1438f499d96feae6b
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Tue Feb 26 20:27:16 2019 +0100

    Tighten up xparse doc [ci skip]


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

def884c1f1bbf4b0d14811f1438f499d96feae6b
 l3packages/xparse/xparse.dtx |   81 +++++++++++++++++++++---------------------
 1 file changed, 41 insertions(+), 40 deletions(-)

diff --git a/l3packages/xparse/xparse.dtx b/l3packages/xparse/xparse.dtx
index 8deffce..19277bf 100644
--- a/l3packages/xparse/xparse.dtx
+++ b/l3packages/xparse/xparse.dtx
@@ -126,26 +126,27 @@
 % are:
 % \begin{itemize}[font=\ttfamily]
 %   \item[m] A standard mandatory argument, which can either be a single
-%     token alone or multiple tokens surrounded by curly braces.
+%     token alone or multiple tokens surrounded by curly braces |{}|.
 %     Regardless of the input, the argument will be passed to the
-%     internal code surrounded by a brace pair. This is the \pkg{xparse}
+%     internal code without the outer braces. This is the \pkg{xparse}
 %     type specifier for a normal \TeX{} argument.
-%   \item[r] Reads a \enquote{required} delimited argument, where the
-%     delimiters are given as \meta{char1} and \meta{char2}:
-%     \texttt{r}\meta{char1}\meta{char2}. If the opening \meta{character}
-%     is missing, the default marker |-NoValue-| will be inserted after
-%     a suitable error.
-%   \item[R] As for \texttt{r}, this is a \enquote{required} delimited
-%     argument but has a user-definable recovery \meta{default}, given
-%     as \texttt{R}\meta{char1}\meta{char2}\marg{default}.
+%   \item[r] Given as \texttt{r}\meta{char1}\meta{char2}, this denotes a
+%     \enquote{required} delimited argument, where the delimiters are
+%     \meta{char1} and \meta{char2}. If the opening delimiter
+%     \meta{char1} is missing, the default marker |-NoValue-| will be
+%     inserted after a suitable error.
+%   \item[R] Given as \texttt{R}\meta{char1}\meta{char2}\marg{default},
+%     this is a \enquote{required} delimited argument as for~\texttt{r},
+%     but it has a user-definable recovery \meta{default} instead of
+%     |-NoValue-|.
 %   \item[v] Reads an argument \enquote{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 matching tokens, which cannot be any of |%|, |\|,
+%     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 not work when it appears within an argument of
+%     argument will produce an error when it appears within an argument of
 %     another function.
 % \end{itemize}
 % The types which define optional arguments are:
@@ -153,14 +154,14 @@
 %   \item[o] A standard \LaTeX{} optional argument, surrounded with square
 %     brackets, which will supply
 %     the special |-NoValue-| marker if not given (as described later).
-%   \item[d] An optional argument which is delimited by \meta{char1}
-%     and \meta{char2}, given as follows:
-%     \texttt{d}\meta{char1}\meta{char2}. As with \texttt{o}, if no
+%   \item[d] Given as \texttt{d}\meta{char1}\meta{char2}, an optional
+%     argument which is delimited by \meta{char1} and \meta{char2}.
+%     As with \texttt{o}, if no
 %     value is given the special marker |-NoValue-| is returned.
-%   \item[O] As for \texttt{o}, but returns \meta{default} if no
-%     value is given.  Should be given as \texttt{O}\marg{default}.
-%   \item[D] As for \texttt{d}, but returns \meta{default} if no
-%     value is given: \texttt{D}\meta{char1}\meta{char2}\marg{default}.
+%   \item[O] Given as \texttt{O}\marg{default}, is like \texttt{o}, but
+%     returns \meta{default} if no value is given.
+%   \item[D] Given as \texttt{D}\meta{char1}\meta{char2}\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[s] An optional star, which will result in a value
@@ -169,9 +170,9 @@
 %   \item[t] An optional \meta{char}, which will result in a value
 %     \cs{BooleanTrue} if \meta{char} is present and \cs{BooleanFalse}
 %     otherwise. Given as \texttt{t}\meta{char}.
-%   \item[e] A set of optional \emph{embellishments}, each of which
-%     requires a \emph{value}: \texttt{e}\marg{chars}.  If an
-%     embellishment is not present, |-NoValue-| is returned.  Each
+%   \item[e] Given as \texttt{e}\marg{chars}, 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{chars} in the argument specification.  All \meta{chars}
 %     must be distinct.  \emph{This is an experimental type}.
@@ -217,7 +218,7 @@
 %   \NewDocumentCommand{\foobar}{o}{#1}
 %   \foobar[{[}]         % Allowed as the "[" is 'hidden'
 % \end{verbatim}
-% These braces will be stripped if they surround the \emph{entire} content
+% These braces will be stripped only if they surround the \emph{entire} content
 % of the optional argument
 % \begin{verbatim}
 %   \NewDocumentCommand{\foobaz}{o}{#1}
@@ -241,7 +242,7 @@
 % When an optional argument is followed by a mandatory argument with the
 % same delimiter, \pkg{xparse} issues a warning because the optional
 % argument could not be omitted by the user, thus becoming in effect
-% mandatory.  This applies to \texttt{o}, \texttt{d}, \texttt{O},
+% 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, but also to \texttt{g} or \texttt{G} type arguments
@@ -313,10 +314,6 @@
 % (\texttt{r}-type) or user-specified default (for \texttt{R}-type) will be
 % inserted to allow error recovery.
 %
-% Users should note that support for required delimited arguments is somewhat
-% experimental. Feedback is therefore very welcome on the \texttt{LaTeX-L}
-% mailing list.
-%
 % \subsection{Verbatim arguments}
 %
 % Arguments of type~\texttt{v} are read in verbatim mode, which will
@@ -404,12 +401,13 @@
 %     \DeclareDocumentCommand
 %   }
 %   \begin{syntax}
-%     \cs{NewDocumentCommand} \meta{Function} \Arg{arg spec} \Arg{code}
+%     \cs{NewDocumentCommand} \meta{function} \Arg{arg spec} \Arg{code}
 %   \end{syntax}
 %   This family of commands are used to create a document-level
 %   \meta{function}. The argument specification for the function is
-%   given by \meta{arg spec},  and expanding
-%   to be replaced by the \meta{code}.
+%   given by \meta{arg spec}, and the function expands to the
+%   \meta{code} with |#1|, |#2|, etc.\ replaced by the arguments found
+%   by \pkg{xparse}.
 % \end{function}
 %
 %   As an example:
@@ -599,10 +597,10 @@
 %
 % \begin{function}[updated = 2012-02-12]{\SplitArgument}
 %   \begin{syntax}
-%     \cs{SplitArgument} \Arg{number} \Arg{token}
+%     \cs{SplitArgument} \Arg{number} \Arg{token(s)}
 %   \end{syntax}
 %   This processor splits the argument given at each occurrence of the
-%   \meta{token} up to a maximum of \meta{number} tokens (thus
+%   \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
@@ -615,9 +613,10 @@
 %       { > { \SplitArgument { 2 } { ; } } m }
 %       { \InternalFunctionOfThreeArguments #1 }
 %   \end{verbatim}
-%   Any category code $13$ (active) \meta{tokens} will be replaced
-%   before the split takes place. Spaces are trimmed at each end of each
-%   item parsed.
+%   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.
 % \end{function}
 %
 % \begin{function}{\SplitList}
@@ -633,9 +632,10 @@
 %       { > { \SplitList { ; } } m }
 %       { \MappingFunction #1 }
 %   \end{verbatim}
-%   If only a single \meta{token} is used for the split, any
-%   category code $13$ (active) \meta{token} will be replaced
-%   before the split takes place.
+%   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.
 % \end{function}
 %
 % \begin{function}[EXP]{\ProcessList}
@@ -713,7 +713,8 @@
 %   available:
 %   \begin{itemize}
 %     \item The last argument (if any are present) must be one of the
-%       mandatory types \texttt{m} or \texttt{r}.
+%       mandatory types \texttt{m}, \texttt{r}, \texttt{R}, \texttt{l}
+%       or~\texttt{u}.
 %     \item All short arguments appear before long arguments.
 %     \item The mandatory argument types \texttt{l} and \texttt{u} may
 %       not be used after optional arguments.





More information about the latex3-commits mailing list