
I just spotted someone use \newcommand* in an answer and realised that I'd never quite sorted out in my head what the star (asterisk) was there for.

(This one is practically impossible to search for on the internet so this is a good place to record the answer!)

-
so much for a self-documenting system, huh? texdoc fail =) i thought it can do that. – Dima Aug 4 '10 at 18:14

A bit of background first. When Knuth wrote TeX, he realised that most macros would not need to absorb more than one paragraph as an argument. As a result, a good way to test for errors such as a missing } is to forbid macros to accept paragraph tokens (either those generated by blank lines or explicit \par tokens). So he created \def for definitions which cannot take a paragraph token, and the \long prefix to allow them to:

\def\examplea#1{% #1 cannot contain \par
}
\long\def\exampleb#1{% #1 can contain \par
}



\newcommand{\examplea}[1]{% #1 can contain \par
}
\newcommand*{\exampleb}[1]{% #1 cannot contain \par
}



The same behaviour is seen with \newenvironment:

\newenvironment{examplea}[1]{% #1 can contain \par
}{}
\newenvironment*{exampleb}[1]{% #1 cannot contain \par
}{}



For LaTeX3, we've decided to take a somewhat hybrid approach. If you use xparse for defining document commands, they are only 'long' if you ask for it:

\NewDocumentCommand\examplea{m}{% #1 cannot contain \par
}
\NewDocumentCommand\examplab{+m}{% #1 can contain \par
}


(We've decided on + to represent a long argument). On the other hand, for internal use it is normally best to accept paragraph tokens, and to leave the filtering to the user interface level.

-
So what’s the common/best practice for macros without arguments? – Konrad Rudolph Aug 5 '10 at 9:41
A very good question. I favour making macros long only when needed, so use \newcommand*/\def for macros with no arguments. However, it does not matter for the application of the macro. One place it does matter is when you do an \ifx test: identical macros with no arguments but where one is long and the other is not do not evaluate to 'identical' as far a TeX is concerned. – Joseph Wright Aug 5 '10 at 10:00
I don't know about \WithSuffix (I'd use xparse instead), but \expandafter\newcommand\expandafter*\csname some-name\endcsname{} works fine. Remember that we go past one token with \expandafter. – Joseph Wright Aug 5 '10 at 11:07
We're hoping that xparse means most people have less basic TeX to learn :-) – Joseph Wright Aug 6 '10 at 11:24
The starred variant of \newcommand wasn't introduced by Lamport but by the LaTeX2e team with the LaTeX2e release 1994/12/01. (see usrguide) – Axel Sommerfeldt May 18 '13 at 7:27

From here: "Using the starred version of \newcommand means that the arguments of the defined command cannot contain a blank line or \par. This makes it a lot easier to spot runaway arguments."

-

According to the Companion:

[\newcommand*] defines a [command], that is not, in TeX terms, long. This means that the newly defined command does not accept empty lines or \par.

This is also the default behaviour of \def, while the unstarred version is actually equivalent to \long\def.

-

In the Latex2e for authors (usrguide.pdf) I found section 3.4 relating about all "defin-y" commands:

All the above five ‘defining commands’ now have *-forms that are usually the better form to use when defining commands with arguments, unless any of these arguments is intended to contain whole paragraphs of text. Moreover, if you ever do find yourself needing to use the non-star form then you should ask whether that argument would not better be treated as the contents of a suitably defined environment.

-