[latex3-commits] [git/LaTeX3-latex3-latex3] xparse: Tighten up xparse doc [ci skip] (0e34832)
Bruno Le Floch
bruno at le-floch.fr
Wed Feb 27 00:07:32 CET 2019
Repository : https://github.com/latex3/latex3
On branch : xparse
Link : https://github.com/latex3/latex3/commit/0e34832236bc88582b7b2190b6b5a425b42c8e13
>---------------------------------------------------------------
commit 0e34832236bc88582b7b2190b6b5a425b42c8e13
Author: Bruno Le Floch <bruno at le-floch.fr>
Date: Tue Feb 26 20:27:16 2019 +0100
Tighten up xparse doc [ci skip]
>---------------------------------------------------------------
0e34832236bc88582b7b2190b6b5a425b42c8e13
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 dff584a..b74aa8c 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