\NewDocumentCommand vs \newcommand vs \NewExpandableDocumentCommand (to define a container for a text)

Question

In his answer to a recent question of mine, @egreg advised \newcommand instead of \NewDocumentCommand to define a container for a text. And I'm aware of this (10 years old!) question where:

• Joseph Wright answers “Conceptually, \NewDocumentCommand is intended for 'package authors' to define commands”. But it is so simpler to define optional arguments (and even starred variants) with \NewDocumentCommand that I don't see why not advise it to document authors.

• Ulrike Fischer answers “Macros defined with \NewDocumentCommand are robust, they don't get expanded when e.g. moved to the .toc”. But the issue with \NewDocumentCommand example she gave there can be avoided with \NewExpandableDocumentCommand:

    \documentclass{article}
    % \usepackage{xparse}                          % <- useless nowadays
  \begin{document}
    \NewDocumentCommand\testA{}{ABC}
    \newcommand\testB{ABC}
    \NewExpandableDocumentCommand{\testC}{}{ABC}   % <- added by me
  \tableofcontents
  \RenewDocumentCommand\testA{}{CDE}
    \renewcommand\testB{CDE}
    \RenewExpandableDocumentCommand{\testC}{}{CDE} % <- added by me
  \section{\testA, \testB
    , \testC                                       % <- added by me
    }
  \end{document}
  

Hence I wonder why not use:

• \NewDocumentCommand (and friends) as document author?
• \NewExpandableDocumentCommand to define a container for a text?

I agree that it wouldn't be ideal to mix \NewExpandableDocumentCommands and \NewDocumentCommands in the same preamble, the former for variables (i.e. container of text i.e. macros used as storage) and the latter for commands. But mixing \newcommands and \NewDocumentCommands would look worse.

Moreover, the arguments in this answer also are in favor of \NewDocumentCommand and \NewExpandableDocumentCommand.

So I know this has been already discussed but, since xparse is now in the kernel, I'd like to know if there are still strong arguments against \NewDocumentCommand and \NewExpandableDocumentCommand for document authors (I'm inclined to promote them in my LaTeX's courses).

Edit

(Here is a bit of context that might explain the current question.)

My concern here is what to teach to beginners or intermediate users of LaTeX. I used to teach \newcommand{\dst}{Dostoïevsky} as an example of a nice feature of LaTeX for a student who has to write a long report on Dostoïevsky. And, of course, I didn't stop there: for students in history, I used to teach:

