12.1 \newcommand & \renewcommand

Synopses, one of (three regular forms, three starred forms):

\newcommand{\cmd}{defn}
\newcommand{\cmd}[nargs]{defn}
\newcommand{\cmd}[nargs][optargdefault]{defn}
\newcommand*{\cmd}{defn}
\newcommand*{\cmd}[nargs]{defn}
\newcommand*{\cmd}[nargs][optargdefault]{defn}

or the same six possibilities with \renewcommand instead of \newcommand:

\renewcommand{\cmd}{defn}
\renewcommand{\cmd}[nargs]{defn}
\renewcommand{\cmd}[nargs][optargdefault]{defn}
\renewcommand*{\cmd}{defn}
\renewcommand*{\cmd}[nargs]{defn}
\renewcommand*{\cmd}[nargs][optargdefault]{defn}

Define or redefine a command (see also \DeclareRobustCommand in Class and package commands).

The starred form of these two forbids the arguments from containing multiple paragraphs of text (i.e., a \par token; in plain TeX terms: the commands are not \long). With the default form, arguments can be multiple paragraphs.

These are the parameters (examples follow):

cmd

Required; \cmd is the command name. It must begin with a backslash, \, and must not begin with the four character string \end. For \newcommand, it must not be already defined. For \renewcommand, this name must already be defined.

nargs

Optional; an integer from 0 to 9, specifying the number of arguments that the command takes, including any optional argument. Omitting this argument is the same as specifying 0, meaning that the command has no arguments. If you redefine a command, the new version can have a different number of arguments than the old version.

optargdefault

Optional; if this argument is present then the first argument of \cmd is optional, with default value optargdefault (which may be the empty string). If optargdefault is not present then \cmd does not take an optional argument.

That is, if \cmd is called with a following argument in square brackets, as in \cmd[optval]{...}..., then within defn the parameter #1 is set to optval. On the other hand, if \cmd is called without following square brackets then within defn the parameter #1 is set to optargdefault. In either case, the required arguments start with #2.

Omitting [optargdefault] from the definition is entirely different from giving the square brackets with empty contents, as in []. The former says the command being defined takes no optional argument, so #1 is the first required argument (if nargs ≥ 1); the latter sets the optional argument #1 to the empty string as the default, if no optional argument was given in the call.

Similarly, omitting [optval] from a call is also entirely different from giving the square brackets with empty contents. The former sets #1 to the value of optval (assuming the command was defined to take an optional argument); the latter sets #1 to the empty string, just as with any other value.

If a command is not defined to take an optional argument, but is called with an optional argument, the results are unpredictable: there may be a LaTeX error, there may be incorrect typeset output, or both.

defn

Required; the text to be substituted for every occurrence of \cmd. The parameters #1, #2, …, #nargs are replaced by the values supplied when the command is called (or by optargdefault in the case of an optional argument not specified in the call, as just explained).

TeX ignores blanks in the source following a control word (see Control sequence, control word and control symbol), as in ‘\cmd ’. If you want a space there, one solution is to type {} after the command (‘\cmd{} ’), and another solution is to use an explicit control space (‘\cmd\ ’).

A simple example of defining a new command: \newcommand{\RS}{Robin Smith} results in \RS being replaced by the longer text. Redefining an existing command is similar: \renewcommand{\qedsymbol}{{\small QED}}.

If you use \newcommand and the command name has already been used then you get something like ‘LaTeX Error: Command \fred already defined. Or name \end... illegal, see p.192 of the manual’. Similarly, If you use \renewcommand and the command name has not been defined then you get something like ‘LaTeX Error: \hank undefined’.

Here the first definition creates a command with no arguments, and the second, a command with one required argument:

\newcommand{\student}{Ms~O'Leary}
\newcommand{\defref}[1]{Definition~\ref{#1}}

Use the first as in I highly recommend \student{} to you. The second has a variable argument, so that \defref{def:basis} expands to Definition~\ref{def:basis}, which ultimately expands to something like ‘Definition~3.14’.

Similarly, but with two required arguments: \newcommand{\nbym}[2]{$#1 \times #2$} is invoked as \nbym{2}{k}.

This example has an optional argument.

\newcommand{\salutation}[1][Sir or Madam]{Dear #1:}

Then \salutation gives ‘Dear Sir or Madam:’ while \salutation[John] gives ‘Dear John:’. And \salutation[] gives ‘Dear :’.

This example has an optional argument and two required arguments.

\newcommand{\lawyers}[3][company]{#2, #3, and~#1}
I employ \lawyers[Howe]{Dewey}{Cheatem}.

The output is ‘I employ Dewey, Cheatem, and Howe.’. The optional argument, Howe, is associated with #1, while Dewey and Cheatem are associated with #2 and #3. Because of the optional argument, \lawyers{Dewey}{Cheatem} will give the output ‘I employ Dewey, Cheatem, and company.’.

The braces around defn do not define a group, that is, they do not delimit the scope of the result of expanding defn. For example, with \newcommand{\shipname}[1]{\it #1}, in this sentence,

The \shipname{Monitor} met the \shipname{Merrimac}.

the words ‘met the’, and the period, would incorrectly be in italics. The solution is to put another pair of braces inside the definition: \newcommand{\shipname}[1]{{\it #1}}.


Unofficial LaTeX2e reference manual