[latex3-commits] [git/LaTeX3-latex3-latex3] master: Document advice on xparse delimiters (7e94dae)

[Bruno Le Floch]

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

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

commit 7e94dae775dbf438224b821a33d61375082ebb56
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Wed Apr 18 12:00:56 2018 -0400

    Document advice on xparse delimiters


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

7e94dae775dbf438224b821a33d61375082ebb56
 l3packages/xparse/xparse.dtx |   21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/l3packages/xparse/xparse.dtx b/l3packages/xparse/xparse.dtx
index cf5e3d3..3f3e255 100644
--- a/l3packages/xparse/xparse.dtx
+++ b/l3packages/xparse/xparse.dtx
@@ -123,8 +123,7 @@
 % 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 (as described in Section~\ref{sec:backwards} the types \texttt{l}
-% and \texttt{u} are not recommended):
+% 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.
@@ -149,9 +148,7 @@
 %     argument will not work when it appears within an argument of
 %     another function.
 % \end{itemize}
-% The types which define optional arguments are (as described in
-% Section~\ref{sec:backwards} the types \texttt{g} and \texttt{G} are
-% not recommended):
+% The types which define optional arguments are:
 % \begin{itemize}[font=\ttfamily]
 %   \item[o] A standard \LaTeX{} optional argument, surrounded with square
 %     brackets, which will supply
@@ -250,6 +247,20 @@
 % arguments, but also to \texttt{g} or \texttt{G} type arguments
 % followed by \texttt{m} type arguments.
 %
+% As \pkg{xparse} is also used to describe interfaces that have appeared
+% in the wider \LaTeXe{} eco-system, it also defines additional argument
+% types, described in Section~\ref{sec:backwards}: the mandatory types
+% \texttt{l} and \texttt{u} and the optional brace group types
+% \texttt{g} and \texttt{G}.  Their use is not recommended because it is
+% simpler for a user if all packages use a similar syntax.  For the same
+% reason, delimited arguments \texttt{r}, \texttt{R}, \texttt{d} and
+% \texttt{D} should normally use delimiters that are naturally paired,
+% such as |[| and |]| or |(| and |)|, or that are identical, such as |"|
+% and~|"|.  A very common syntax is to have one optional argument
+% \texttt{o} treated as a key--value list (using for instance
+% \pkg{l3keys}) followed by some mandatory arguments~\texttt{m} (or
+% \texttt{+m}).
+%
 % \subsection{Spacing and optional arguments}
 %
 % \TeX{} will find the first argument after a function name irrespective