• \newcommand{\century}[1]{\textsc{#1}\ieme{}~siècle} (sorry in French, “siècle” being “century” and with the babel-french feature \ieme),
• and even \newcommand{\century}[2][\ieme]{\textsc{#2}#1~siècle} since, in French, there is an exception only for the 1^st century (ignoring negative centuries): \century[\ier]{i}.

And I was after a way to replace this by the more modern, flexible and, I hoped, uniform way of defining variables/commands: the “xparse”' way.

Answer 1

If you want a container for text that can be delivered by expansion also in “full expansion” contexts, then \NewDocumentCommand is out of the question, because it defines a \protected command.

So the choice would be between \NewExpandableDocumentCommand and \newcommand. The latter has big advantages: delivering the contained text just requires one expansion step.

Besides, \New(Expandable)DocumentCommand is designed to do parsing of arguments in a cleaner way than with legacy LaTeX programming and not as a catch-all replacement for \newcommand, which will continue to exist. Argumentless macros (that is, containers) are best dealt with \newcommand, if you don't want to follow the path described below.

A better way

Actually, my suggestion is to use neither.

\ExplSyntaxOn
\NewDocumentCommand{\definecontainer}{mm}
 {
  \tl_new:c { l__denis_container_#1_tl }
  \tl_set:cn { l__denis_container_#1_tl } { #2 }
 }
\NewExpandableDocumentCommand{\usecontainer}{m}
 {
  \tl_use:c { l__denis_container_#1_tl }
 }
\ExplSyntaxOff

Or possibly a property list:

\ExplSyntaxOn
\prop_new:N \l_denis_container_prop
\NewDocumentCommand{\definecontainer}{mm}
 {
  \prop_put:Nnn \l_denis_container_prop { #1 } { #2 }
 }
\NewExpandableDocumentCommand{\usecontainer}{m}
 {
  \prop_item:Nn \l_denis_container_prop { #1 }
 }
\ExplSyntaxOff

In either case you say \definecontainer{foo}{whatever} and \usecontainer{foo}.

The latter has the advantage that what's delivered by \prop_item:Nn is not subject to further expansion in full expansion contexts.

Real world application

Something like \newcommand{\dst}{Dostoïevsky} seems to simplify one's life, but that's not really true. After a few months, the same author of the essay will not remember what \dst means.

A possible better choice could be to use \dostoievsky as the name, but with the downside that you need {} after it, in order to preserve a following space.

A strategy like the one outlined above might help much better.

% boilerplate code
\ExplSyntaxOn
\prop_new:N \g_denis_names_prop
\NewDocumentCommand{\definename}{mm}
 {
  \prop_gput:Nnn \g_denis_names_prop { #1 } { #2 }
 }
\NewExpandableDocumentCommand{\name}{m}
 {
  \prop_item:Nn \g_denis_names_prop { #1 }
 }
\ExplSyntaxOff
% define names
\definename{dostoievski}{Dostoïevsky}

In the body of the document you'd use

The Russian writer \name{dostoievsky} risked to be executed.

The name is there and the obvious convention is to remove capitalization and diacritics. This will be remembered much more easily.

For \century you can do

\documentclass{article}
\usepackage{fix-cm}
\usepackage[T1]{fontenc}
\usepackage[french]{babel}
\ExplSyntaxOn
\NewDocumentCommand{\century}{m}
 {
  % make the argument lowercase
  \textsc{\text_lowercase:n{#1}}
  % add the suffix
  \denis_century_suffix:n { #1 }
 }
\cs_new_protected:Nn \denis_century_suffix:n
 {
  \str_case_e:nnF { \str_foldcase:n { #1 } }
   { {i}{\ier} }
   { \ieme }
 }
\ExplSyntaxOff
\begin{document}
\century{i} \century{I} \century{xiv} \century{XIV}
\end{document}

More complicated than using an optional argument? Perhaps, but it makes life much easier.

Answer 2

In my LaTeX book, I have relegated \newcommand to a sidebar and \NewExpandableDocumentCommand to an appendix, preferring \NewDocumentCommand (and \NewEnvironment) for creating commands.

The biggest limitation had been that tabularray’s expand= option only worked with commands defined with \def or \newcommand¹ but a newer release has relaxed that restriction (and now I need to add a section to the manuscript, having seen this when checking for the name of the option).

I do like to put the argument specification on its own line with \NewDocumentCommand as it makes it harder to miss the empty spec when defining a command without arguments. Compare

\NewDocumentCommand{\dst}
   {}
   {Dostoïevsky}

and

\NewDocumentCommand{\dst}{}{Dostoïevsky}

---

1. Except commands defined with \newcommand that have optional arguments.

Answer 3

We have two cases how to save a tokens list into TeX memory and restore it. First case is defining macros without parameter and second case is using toks registers:

                            save it:  \def\foo{text}    use it:   \foo
or:
declare it: \newtoks\foo    save it:  \foo={text}       use it:   \the\foo

The first case if fully expandable (in context of \edef, \write), the second case expands only to text, but if text includes expandable control sequences then they are not expanded in \edef, \write context. For example

\newtoks\foo  \foo={text: \the\dimen0 }  \edef\bar{... \the\foo ...}

then \bar is a macro with body: ... text: \the\dimen0 ....

Moreover, we can use the prefix \protected before \def\foo in order to prohibit expansion of \foo in the \edef, \write context:

\protected\def\foo{text}  \edef\bar{... \foo ...}

then \bar is a macro with body: ... \foo ....

Note that the prefix \long can be used before \def too but its usage is irrelevant when we define a macro without parameter. Only \ifx differs between long and no-long macros even if they have no parameters.

LaTeX provides huge amount of macros which expand to these primitive constructs (in order to make the world more difficult?). We can try to use them and then to look at the meaning of declared control sequence:

\tt \parindent=0pt \parskip=10pt
\def\foo{text}               def: \meaning\foo     \par
\newtoks\foo  \foo={text}    toks: \meaning\foo    \par
\protected\def\foo{text}     protected def: \meaning\foo   \par
\let\foo=\undefined
\newcommand\foo{text}        newcommand: \meaning\foo   \par
\renewcommand\foo{text}      renewcommand: \meaning\foo  \par
\DeclareRobustCommand\foo{text}  DeclareRobustCommand: \meaning\foo  \par
\let\foo=\undefined
\NewDocumentCommand\foo{}{text}  NewDocumentCommand: \meaning\foo  \par
\let\foo=\undefined
\NewExpandableDocumentCommand\foo{}{text}  NewExpandableDocumentCommand: \meaning\foo  \par

The result is:

Note that macros declared by \DeclareRobustCommand, \NewDocumentCommand and \NewExpandableDocumentCommand don't expand into its declared macro body directly, but there is more complicated way to reach the declared macro body. The declared macro body is invisible when we are using only \meaning\foo. Tracing such macros (using positive \tracingmacros) is very inconvenient.

There are plenty of more macros doing the same or similar things in LaTeX's Expl3 syntax, but I don't want to dig into them. They all run ultimately \def or handle with tokens registers.