Examples and rules
15.1.1 Examples and rules
Commands to enhance readability Let us start with a few examples of user-defined commands as shorthand for longer
command(s) or text in order to enhance readability of the source file (Goal 1).
1. If you use the \leftarrow command a lot, you could define \newcommand{\larr}{\leftarrow} Then you would only have to type \larr to obtain a left arrow.
2. Instead of \widetilde{a} you could simply type \wtilda after defining \newcommand{\wtilda}{\widetilde{a}}
I show you how to define a generalized version of such a command in Section 15.1.2.
15.1 User-defined commands 365
3. If you want to suppress the ligature in iff (see Section 5.4.6), you would normally have to type
if\textcompwordmark f By defining a command \Iff, \newcommand{\Iff}{if\textcompwordmark f} you can type \Iff to get iff. We name this command \Iff because \iff is the
symbol ⇐⇒ (see Section B.4).
4. If you use the construct D [2]
×D [3] often, you could introduce the \DxD (
D times
D) command, \newcommand{\DxD}{D^{[2]}\times D^{[3]}} and then type \DxD instead of the longer, and hard to read, version throughout your
document—serves also Goal 2.
5. If you want to get a backslash in typewriter style, you would normally have to type (see Section 5.4.4)
\texttt{\symbol{92}} Instead, you can introduce the \bsl command, \newcommand{\bsl}{\texttt{\symbol{92}}} and \bsl typesets as \.
6. You can also use commands as a shorthand for text. For instance, if you use the phrase subdirectly irreducible many times in your document, you could de- fine
\newcommand{\subdirr}{subdirectly irreducible} \subdirr is now shorthand for subdirectly irreducible, which typesets as
subdirectly irreducible.
Tip With modern editors, the need to have user-defined commands as shorthand is re- duced. Most editors have “command completion” or “phrase completion”. For instance, in TeXShop, type the first few letters of a word and hit the escape key. The remaining letters are entered to match the first entry in the completion dictionary. Hitting escape again cycles through all possible completions. To make this feature useful, you have to customize the completion dictionary.
366 Chapter 15 Customizing L A TEX
Rule
User-defined commands
1. Issue the \newcommand command.
2. In braces, type the name of your new command, for example, \subdirr, including the backslash (\).
3. In a second pair of braces, define the command, in this example, subdirectly irreducible.
4. Use the command as \subdirr\ or \subdirr{} before a space, before an alpha- betical character as \subdirr{}, and \subdirr otherwise.
Examples for Rule 4. For subdirectly irreducible lattice type \subdirr{} lattice
or
\subdirr\ lattice
and not \subdirr lattice. Indeed, typesetting \subdirr lattice results in sub- directly irreduciblelattice. By the first spacing rule, \subdirr lattice is not any better (see Section 5.2.1). If you want subdirectly irreducibles, you must use the \subdirr{} form. Indeed, \subdirr{}s typesets as subdirectly irreducibles.
Using new commands It is good practice to place user-defined commands in the preamble of your document or
in a command (style) file you load with a \usepackage command (see Section 15.3)— provided that you do not submit to a journal that does not allow this. Then you always know where to look for the command definitions. An exception is a user-defined com- mand that you want to restrict to a part of the document. Delimit the segment with braces and define the user-defined command within those braces (see Section 5.3.2). Instead of a pair of braces, you can use \begingroup and \endgroup, which is easier to see. Section 15.2.5 recommends yet another approach.
Tip If errors occur, isolate the problem. Comment out the user-defined commands and
reintroduce them one at a time. L A TEX only checks whether the braces match in the command definition. Other mis-
takes are found only when the command is used.
For instance, if you define a command with a spelling error \newcommand{\bfA}{\textf{A}} then at the first use of \bfA you get the error message
15.1 User-defined commands 367
! Undefined control sequence. \bfA ->\textf
{A} Note that L A TEX is not complaining about \bfA but about the misspelled \textbf com-
mand in the definition of \bfA. Be careful not to define a user-defined command with a name that is already in use. If you do, you get an error message such as
! LaTeX Error: Command \larr already defined. To correct the error, replace the command name with a new one. On the other hand, if
you need to replace an existing command, you have to redefine it. See Section 15.1.5 for how to do so.
Tip Use spaces to make your source files more readable, but avoid them in definitions.
For example, you may type $D^{ \langle 2 \rangle } + 2 = x^{ \mathbf{a} }$ This may help you see how the braces match, easily identify relations and operations,
and so on. Do not add these spaces in command definitions because it may result in unwanted spaces in your typeset document. You may start a new line to increase the readability of a command definition, provided that you terminate the previous line with %. For instance, borrowing an example from page 372:
\newcommand{\Xquotphi}[2]{% \dfrac{\varphi \cdot X_{n, #1}}% {\varphi_{#2}\times \varepsilon_{#1}}}
Tip In the definition of a new command, command declarations need an extra pair of braces (see Section 5.3.3).
Say you want to define a command that typesets the warning: Do not redefine this variable! It is very easy to make the following mistake:
\newcommand{\Warn}{\em Do not redefine this variable!} \Warn typesets the warning emphasized, but everything that follows the warning is also
emphasized (more precisely, until the end of the \Warn command’s scope). Indeed, \Warn is replaced by \em Do not redefine this variable! so the effect of \em goes beyond the sentence to the next closing brace.
368 Chapter 15 Customizing L A TEX The correct definition is
\newcommand{\Warn}{{\em Do not redefine this variable!}} Even simpler, you could use a command with an argument \newcommand{\Warn}{\emph{Do not redefine this variable!}}
The xspace package Rule 4 (on page 366) is the source of many annoying problems in L A TEX. David
Carlisle’s xspace package (see Section 12.3.1) helps eliminate such problems. In the preamble, load the package with
\usepackage{xspace} Whenever you define a command that may have such problems, add the \xspace com-
mand to the definition. For instance, define \subdirr as \newcommand{\subdirr}{subdirectly irreducible\xspace} Then all the following typesets subdirectly irreducible lattice correctly:
\subdirr\ lattice \subdirr{} lattice \subdirr lattice
Note that \xspace does not add space if followed by a punctuation mark, so to get
the lattice is subdirectly irreducible. type
the lattice is \subdirr.
Tip Be careful not to use \xspace twice in a definition. For instance, if you define
\newcommand{\tex}{\TeX\xspace} \newcommand{\bibtex}{\textsc{Bib}\kern-.1em\tex\xspace}% Bad!!!
then \bibtex, followed by a comma
15.1 User-defined commands 369
typesets as
BibTEX , followed by a comma The correct definitions are
\newcommand{\tex}{\TeX\xspace} \newcommand{\bibtex}{\textsc{Bib}\kern-.1em\TeX\xspace}% Correct!
Of course, if you want to get TEXbook, you cannot use \xspace variant definition: \tex.
Ensuring math The \ensuremath command is useful for defining commands that work in both text
and math mode. Suppose you want to define a command for D h2i . If you define it as \newcommand{\Dsq}{D^{\langle2\rangle}} then you can use the command in math mode, but not in text mode. If you define it as \newcommand{\Dsq}{$D^{\langle2\rangle}$} then it works in text mode, but not in math mode. Instead, define this command as \newcommand{\Dsq}{\ensuremath{D^{\langle2\rangle}}} Then \Dsq works correctly in both contexts.
This example also shows the editorial advantages of user-defined commands. Sup- pose the referee suggests that you change the notation to D [2] . To carry out the change you only have to change one line:
\newcommand{\Dsq}{\ensuremath{D^{[2]}}} It is hard to overemphasize the importance of this example. You may want to
change notation because: you found a better notation; your coauthor insists; your article appears in a conference proceedings, and the editor wants to unify the
notation; you are reusing the code from this article in another one or in a book, where the
notation is different.
See also the discussion of the \TextOrMath command on page 311.
370 Chapter 15 Customizing L A TEX