Detail creating commands at start of tabular cells

base/changes.txt

@@ -12,8 +12,10 @@ are not part of the distribution.
 
 2023-05-17  Joseph Wright  <Joseph.Wright@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@latex-project.org>
 

base/doc/usrguide.tex

@@ -728,15 +728,15 @@ \subsection{Body of an environment}
 
 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
 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 @@ \subsection{Fully-expandable document commands}
     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