[latex3-commits] [git/LaTeX3-latex3-latex3] xparse: Document that xparse doesn't treat starred environment names specially [ci-skip] (ed3a1aa)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : xparse
Link       : https://github.com/latex3/latex3/commit/ed3a1aaf5286793bb303605d3c19e908302d20ef

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

commit ed3a1aaf5286793bb303605d3c19e908302d20ef
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Thu Feb 28 15:59:28 2019 +0100

    Document that xparse doesn't treat starred environment names specially [ci-skip]


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

ed3a1aaf5286793bb303605d3c19e908302d20ef
 l3packages/xparse/xparse.dtx |   25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/l3packages/xparse/xparse.dtx b/l3packages/xparse/xparse.dtx
index 1f74e0f..a918590 100644
--- a/l3packages/xparse/xparse.dtx
+++ b/l3packages/xparse/xparse.dtx
@@ -434,6 +434,31 @@
 % Users should note that this feature is somewhat experimental. Feedback
 % is therefore very welcome on the \texttt{LaTeX-L} mailing list.
 %
+% \subsection{Starred environments}
+%
+% Many packages define environments with and without \texttt{*} in their
+% name, for instance \texttt{tabular} and \texttt{tabular*}.  At
+% present, \pkg{xparse} does not provide specific tools to define these:
+% one should simply define the two environment separately, for instance
+% \begin{verbatim}
+% \NewDocumentEnvironment { tabular } { o +m } {...} {...}
+% \NewDocumentEnvironment { tabular* } { m o +m } {...} {...}
+% \end{verbatim}
+% Of course the implementation of these two environments, denoted
+% \enquote{\texttt{...}} in this example, can rely on the same internal
+% commands.
+%
+% Note that this situation is different from the \texttt{s} argument
+% type: if the signature of an environment starts with~\texttt{s} then
+% the star is searched for after the argument of \cs{begin}.  For
+% instance, the following typesets \texttt{star}.
+% \begin{verbatim}
+% \NewDocumentEnvironment { envstar } { s }
+%   {\IfBooleanTF {#1} {star} {no star}} {}
+% \begin{envstar}*
+% \end{envstar}
+% \end{verbatim}
+%
 % \subsection{Backwards Compatibility}
 % \label{sec:backwards}
 %