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




### 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 "$$" and "$$", 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.