Some macros for making TeX source more readable

The TeX typesetting system is a lovely bit of software: one can easily use it to typeset production-grade documents such as mathematical papers. However, typesetting complex equations can be tedious, learning to use TeX well can involve memorizing a large number of macros, and it can be difficult to understand the meaning of an equation from looking purely at its source. TeX can be made more readable by utilizing packages and introducing macros to simplify code.

Some time ago, I moved for handwritten note-taking to a fully paperless workflow: more-or-less every bit of mathematics I work on is written either on a whiteboard, or in LaTeX directly, including over 100 pages of notes from a functional analysis course, which I typeset in real time as the lectures were being given. This post contains a collection of useful macros that made this possible.

Overloading accent macros in math mode

One-character macros are an important part of readable LaTeX. Consider the union symbol $\cup$ given by the macro \cup – this describes the shape of the symbol, not its meaning, which would be better described by \union, or more concisely, \u.

Unfortunately, the macro \u is already defined by LaTeX to be the underline macro for text mode. Since the symbol $\cup$ is only used in math mode to begin with, it makes sense for us to extend \u without changing the original functionality. This may be achieved by writing

\let\textu\u % redefinition: underline
\renewcommand{\u}{\relax\ifmmode\cup\else\expandafter\textu\fi} % union

which redefines \u in math mode only. This is achieved by first copying the original definition of \u to \textu. Then, \ifmmode is used to check if LaTeX is in math mode: if it is, \u expands to \cup, if not, it expands to \expandafter\textu. Since \textu is a LaTeX macro which accept an argument, it is important that it is expanded after \ifmmode is completed, otherwise \fi would become its argument, resulting in an error. This is achieved via \expandafter, which causes \textu to be expanded after the redefined \u has completed.

Similarly, one can use this trick to redefine \v to make a symbol bold italic – a widely-used notation for vectors. Redefinition is done the same way, except we use \expandafter\boldsymbol in place of \cup. The \expandafter similarly allows \boldsymbol to correctly accept an input argument. This lets one to write $\v{x}$ to produce $\v{x}$ while still writing \v{c} to produce č, avoiding bibliography errors in cases where eastern European author names are present.

I use this trick everywhere: \P becomes the probability symbol $\P$, and \c{X} becomes a calligraphic X, i.e. $\c{X}$, while their original definitions in text mode are retained. This helps make my source easier to read and write, and goes a long way toward it possible to typeset large expressions in real time.

The indicator symbol

I prefer to use the blackboard bold symbol 𝟙 for indicators. Unfortunately, this symbol is defined in the bbold package, which changes the AMS blackboard bold font used for the probability symbol $\P$, and by default produces a blurry font. The blurriness can be avoided by installing the bbold-type1 package – once this is done, the font can be loaded by writing

% requires packages bbold and bbold-type1 to avoid bitmap font
\DeclareSymbolFont{bbold}{U}{bbold}{m}{n}
\DeclareSymbolFontAlphabet{\mathbbold}{bbold}

which defines the command \mathbbold. From here, one can use \newcommand{\1}{\mathbbold{1}} to define \1 to be the indicator symbol.

A less-verbose enumerate and itemize

When writing notes, I often prefer to use enumerated and bullet-point lists in order to make the document easier to read. In LaTeX, using \begin{enumerate}, \item, and \end{enumerate} is rather verbose. A more concise and more readable syntax can be obtained by writing

\1 Here's my first item.
\2 The second item!
\1* A bullet point.
\2* Another bullet point!
\0*
\3 A third item.
\0

to produce

  1. Here’s my first item.
  2. The second item!
    • A bullet point.
    • Another bullet point!
  3. A third item.

where \0* closes the itemize, \0 closes the enumerate. As before \1 is defined separately for text and math mode. This syntax supports custom labels and more-or-less arbitrary nesting. It is compatible with the enumerate package, and is largely unproblematic: the only TeX package I am aware of which defines \1 or \2 is xymatrix, which appears to seldom use them. The code for the simplified enumerate and itemize syntax is given below.

\providecommand{\1}{} % xymatrix workaround
\renewcommand{\1}{\relax\ifmmode\mathbbold{1}\else\expandafter\@onenonmath\fi} % indicator function and enumerate/itemize shorthand
\newcommand{\@onenonmath}{\@ifstar\@onestarred\@onenonstarred}
\newcommand{\@onestarred}{\begin{itemize}\item} % itemize shorthand
\newcommand{\@onenonstarred}[1][]{\ifx\\#1\\\begin{enumerate}\item\else\begin{enumerate}[#1]\item\fi} % enumerate with possible iteration choice
\providecommand{\2}{} % xymatrix workaround
\renewcommand{\2}{\@ifstar\item\item} % enumerate/itemize shorthand
\newcommand{\3}{\@ifstar\item\item} % enumerate/itemize shorthand
\newcommand{\4}{\@ifstar\item\item} % enumerate/itemize shorthand
\newcommand{\5}{\@ifstar\item\item} % enumerate/itemize shorthand
\newcommand{\6}{\@ifstar\item\item} % enumerate/itemize shorthand
\newcommand{\7}{\@ifstar\item\item} % enumerate/itemize shorthand
\newcommand{\8}{\@ifstar\item\item} % enumerate/itemize shorthand
\newcommand{\9}{\@ifstar\item\item} % enumerate/itemize shorthand
\newcommand{\0}{\@ifstar\@zerostarred\@zerononstarred} % close enumerate/itemize
\newcommand{\@zerostarred}{\end{itemize}} % close itemize
\newcommand{\@zerononstarred}{\end{enumerate}} % close enumerate

Math-mode inline text with correct spacing

Sometimes, it’s useful to write a snippet of text inside a mathematical expression, for instance in

[ f(x) = \begin{cases} 1 \t{if} x=0 \\ 0 \t{otherwise.} \end{cases} ]

The LaTeX command \text does not by default take spacing into account, so I prefer to redefine \t in math mode in a way that produces spacing. This allows me to write

f(x) = \begin{cases}
1 \t{if} x=0 \\
0 \t{otherwise.}
\end{cases}

to produce the above. LaTeX has a number of commands that automatically determine spacing: the one that I find to work best for inline text is \mathrel. The full definition of \t in the above is given below.

\let\textt\t % redefinition: tie accent
\renewcommand{\t}{\relax\ifmmode\expandafter\mathrel\expandafter\text\else\expandafter\textt\fi} % text with spacing

Concluding remarks

Using customs TeX macros helps make the source more readable, which makes it easier to typeset notes in real time. Beyond the macros listed here, I define a number of commands for readability: \m for upface bold symbols typically used for matrices, i.e. $\m{x}$, \N for $\N$, \R for $\R$, and many others. I also define \< and \> to be \begin{align} and \end{align}, define \? to be \begin{gather} and \end{gather}, and redefine \[ and \] to automatically number equations.

For collaboratively-written documents, custom macros can improve source readability, but will generally be unfamiliar to others. In my experience, the benefits of having a more concise and easier-to-read source tend to be worth the costs, because it’s usually straightforward to figure out what was meant.

I hope these tricks help make TeX source easier to read, and make it slightly simpler for anyone attending a mathematical course to take their notes directly in LaTeX.