[latex3-commits] [latex3/latex2e] develop: Detail creating commands at start of tabular cells (8815c607)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : develop
Link       : https://github.com/latex3/latex2e/commit/8815c6077f300b6661e274f34189a630b7caa5ac

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

commit 8815c6077f300b6661e274f34189a630b7caa5ac
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed May 17 07:47:25 2023 +0100

    Detail creating commands at start of tabular cells


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

8815c6077f300b6661e274f34189a630b7caa5ac
 base/changes.txt      |  4 +++-
 base/doc/usrguide.tex | 23 +++++++++++++++++++++--
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/base/changes.txt b/base/changes.txt
index 45d85d9f..d0a5b02c 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -12,8 +12,10 @@ are not part of the distribution.
 
 2023-05-17  Joseph Wright  <Joseph.Wright at latex-project.org>
 
-	* usrguide.tex (subsection Argument processors)
+	* usrguide.tex (section Creating document commands and environments)
 	  Add details of brace stripping by \SplitList
+	  Add guidance on creating commands to use at start of
+	  tabular cells
 
 2023-05-13  David Carlisle  <David.Carlisle at latex-project.org>
 
diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex
index 590a9190..f4f7dc37 100644
--- a/base/doc/usrguide.tex
+++ b/base/doc/usrguide.tex
@@ -728,7 +728,7 @@ put that code at the end of the \meta{start code}. Nevertheless this
 
 Environments that use this feature can be nested.
 
-\subsection{Fully-expandable document commands}
+\subsection{Fully-expandable document commands\label{sec:ltcmd:expandable}}
 
 Document commands created using \cs{NewDocumentCommand}, etc.\@, are normally
 created so that they do not expand unexpectedly. This is done using engine
@@ -736,7 +736,7 @@ features, so is more powerful than \LaTeXe{}'s \cs{protect} mechanism. There
 are \emph{very rare} occasion when it may be useful to create functions using a
 expansion-only grabber. This imposes a number of restrictions on the
 nature of the arguments accepted by a function, and the code it implements.
-This facility should only be used when \emph{absolutely necessary}.
+This facility should only be used when \emph{necessary}.
 
 \begin{decl}
   |\NewExpandableDocumentCommand|     \arg{cmd} \arg{arg spec} \arg{code} \\
@@ -767,6 +767,25 @@ available:
     in the standard version.
 \end{itemize}
 
+\subsection{Commands at the start of tabular cells}
+
+Creating commands that are used at the start of tabular cells imposes
+some restrictions on the underyling implementation. The standard \LaTeX{}
+tabular environments (\texttt{tabular}, etc.)  use a mechanism which requires
+that any command wrapping \cs{multicolumn} or similar must be
+`expandable'. This is \emph{not} the case for commands created using
+\cs{NewDocumentCommand}, etc., which as detailed in
+Section~\ref{sec:ltcmd:expandable} use an engine feature which prevents
+such `expansion'. Therefore, to create such wrappers for use at the start
+of tabular cells, you must use \cs{NewExpandableDocumentCommand}, for example
+\begin{verbatim}
+\NewDocumentCommand\MyMultiCol{m}{\multicolumn{3}{c}{#1}}
+\begin{tabular}{lcr}
+a & b & c \\
+\MyMultiCol{stuff} \\
+\end{tabular}
+\end{verbatim}
+
 \subsection{Details about argument delimiters}
 
 In normal (non-expandable) commands, the delimited types look for the