40

TUGboat, Volume 42 (2021), No. 1

Creating document commands: The good,the bad and the ugly
Joseph WrightCreating document commands in LATEX has traditionally involved a mix of \newcommand, semi-internalkernel commands (like \@ifnextchar and \@ifstar)and low-level TEX programming using \def. As partof wider efforts to improve LATEX, the team haveover the past few years developed ideas for creating
document commands in the package xparse. In aparallel article (on \NewDocumentCommand, on thefollowing pages), I’ve looked at how the xparse ideas
compare to the abilities of other packages.
The aims of xparse have always been two-fold:to provide a clear way to create new commands, andto provide a language to describe existing ones. It
is also intended to be as flexible as possible, so it
doesn’t impose artificial restrictions on syntax. That
comes at a cost, however: it can be (ab)used to createcommands that do not fit into the standard LATEX
pattern.
The LATEX kernel now integrates most, though
not all, of xparse into the kernel. That means the coreideas are available out-of-the-box. This seems like a
good time, therefore, to look at the best ways to use
the abilities of xparse in making document commands.
I won’t look at the full detail, but rather pick out how
to, and how not to, create good document commands.
1second is strictly dependent on the presence of thefirst.
Following the kernel, signatures (argument descriptions) such as:s o ms O{<default>} m mo m mare ‘good’. You can use something likes +m O{0} +o +m(with optional arguments after a mandatory one; thisis the syntax of \newcommand!) if you are careful, butthink very carefully.
There’s one syntax that’s not from the kernel
but is recommended where it applies: the beamer
overlay syntax, which is d<> in xparse terms. This
always comes first (other than a star), and is best reserved for the ‘on X slides of Y’ idea in presentations(doesn’t have to be using beamer).
xparse lets us create arguments using _ and ^,similar to TEX’s core math mode syntax. Most of thetime, this should be reserved for math mode whereyou need to emulate the TEX syntax but for somereason need to grab the arguments yourself. This isdone using e{^_}.
2

The above already shows we have quite a few combinations available. Things go bad when too many
combinations are used. For example:The Good• Multiple optional arguments where the secondor subsequent ones don’t strictly depend on theearlier ones.

The LATEX kernel is very careful to have consistent
syntax for document commands. It uses only a small
number of the possible argument types, which I’ll
describe in xparse terms:• Optional arguments using tokens other than [](or <> for overlays).

• Mandatory (m) arguments in braces.
• Optional (o/O{<default>}) arguments in [],which may have a default; in xparse terms we
can tell the difference between a missing optional
argument and one given with an empty [] pair.
• An optional star (s).
• Picture co-ordinates (r()), which are split into
x and y, so in xparse terms subject to\SplitArgument.
Most of the time, the LATEX kernel makes arguments long, which is shown as + in xparse syntax.
A star is always used as the first argument after
a command, so in some ways it looks like part ofthe command name itself. Optional arguments arealmost always given before mandatory ones, andmost of the time there is only one. Where two areused, for example with \makebox, it’s because theJoseph Wright
doi.org/10.47397/tb/42-1/tb130wright-goodbad

The Bad• Testing for tokens other than * as ‘a special case’(think things like +).
Almost always, complex setups using these typesof combination mean you need to rethink the syntax.
In particular, multiple optional arguments tend to
be much better replaced by using a keyval approach.
3The Ugly

Some ideas in xparse won’t be making it to the kernel:
these are definitely the Ugly. They’ll stay in a stub
xparse for historical reasons, and as they do describe
some syntax choices people have made, but in truth,
they should be avoided:• Optional groups (g) in braces; breaks the LATEX
conventions badly.
• Arguments up to a left brace (l); useful at a lowlevel, but not in a document command.

TUGboat, Volume 42 (2021), No. 141• Arguments up to a token (u); widely used inprogramming, but again not in document commands.
You might wonder why they are all there in thefirst place: these were part of the more experimental
work in xparse, and those particular experiments haveshown we don’t want to enable such syntaxes evenfor emulating existing commands.
4

A Fistful of Tokens

There are of course places where you need to go
outside of the xparse structures, particularly whenparsing specialist data. The popular Tik Z graphics system is one example; linguistic glosses are another. But these are restricted contexts, normallyused within a dedicated environment where it is clearthat the ‘usual’ rules do not apply. Basically, if you
do this, you are on your own, so be sure to check thebalance of consistency versus compactness.
5For a Few Tokens More

Using xparse syntax makes it much easier to have aclear break between interface and implementation.
As such, the fact that it’s got more going on ‘beneaththe hood’ is worth it: it’s a lot easier to track what’s
happening. The move into the kernel will makeusing xparse descriptions even easier to exploit, so it’s
important that users defining their own commands
give a little thought to the syntax they choose.
⋄ Joseph WrightNorthampton, United Kingdom
joseph dot wright (at)morningstar2.co.uk

Creating document commands: The good, the bad and the ugly