[latex3-commits] [git/LaTeX3-latex3-latex2e] cmd: Document nesting behaviour of o-type arguments (b07416d6)

[Joseph Wright]

Repository : https://github.com/latex3/latex2e
On branch  : cmd
Link       : https://github.com/latex3/latex2e/commit/b07416d636ba36dd5faab973b3e22df88c29a70a

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

commit b07416d636ba36dd5faab973b3e22df88c29a70a
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Thu Dec 3 07:35:32 2020 +0000

    Document nesting behaviour of o-type arguments


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

b07416d636ba36dd5faab973b3e22df88c29a70a
 base/doc/usrguide3.tex | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/base/doc/usrguide3.tex b/base/doc/usrguide3.tex
index 50150845..d527844d 100644
--- a/base/doc/usrguide3.tex
+++ b/base/doc/usrguide3.tex
@@ -242,6 +242,23 @@ given following \cs{begin}\arg{environment}.
 \subsection{Optional arguments}
 \label{sec:cmd:opt}
 
+In contrast to commands created using \LaTeXe{}'s \cs{newcommand}, optional
+arguments created using \cs{NewDocumentCommand} may safely be nested. Thus for
+example, following
+\begin{verbatim}
+\NewDocumentCommand\foo{om}{I grabbed `#1' and `#2'}
+\end{verbatim}
+using the command as
+\begin{verbatim}
+\foo[[some stuff]]{more stuff}
+\end{verbatim}
+will print
+\begin{quote}
+I grabbed `[some stuff]' and `more stuff'
+\end{quote}
+This is particularly useful when placing a command with an optional argument
+\emph{inside} the optional argument of a second command.
+
 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