Definitions

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:

cmd

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.

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 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.

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 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 counter

Synopsis, 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.

env

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.

nargs

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.

optargdefault

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.

begdef

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.

enddef

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:

name

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.

title

The text to be printed at the beginning of the environment, before the number. For example, ‘Theorem’.

numbered_within

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}.

numbered_like

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}.