\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):
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.
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.
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.
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}}.