9

What are the main differences between \newcommand, \NewDocumentCommand and \DeclareRobustCommand? Could you answer me giving exhaustive examples, please?

I already read this, this and this, but I'd like to know more.

1

1 Answer 1

11

\newcommand is the good'ol command for defining user-level commands in LaTeX: it allows you to make a long (\newcommand) or short (\newcommand*) command, and allows you to have a command with an optional argument and give it a default.

On top of that, you can use \newcommand* instead, and the commands will be short macros (they will error if there is a \par in the argument).

Commands defined with \newcommand will be robust if they take an optional argument, and will be expandable otherwise.


\DeclareRobustCommand is a companion to \newcommand: it makes every command defined with it robust, including ones that don't take optional arguments. \newcommand making commands with optional arguments robust is a slightly more recent feature (end of 1995), and \DeclareRobustCommand predates that (added mid-1994).

You will use \DeclareRobustCommand when your command is not expandable and it's supposed to be used in moving arguments (for example section titles or captions). If your command should be expandable, you cannot use \DeclareRobustCommand.

Since 2015, LaTeX provides \MakeRobust. Doing \DeclareRobustCommand\foo ... has exactly the same effect as \newcommand\foo ... then \MakeRobust\foo.


\NewDocumentCommand is (along with its expandable counterpart \NewExpandableDocumentCommand) kind of the successor to \newcommand: they allow you to define commands with different combinations of mandatory (m and r) and optional arguments (d and o), starred versions of a command (s), different combinations of long (+) and short arguments. It also allows you to pre-process an argument before passing it to the command (using >).

Different from \newcommand, commands defined with \NewDocumentCommand are always robust, and ones defined with \NewExpandableDocumentCommand are always expandable (as long as the code in them is also expandable).


In the past, package authors only had \newcommand (and \DeclareRobustCommand, which is roughly the same thing) to define user interfaces, and if that wasn't enough for whatever reason, then the programmer had to do the parsing manually. \NewDocumentCommand, on the other hand, has a much more complex parsing machinery that goes far beyond what \newcommand provides, so it is the recommended way to create user-level commands (see this blog post on that matter).

Nowadays, it is recommended to use \newcommand only when you want the simple interface it provides, and you have a performance-critical application (the features of \NewDocumentCommand come at a cost), or when you are using a command as a simple text substitution (example).

On the technical side, \newcommand is also very different from \NewDocumentCommand. Suppose we are defining a command \foo. \newcommand just defines \foo to look for an optional argument, and then \\foo to actually grab them (or just \foo if there is no optional), and that's that. When defined with \NewDocumentCommand, \foo is actually just a wrapper around internal LaTeX macros that will do the parsing of the arguments, and then pass them to the actual definition of the command stored in \foo code.


P.S.: Also note that while \newcommand and \NewDocumentCommand check if the command being defined already exist (trying to protect you from shooting yourself on the foot), \DeclareRobustCommand doesn't, and will overwrite existing commands. There is also \renewcommand and \RenewDocumentCommand in case you want to redefine something. There is also provide versions of both, which only create the definition if there isn't one yet (kind of a "fallback version" of a command), and there is also \DeclareDocumentCommand that always creates the definition (not recommended), but no matching \declarecommand.

3
  • 1
    actually \DeclareRobustCommand is 2e as well Oct 22, 2021 at 11:48
  • 1
    The LaTeX2.09 way used to be \def\LaTeX{\protect\pLaTeX}\def\pLaTeX{...}.
    – egreg
    Oct 22, 2021 at 11:53
  • @DavidCarlisle Oh! Not sure where I got that from. I'll fix, thanks! Oct 22, 2021 at 12:00

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .