Macros
Use macros sparingly. Don't include a kitchen-sink full of macros in an
article length document
Some authors have, over the years, acquired a large macro collection,
and made it a habit to include this collection (their "kitchen-sink") in
every paper they write. I strongly recommend against this practice. An
excessively long list of macros makes a document hard to maintain
and increases the chances of conflicts between macros, or of one macro
inadvertently overriding another (or a predefined command). In
addition, papers with extensive lists of macros, especially those with
complex custom macros that override the default behavior of Latex, are
much harder to process at the publisher's end, as any custom macros will
likely have to be removed, or modified, in order to make the paper
conform to the journal style. The extensive editing at the
publisher's end that this requires in turn increases the chances of
inadvertently introducing errors.
For these reasons, it is best to only include macros that are actually
used in the document. I usually start with a blank slate and add macros
as needed for frequently occurring constructs. I rarely need more than
two or three dozen macros for an article length document, and almost all
of those are harmless "abbreviation type" macros. For a thesis and
other book-length documents a more extensive macro
collection, and more complex macros (e.g., macros defining new
environments), may be appropriate. However, don't fall into the habit
of including your thesis macro set in every paper you write; trim it
down to what you actually need in the paper.
Keep it simple. Avoid complex macros, and use those only
if you really know what you are doing
The more complex a macro is, the greater the chance that something goes
wrong, and the more difficult it will be to diagnose and fix any problems.
With Latex (in contrast to plain TeX), there is rarely a need for
introducing complex macros. Latex has built-in constructs for nearly
everything one would want in a typical mathematical paper. In addition,
there are numerous add-on packages available that provide additional
sets of predefined macros and which can be included with a simple
\usepackage{...} instruction.
Define your own macros, don't copy someone else's
Don't blindly copy someone else's macros, or use someone else's paper
as template, with all the macros preserved.
Chances are that many of these macros are not needed for your own paper,
so you'll end up with an unnecessarily long list of
macros, with all the problems that this entails. Also, since most
authors' TeX skills are less than perfect, you may acquire poorly
constructed macros and bad coding practices.
Finally, if you copy complex macros that someone else has written, but
don't have a real understanding how they work, you'll be unable to
modify or adapt these to a particular situation, and if something goes
wrong with the macro, you'll have a hard time tracking down the error.
If a macro is over your head, don't use it; find a simpler solution
(there almost always is).
Put all macros in a single place near the top of the document, group
macros by function, and put each macro on a separate line
Don't scatter macros throughout the document. If midway through editing
a document you find that could use another macro, insert it in the
preamble at the top of the document. Having all macros in a single place
makes it easier to maintain these macros, and to detect any problems or
inconsistencies.
Similarly, grouping similar macros (e.g., all theorem declarations
(\newtheorem{...}), followed by math font macros (\mathbb{N}), followed
by operator definitions (\operatorname{...}), etc.), and by putting each
macro on a line by itself makes it easier to spot a macro, and the file
more maintainable.
Define macros with \newcommand. Use \renewcommand sparingly if at all,
and avoid \def completely unless you really know what you are doing
"\newcommand" is the Latex way of defining macros; "\def" is the old,
plain TeX style, definition. Using "\newcommand" is far preferable, since
\newcommand checks against existing definitions and generates an error
message if a macro name is in use. By contrast, "\def" happily
overwrites any existing definition; this may cause unexpected errors
that are often hard to track down.
If a "\newcommand" definition generates an error message because of a
conflict with an existing macro, don't try to get rid of the error
message by changing "\newcommand" to "\def". There is a good reason
why Latex produces an error message in the first place, and if you
choose to ignore the message, you risk running into problems associated
with overriding existing definitions.
A slightly safer approach is to replace "\newcommand" by
"\renewcommand", but that, too, is fraught with some risks.
The best way is to eliminate conflicts by changing the name of the macro
to one that is not already defined.
Avoid one letter macros
Many one letter sequences have predefined meanings and thus cause
conflicts if you try to use them for your own macros.
Most of these one-letter macros are part of the TeX core, and usually
not documented in Latex books. Thus, if a macro isn't listed in the
index of a Latex book, it doesn't mean that it is not in use. To be
certain that a macro isn't in use, you would have to check
the original Knuth TeXbook, in addition to a comprehensive Latex
reference.
You can largely avoid running into such problems by using at least two
letters for a macro name. While there exist a few (non-obvious) two letter
sequences that have predefined meanings (e.g., \aa), those are
quite rare and the vast majority of two letter sequences are available
as macro names. For example, to define \mathbf{v}, use \vv, or \bv
(for "bold v"), rather than \v. The latter, \v, is predefined, whereas
both \vv and \bv are available.
Avoid defining macros/abbreviations for \begin{...} or \end{...}
While TeXnically there is nothing wrong with defining,
for example, "\be" and "\ee" as abbreviations for "\begin{equation}"
and "\end{equation}", I try to avoid such abbreviations, for
a number of reasons:
-
As recommended elsewhere,
"\begin{...}" and "\end{...}" commands are best placed on lines by
themselves. This makes these commands stand out in the document and
easier to spot. Using abbreviations like "\be" defeats this purpose.
-
\begin{...} \end{...} pairs are relatively rare, so the time saving in
abbreviations is not very significant. (Note that the most common
such environment, \begin{equation*} .... \end{equation*} for a
single-line, unnumbered, equation, is equivalent to
a backslash-bracket construct: \[ ... \].)
-
If you have many different environments (e.g., theorem, proof,
align, equation, etc.), defining abbreviations for each of these
makes for a very messy and hard to remember set of macros.
-
Editors that are Latex aware recognize the \begin{...} and \end{...}
commands and use these to appropriately colorize the text, but if you
use abbreviations, that feature might be lost.
-
I have written a number of scripts that parse TeX files to look for, and
extract (or otherwise process), particular chunks of text (e.g,
displayed equations, theorems, etc.), delimited by a \begin{...} ....
\end{...} pair. These scripts break if abbreviations are used.
Avoid defining macros for ordinary English words and phrases
I recommend against defining macros as abbreviations for ordinary
words and phrases, e.g, "\rh" for "Riemann Hypothesis", "\ae" for
"almost everywhere", "\rv" for "random variable", etc. While, from a
TeXnical point of view, such abbreviation macros cause
no problems or conflicts, I try to avoid these for a number of reasons:
-
Using macros for English text makes the source file harder to read
and to maintain.
-
Spell checkers will likely skip over macros,
and thus not catch spelling errors in an expression defined by a macro.
-
A macro becomes useless if a variant form of the abbreviated expression
is needed, e.g., a capitalized form at the beginning of a sentence, or a
plural form. It is easy to overlook these special situations and
simply use a macro in a context where it is not appropriate.
-
The spacing surrounding macros requires special attention
since, by default, spaces following a macro are ignored. Thus, for
example, the TeX source code "If the \rh holds" (with "\rh" being macro for
"Riemann Hypothesis", will produce "If the Riemann Hypothesisholds".
If one tries to compensate for this by incorporating
an explicit space in the "\rh" macro, then the above phrase will come out
right, but the macro then cannot be used at the end of a sentence or
right before a comma since there it will have an extraneous space.
-
Lastly, but perhaps most importantly, if a phrase really occurs that
frequently that typing it in full every single time becomes a chore, one
should probably consider introducing an abbreviation for it. For example,
instead of having the phrase "Riemann Hypothesis" dozens of times in a
paper, it would be better to introduce an abbreviation "RH" by saying, at
the first occurrence, "Riemann Hypothesis (RH)", and using "RH" at all
subsequent occurrences.
Some common examples of macro definitions
Here are some common situations where macros are appropriate:
-
"Blackboard-bold" symbols (for the sets N, Q, R):
\newcommand{\RR}{\mathbb{R}}
-
Boldface math symbols (for vectors, etc.):
\newcommand{\vv}{\mathbf{v}}
-
Script letters (for sets, etc.):
\newcommand{\cA}{\mathcal{A}}
-
Letters with diacritical marks, accents, superscripts:
\newcommand{\ah}{\hat{a}}
-
Math operators (e.g., "supp" for support):
\newcommand{\supp}{\operatorname{supp}}
\newcommand{\Ext}{\operatorname{Ext}}
-
Nonstandard structural elements:
Occasionally, one comes across a situation for which is no
obvious or natural Latex structure. An example
is a proof broken down into several explicit "cases" or "steps".
In such situations I would define a macro that takes care of the
appropriate formatting and which can easily be modified if needed.
For example:
\newcommand{\case}[1]{\subsubsection*{#1}}
\newcommand{\step}[1]{\par\medskip\par\noindent\textit{#1}}
With such a macro one can say
"\case{Case 1: $x>0$}" or "\step{Step I: $f(x)$ is linear}"
without having to worry about spacing, fonts, etc.
The main advantage of using a macro here is flexibility. By
redefining the macro it is easy to change the appears with a single
global setting.
Back to the LaTeX Tips Page
Last modified: Tue 23 Aug 2011 05:47:48 PM CDT
A.J. Hildebrand