LaTeX has support for making new commands of many different kinds.
\newcommand
& \renewcommand
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 requires that the arguments not contain
multiple paragraphs of text (in plain TeX terms that it not be
\long
).
These are the parameters:
Required; the command name. It must begin with a backslash, \
,
and must not begin with the four letter 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 this argument 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.
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 spaces in the source following an alphabetic control
sequence, 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\ ’).
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 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 command definition has no arguments, and the second has 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, 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}}
.
\providecommand
Synopses, one of:
\providecommand{cmd}{defn} \providecommand{cmd}[nargs]{defn} \providecommand{cmd}[nargs][optargdefault]{defn} \providecommand*{cmd}{defn} \providecommand*{cmd}[nargs]{defn} \providecommand*{cmd}[nargs][optargdefault]{defn}
Defines a command, as long as no command of this name already exists.
If no command of this name already exists then this has the same effect
as \newcommand
. If a command of this name already exists then
this definition does nothing. This is particularly useful in a file
that may be loaded more than once, such as a style file.
See \newcommand & \renewcommand for the description of the arguments.
This example
\providecommand{\myaffiliation}{Saint Michael's College} \providecommand{\myaffiliation}{Saint Michael's College} From \myaffiliation.
outputs ‘From Saint Michael's College’. Unlike \newcommand
,
the repeated use of \providecommand
does not give an error.
\makeatletter
& \makeatother
Synopsis:
\makeatletter ... definition of commands with @ in their name .. \makeatother
Use this pair when you redefine LaTeX commands that are named with an
at-sign character ‘@
’. The \makeatletter
declaration makes the at-sign character have the category code of a
letter, code 11. The \makeatother
declaration sets the
category code of the at-sign to code 12, its default value.
As TeX reads characters, it assigns each one a category code, or
catcode. For instance, it assigns the backslash
character ‘\
’ the catcode 0. Command names
consist of a category 0 character, ordinarily backslash, followed
by letters, category 11 characters (except that a command name can
also consist of a category 0 character followed by a single
non-letter symbol).
LaTeX’s source code has the convention that some commands use
@
in their name. These commands are mainly intended for package
or class writers. The convention prevents authors who are just using a
package or class from accidentally replacing such a command with one of
their own, because by default the at-sign has catcode 12.
The pair \makeatletter
and \makeatother
changes the
default code and then changes it back. Use them inside a .tex
file, in the preamble, when you are defining or redefining commands
named with @
, by having them surround your definition. Don’t
use these inside .sty or .cls files since the
\usepackage
and \documentclass
commands already arrange
that the at-sign has the character code of a letter, catcode 11.
For a comprehensive list of macros with an at-sign in their names see http://ctan.org/pkg/macros2e.
In this example the class file has a command
\thesis@universityname
that the user wants to change. These
three lines should go in the preamble, before the
\begin{document}
.
\makeatletter \renewcommand{\thesis@universityname}{Saint Michael's College} \makeatother
\@ifstar
Synopsis:
\newcommand{\mycmd}{\@ifstar{\mycmd@star}{\mycmd@nostar}} \newcommand{\mycmd@nostar}[nostar-num-args]{nostar-body} \newcommand{\mycmd@star}[star-num-args]{star-body}
Many standard LaTeX environments or commands have a variant with the
same name but ending with a star character *
, an asterisk.
Examples are the table
and table*
environments and the
\section
and \section*
commands.
When defining environments, following this pattern is straightforward
because \newenvironment
and \renewenvironment
allow the
environment name to contain a star. For commands the situation is more
complex. As in the synopsis above, there will be a user-called command,
given above as \mycmd
, which peeks ahead to see if it is followed
by a star. For instance, LaTeX does not really have a
\section*
command; instead, the \section
command peeks
ahead. This command does not accept arguments but instead expands to
one of two commands that do accept arguments. In the synopsis these two
are \mycmd@nostar
and \mycmd@star
. They could take the
same number of arguments or a different number, or no arguments at all.
As always, in a LaTeX document a command using at-sign @
must be enclosed inside a \makeatletter ... \makeatother
block
(see \makeatletter & \makeatother).
This example of \@ifstar
defines the command \ciel
and a
variant \ciel*
. Both have one required argument. A call to
\ciel{night}
will return "starry night sky" while
\ciel*{blue}
will return "starry not blue sky".
\newcommand*{\ciel@unstarred}[1]{starry #1 sky} \newcommand*{\ciel@starred}[1]{starry not #1 sky} \newcommand*{\ciel}{\@ifstar{\ciel@starred}{\ciel@unstarred}}
In the next example, the starred variant takes a different number of
arguments than the unstarred one. With this definition, Agent 007’s
``My name is \agentsecret*{Bond},
\agentsecret{James}{Bond}.''
is equivalent to entering the commands
``My name is \textsc{Bond}, \textit{James} textsc{Bond}.''
\newcommand*{\agentsecret@unstarred}[2]{\textit{#1} \textsc{#2}} \newcommand*{\agentsecret@starred}[1]{\textsc{#1}} \newcommand*{\agentsecret}{% \@ifstar{\agentsecret@starred}{\agentsecret@unstarred}}
There are two sometimes more convenient ways to accomplish the work of
\@ifstar
. The suffix package allows the construct
\newcommand\mycommand{unstarred version}
followed by
\WithSuffix\newcommand\mycommand*{starred version}
. And
LaTeX3 has the xparse package that allows this code.
\NewDocumentCommand\foo{s}{\IfBooleanTF#1 {starred version}% {unstarred version}% }
\newcounter
: Allocating a counterSynopsis, one of:
\newcounter{countername} \newcounter{countername}[supercounter]
Globally defines a new counter named countername and initialize it to zero (see Counters).
The name countername must consist of letters only. It does not begin with a backslash. This name must not already be in use by another counter.
When you use the optional argument [supercounter]
then the
counter countername will be reset to zero whenever
supercounter is incremented. For example, ordinarily
subsection
is numbered within section
so that any time you
increment section, either with \stepcounter
(see \stepcounter) or \refstepcounter
(see \refstepcounter), then LaTeX will reset subsection to
zero.
This example
\newcounter{asuper} \setcounter{asuper}{1} \newcounter{asub}[asuper] \setcounter{asub}{3} % Note `asuper' The value of asuper is \arabic{asuper} and of asub is \arabic{asub}. \stepcounter{asuper} Now asuper is \arabic{asuper} while asub is \arabic{asub}.
produces ‘The value of asuper is 1 and that of asub is 3’ and ‘Now asuper is 2 while asub is 0’.
If the counter already exists, for instance by entering asuper
twice, then you get something like ‘LaTeX Error: Command \c@asuper
already defined. Or name \end... illegal, see p.192 of the manual.’.
If you use the optional argument then the super counter must already
exist. Entering \newcounter{jh}[lh]
when lh
is not a
defined counter will get you ‘LaTeX Error: No counter 'lh'
defined.’
\newlength
Synopsis:
\newlength{arg}
Allocate a new length register (see Lengths). The required argument
arg must begin with a backslash, \
. The new register holds
rubber lengths such as 72.27pt
or 1in plus.2in minus.1in
(a LaTeX length register is what plain TeX calls a skip
register). The initial value is zero. The control sequence
\arg
must not be already defined.
An example:
\newlength{\graphichgt}
If you forget the backslash then you get ‘Missing control sequence inserted’. If the command sequence already exists then you get something like ‘LaTeX Error: Command \graphichgt already defined. Or name \end... illegal, see p.192 of the manual’.
\newsavebox
Synopsis:
\newsavebox{\cmd}
Define \cmd, the string consisting of a backslash followed by cmd, to refer to a new bin for storing material. These bins hold material that has been typeset, to use multiple times or to measure or manipulate (see Boxes). The bin name \cmd is required, must start with a backslash, \, and must not already be a defined command. This command is fragile (see \protect).
This allocates a bin and then puts typeset material into it.
\newsavebox{\logobox} \savebox{\logobox}{LoGo} Our logo is \usebox{\logobox}.
The output is ‘Our logo is LoGo’.
If there is an already defined bin then you get something like ‘LaTeX Error: Command \logobox already defined. Or name \end... illegal, see p.192 of the manual’.
The allocation of a box is global.
\newenvironment
& \renewenvironment
Synopses, one of:
\newenvironment{env}{begdef}{enddef} \newenvironment{env}[nargs]{begdef}{enddef} \newenvironment{env}[nargs][optargdefault]{begdef}{enddef} \newenvironment*{env}{begdef}{enddef} \newenvironment*{env}[nargs]{begdef}{enddef} \newenvironment*{env}[nargs][optargdefault]{begdef}{enddef}
or one of these.
\renewenvironment{env}{begdef}{enddef} \renewenvironment{env}[nargs]{begdef}{enddef} \renewenvironment{env}[nargs][optargdefault]{begdef}{enddef} \renewenvironment*{env}{begdef}{enddef} \renewenvironment*{env}[nargs]{begdef}{enddef} \renewenvironment*{env}[nargs][optargdefault]{begdef}{enddef}
Define or redefine the environment env, that is, create the
construct \begin{env} ... body ... \end{env}
.
The starred form of these commands requires that the arguments not contain multiple paragraphs of text. However, the body of these environments can contain multiple paragraphs.
Required; the environment name. It consists only of letters or the
*
character, and thus does not begin with backslash, \
.
It must not begin with the string end
. For
\newenvironment
, the name env must not be the name of an
already existing environment, and also the command \env
must be undefined. For \renewenvironment
, env must be the
name of an existing environment.
Optional; an integer from 0 to 9 denoting the number of arguments of
that the environment takes. When you use the environment these
arguments appear after the \begin
, as in
\begin{env}{arg1} ... {argn}
. Omitting
this is equivalent to setting it to 0; the environment will have no
arguments. When redefining an environment, the new version can have a
different number of arguments than the old version.
Optional; if this is present then the first argument of the defined environment is optional, with default value optargdefault (which may be the empty string). If this is not in the definition then the environment does not take an optional argument.
That is, when optargdefault is present in the definition of the
environment then you can start the environment with square brackets, as
in \begin{env}[optval]{...} ... \end{env}
.
In this case, within begdefn the parameter #1
is set to the
value of optval. If you call \begin{env}
without
square brackets, then within begdefn the parameter #1
is
set to the value of the default optargdefault. In either case,
any required arguments start with #2
.
Omitting [myval]
in the call is different than having the
square brackets with no contents, as in []
. The former results
in #1
expanding to optargdefault; the latter results in
#1
expanding to the empty string.
Required; the text expanded at every occurrence of
\begin{env}
. Within begdef, the parameters
#1
, #2
, ... #nargs
, are replaced by the
values that you supply when you call the environment; see the examples
below.
Required; the text expanded at every occurrence of
\end{env}
. This may not contain any parameters, that is,
you cannot use #1
, #2
, etc., here (but see the final
example below).
All environments, that is to say the begdef code, the environment
body, and the enddef code, are processed within a group. Thus, in
the first example below, the effect of the \small
is limited to
the quote and does not extend to material following the environment.
If you try to define an environment 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 an environment and the name has not yet been used then you get something like ‘LaTeX Error: Environment hank undefined.’.
This example gives an environment like LaTeX’s quotation
except that it will be set in smaller type.
\newenvironment{smallquote}{% \small\begin{quotation} }{% \end{quotation} }
This has an argument, which is set in boldface at the start of a paragraph.
\newenvironment{point}[1]{% \noindent\textbf{#1} }{% }
This one shows the use of a optional argument; it gives a quotation environment that cites the author.
\newenvironment{citequote}[1][Shakespeare]{% \begin{quotation} \noindent\textit{#1}: }{% \end{quotation} }
The author’s name is optional, and defaults to ‘Shakespeare’. In the document, use the environment like this.
\begin{citequote}[Lincoln] ... \end{citequote}
The final example shows how to save the value of an argument to use in enddef, in this case in a box (see \sbox & \savebox).
\newsavebox{\quoteauthor} \newenvironment{citequote}[1][Shakespeare]{% \sbox\quoteauthor{#1}% \begin{quotation} }{% \hspace{1em plus 1fill}---\usebox{\quoteauthor} \end{quotation} }
\newtheorem
Synopses:
\newtheorem{name}{title} \newtheorem{name}{title}[numbered_within] \newtheorem{name}[numbered_like]{title}
Define a new theorem-like environment. You can specify one of numbered_within and numbered_like, or neither, but not both.
The first form, \newtheorem{name}{title}
, creates
an environment that will be labelled with title; see the first
example below.
The second form,
\newtheorem{name}{title}[numbered_within]
,
creates an environment whose counter is subordinate to the existing
counter numbered_within, so this counter will be reset when
numbered_within is reset. See the second example below.
The third form
\newtheorem{name}[numbered_like]{title}
,
with optional argument between the two required arguments, creates an
environment whose counter will share the previously defined counter
numbered_like. See the third example.
This command creates a counter named name. In addition, unless
the optional argument numbered_like is used, inside of the
theorem-like environment the current \ref
value will be that of
\thenumbered_within
(see \ref).
This declaration is global. It is fragile (see \protect).
Arguments:
The name of the environment. It is a string of letters. It must not
begin with a backslash, \
. It must not be the name of an
existing environment, and the command name \name
must not
already be defined.
The text to be printed at the beginning of the environment, before the number. For example, ‘Theorem’.
Optional; the name of an already defined counter, usually a sectional
unit such as chapter
or section
. When the
numbered_within counter is reset then the name environment’s
counter will also be reset.
If this optional argument is not used then the command
\thename
is set to \arabic{name}
.
Optional; the name of an already defined theorem-like environment. The new environment will be numbered in sequence with numbered_like.
Without any optional arguments the environments are numbered sequentially. The example below has a declaration in the preamble that results in ‘Definition 1’ and ‘Definition 2’ in the output.
\newtheorem{defn}{Definition} \begin{document} \section{...} \begin{defn} First def \end{defn} \section{...} \begin{defn} Second def \end{defn}
This example has the same document body as the prior one. But here
\newtheorem
’s optional argument numbered_within is given as
section
, so the output is like ‘Definition 1.1’ and
‘Definition 2.1’.
\newtheorem{defn}{Definition}[section] \begin{document} \section{...} \begin{defn} First def \end{defn} \section{...} \begin{defn} Second def \end{defn}
In the next example there are two declarations in the preamble, the
second of which calls for the new thm
environment to use the same
counter as defn
. It gives ‘Definition 1.1’, followed
by ‘Theorem 2.1’ and ‘Definition 2.2’.
\newtheorem{defn}{Definition}[section] \newtheorem{thm}[defn]{Theorem} \begin{document} \section{...} \begin{defn} First def \end{defn} \section{...} \begin{thm} First thm \end{thm} \begin{defn} Second def \end{defn}
\newfont
This command is obsolete. This description is here only to help with old documents. New documents should define fonts in families through the New Font Selection Scheme which allows you to, for example, associate a boldface with a roman (see Fonts).
Synopsis:
\newfont{\cmd}{font description}
Define a command \cmd
that will change the current font.
The control sequence must not already be defined. It must begin with a
backslash, \
.
The font description consists of a fontname and an optional
at clause. LaTeX will look on your system for a file named
fontname.tfm. The at clause can have the form either
at dimen
or scaled factor
, where a
factor of ‘1000’ means no scaling. For LaTeX’s purposes,
all this does is scale all the character and other font dimensions
relative to the font’s design size, which is a value defined in the
.tfm file.
This defines two equivalent fonts and typesets a few characters in each.
\newfont{\testfontat}{cmb10 at 11pt} \newfont{\testfontscaled}{cmb10 scaled 1100} \testfontat abc \testfontscaled abc
\protect
All LaTeX commands are either fragile or robust. A
fragile command can break when it is used in the argument to certain
other commands. Commands that contain data that LaTeX writes to an
auxiliary file and re-reads later are fragile. This includes material
that goes into a table of contents, list of figures, list of tables,
etc. Fragile commands also include line breaks, any command that has an
optional argument, and many more. To prevent such commands from
breaking, one solution is to preceded them with the command
\protect
.
For example, when LaTeX runs the \section{section
name}
command it writes the section name text to the
.aux auxiliary file, moving it there for use elsewhere in the
document such as in the table of contents. Any argument that is
internally expanded by LaTeX without typesetting it directly is
referred to as a
moving argument. A command is fragile if it can
expand during this process into invalid TeX code. Some examples of
moving arguments are those that appear in the \caption{...}
command (see figure), in the \thanks{...}
command
(see \maketitle), and in @-expressions in the tabular
and
array
environments (see tabular).
If you get strange errors from commands used in moving arguments, try
preceding it with \protect
. Every fragile commands must be
protected with their own \protect
.
Although usually a \protect
command doesn’t hurt, length
commands are robust and should not be preceded by a \protect
command. Nor can a \protect
command be used in the argument to
\addtocounter
or \setcounter
command.
In this example the \caption
command gives a mysterious error
about an extra curly brace. Fix the problem by preceding each
\raisebox
command with \protect
.
\begin{figure} ... \caption{Company headquarters of A\raisebox{1pt}{B}\raisebox{-1pt}{C}} \end{figure}
In the next example the \tableofcontents
command gives an error
because the \(..\)
in the section title expands to illegal TeX
in the .toc file. You can solve this by changing \(..\)
to \protect\(..\protect\)
.
\begin{document} \tableofcontents ... \section{Einstein's \( e=mc^2 \)} ...
\ignorespaces & \ignorespacesafterend
Synopsis:
\ignorespaces
or
\ignorespacesafterend
Both commands cause LaTeX to ignore spaces after the end of the command up until the first non-space character. The first is a command from Plain TeX, and the second is LaTeX-specific.
The ignorespaces
is often used when defining commands via
\newcommand
, or \newenvironment
, or \def
. The
example below illustrates. It allows a user to show the points values
for quiz questions in the margin but it is inconvenient because, as
shown in the enumerate
list, users must not put any space between
the command and the question text.
\newcommand{\points}[1]{\makebox[0pt]{\makebox[10em][l]{#1~pts}} \begin{enumerate} \item\points{10}no extra space output here \item\points{15} extra space between the number and the `extra' \end{enumerate}
The solution is to change to this.
\newcommand{\points}[1]{% \makebox[0pt]{\makebox[10em][l]{#1~pts}}\ignorespaces}
A second example shows spaces being removed from the front of text. The
commands below allow a user to uniformly attach a title to names. But,
as given, if a title accidentally starts with a space then
\fullname
will reproduce that.
\makeatletter \newcommand{\honorific}[1]{\def\@honorific{#1}} % remember title \newcommand{\fullname}[1]{\@honorific~#1} % put title before name \makeatother \begin{tabular}{|l|} \honorific{Mr/Ms} \fullname{Jones} \\ % no extra space here \honorific{ Mr/Ms} \fullname{Jones} % extra space before title \end{tabular}
To fix this, change to
\newcommand{\fullname}[1]{\ignorespaces\@honorific~#1}
.
The \ignorespaces
is also often used in a \newenvironment
at the end of the begin clause, that is, as part of the second
argument, as in \begin{newenvironment}{env
name}{... \ignorespaces}{...}
.
To strip spaces off the end of an environment use
\ignorespacesafterend
. An example is that this will show a much
larger vertical space between the first and second environments than
between the second and third.
\newenvironment{eq}{\begin{equation}}{\end{equation}} \begin{eq} e=mc^2 \end{eq} \begin{equation} F=ma \end{equation} \begin{equation} E=IR \end{equation}
Putting a comment character %
immediately after the
\end{eq}
will make the vertical space disappear, but that is
inconvenient. The solution is to change to
\newenvironment{eq}{\begin{equation}}{\end{equation}\ignorespacesafterend}
.