UK TeX FAQ -- question label cmdstar

### Commands defined with * options

LaTeX commands commonly have “versions” defined with an asterisk tagged onto their name: for example `\``newcommand` and `\``newcommand*` (the former defines a `\``long` version of the command).

The simple-minded way for a user to write such a command involves use of the ifthen package:

>     \newcommand{\mycommand}[1]{\ifthenelse{\equal{#1}{*}}%
>       {\mycommandStar}%
>       {\mycommandNoStar{#1}}%
>     }
>     \newcommand{\mycommandStar}{starred version}
>     \newcommand{\mycommandNoStar}[1]{normal version}

This does the trick, for sufficiently simple commands, but it has various tiresome failure modes, and it requires `\``mycommandnostar` to take an argument.

The LaTeX kernel does a lot of this, and has its own command, `\``@ifstar` (which needs ‘internal command protection’, cf.

>     \makeatletter
>     \newcommand{\mycommand}{%
>                  \@ifstar
>                       \mycommandStar%
>                       \mycommandNoStar%
>     \makeatother
>     }
>     \newcommand{\mycommandStar}{starred version}
>     \newcommand{\mycommandNoStar}{normal version}

(Note that arguments to `\``mycommandStar` and `\``mycommandNoStar` are independent — either can have their own arguments, unconstrained by the technique we’re using, unlike the trick described above.) The `\``@ifstar` trick is all very well, is fast and efficient, but it requires that the definition be `\``makeatletter` protected.

A pleasing alternative is the suffix package. This elegant piece of code allows you to define variants of your commands:

>     \newcommand\mycommand{normal version}
>     \WithSuffix\newcommand\mycommand*{starred version}

The package needs e-LaTeX, but any new enough distribution defines LaTeX as e-LaTeX by default. Command arguments may be specified in the normal way, in both command definitions (after the “`*`” in the `\``WithSuffix` version). You can also use the TeX primitive commands, creating a definition like:

>     \WithSuffix\gdef\mycommand*{starred version}

For those of an adventurous disposition, a further option is to use the xparse package from the l3packages distribution. The package defines a bunch of commands (such as `\``NewDocumentCommand`) which are somewhat analagous to `\``newcommand` and the like, in LaTeX2e. The big difference is the specification of command arguments; for each argument, you have a set of choices in the command specification. So, to create a *-command (in LaTeX2e style), one might write:

>     \NewDocumentCommand \foo { s m } {%
>       % #1 is the star indicator
>       % #2 is a mandatory argument
>       ...
>     }

The “star indicator” (`s`) argument appears as `#1` and will take values `\``BooleanTrue` (if there was a star) or `\``BooleanFalse` (otherwise); the other (`m`) argument is a normal TeX-style mandatory argument, and appears as `#2`.

While xparse provides pleasing command argument specifications, it is part of the LaTeX 3 experimental harness. Simply loading the package to provide `\``DeclareDocumentCommand` “pulls in” all of the LaTeX3 kernel (a large bunch of packages) via the expl3 package.

`ifthen.sty`
  Part of the LaTeX distribution
`suffix.sty`
  Distributed as part of macros/latex/contrib/bigfoot (or browse the directory); catalogue entry
`xparse.sty`
  Distributed as part of macros/latex/contrib/l3packages (or browse the directory); catalogue entry
`expl3.sty`
  Distributed as part of macros/latex/contrib/l3kernel (or browse the directory); catalogue entry

This answer last edited: 2014-04-04

This question on the Web: http://www.tex.ac.uk/cgi-bin/texfaq2html?label=cmdstar