
macrosstarred-version

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!)

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.