[latex3-commits] [git/LaTeX3-latex3-latex3] master: Document that reasonable xparse interfaces should avoid u, l, g, G [ci skip] (2a0bdd4)

[Bruno Le Floch]

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

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

commit 2a0bdd494154340d505e1fb5aad025bbf0b5f885
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Sat Apr 7 01:36:30 2018 -0400

    Document that reasonable xparse interfaces should avoid u, l, g, G [ci skip]


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

2a0bdd494154340d505e1fb5aad025bbf0b5f885
 l3packages/xparse/xparse.dtx |   44 ++++++++++++++++++++++++++++++------------
 1 file changed, 32 insertions(+), 12 deletions(-)

diff --git a/l3packages/xparse/xparse.dtx b/l3packages/xparse/xparse.dtx
index 06861a1..e023e95 100644
--- a/l3packages/xparse/xparse.dtx
+++ b/l3packages/xparse/xparse.dtx
@@ -123,15 +123,14 @@
 % 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
-% are:
+% are (as described in Section~\ref{sec:backwards} the types \texttt{l}
+% and \texttt{u} are not recommended):
 % \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.
 %     Regardless of the input, the argument will be passed to the
 %     internal code surrounded by a brace pair. This is the \pkg{xparse}
 %     type specifier for a normal \TeX{} argument.
-%   \item[l] An argument which reads everything up to the first
-%     begin-group token: in standard \LaTeX{} this is a left brace.
 %   \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}
@@ -140,9 +139,6 @@
 %   \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[u] Reads an argument \enquote{until} \meta{tokens} are encountered,
-%     where the desired \meta{tokens} are given as an argument to the
-%     specifier: \texttt{u}\marg{tokens}.
 %   \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
@@ -153,7 +149,9 @@
 %     argument will not work when it appears within an argument of
 %     another function.
 % \end{itemize}
-% The types which define optional arguments are:
+% The types which define optional arguments are (as described in
+% Section~\ref{sec:backwards} the types \texttt{g} and \texttt{G} are
+% not recommended):
 % \begin{itemize}[font=\ttfamily]
 %   \item[o] A standard \LaTeX{} optional argument, surrounded with square
 %     brackets, which will supply
@@ -174,11 +172,6 @@
 %   \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[g] An optional argument given inside a pair of \TeX{} group
-%     tokens (in standard \LaTeX, |{| \ldots |}|), which returns
-%     |-NoValue-| if not present.
-%   \item[G] As for \texttt{g} but returns \meta{default} if no value
-%     is given: \texttt{G}\marg{default}.
 %   \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
@@ -761,6 +754,33 @@
 % \end{verbatim}
 % this may be suppressed and no information messages are produced.
 %
+% \section{Backwards Compatibility}
+% \label{sec:backwards}
+%
+% One role of \pkg{xparse} is to describe existing \LaTeX{} interfaces,
+% including some that are rather unusual in \LaTeX{} (as opposed to
+% formats such as plain \TeX{}) such as delimited arguments.  As such,
+% the package defines some argument specifiers that should largely be
+% avoided nowadays as using them in packages leads to inconsistent user
+% interfaces.  The simplest syntax is often best, with argument
+% specifications such as |mmmm| or |ommmm|, namely an optional argument
+% followed by some standard mandatory ones.  The optional argument can
+% be made to support key--value syntax using tools from \pkg{l3keys}.
+%
+% The argument types that are not recommended any longer are:
+% \begin{itemize}[font=\ttfamily]
+%   \item[l] A mandatory argument which reads everything up to the first
+%     begin-group token: in standard \LaTeX{} this is a left brace.
+%   \item[u] Reads a mandatory argument \enquote{until} \meta{tokens} are encountered,
+%     where the desired \meta{tokens} are given as an argument to the
+%     specifier: \texttt{u}\marg{tokens}.
+%   \item[g] An optional argument given inside a pair of \TeX{} group
+%     tokens (in standard \LaTeX{}, |{| \ldots |}|), which returns
+%     |-NoValue-| if not present.
+%   \item[G] As for \texttt{g} but returns \meta{default} if no value
+%     is given: \texttt{G}\marg{default}.
+% \end{itemize}
+%
 % \end{documentation}
 %
 % \begin{implementation}