Next: , Up: Definitions   [Contents][Index]


Synopses, one of:

\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 one of these.

\renewcommand{\cmd}[nargs]{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 the discussion of \DeclareRobustCommand in Class and package commands).

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

These are the parameters:

cmd


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 optargsdefault is not present then \cmd does not take an optional argument.

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

Omitting [optargdefault] is different from having the square brackets with no contents, as in []. The former sets #1 to the value of optargdefault; the latter sets #1 to the empty string.

defn

Required; the text to be substituted for every occurrence of \cmd. The parameters #1, #2, ... #nargs are replaced by the values that you supply when you call the command (or by the default value if there is an optional argument and you don’t exercise the option).

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


If you try to define a command and the 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’. If you try to redefine a command and the name has not yet been used then you get something like ‘LaTeX Error: \hank undefined’.

Here the first definition creates a command with no arguments, and the second, one 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, the 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’ would incorrectly be in italics. The solution is to put another pair of braces inside the definition: \newcommand{\shipname}[1]{{\it #1}}.