Parker Glynn-Adey | LaTeX Best Practices

This is an idiosyncratic list of what I consider “best practices” when writing $\LaTeX{}$ documents. I primarily write documents for teaching, so the focus of this advice is generally towards teaching materials. Elsewhere, I have a list of Common $\LaTeX{}$ Errors.

Write on Paper First

I highly recommend hand-writing a first draft of any document which you intend to typeset. Preferably, use pencil and paper. You will definitely need to erase and re-write things. I recommend this practice because the work of typesetting things in $\LaTeX{}$ is sufficiently complicated that you don’t want to mix it with the act of composition. Separate composition and typesetting as far as possible.

Use Lots of White Space And Indentation

$\LaTeX{}$ doesn’t care how much white space or indentation you use, but it can make things much more readable. Here is a nice algebra fact from highschool.

There are lots of ways to typeset this equation. Looking at it on paper, your natural instinct is to code this in $\LaTeX{}$ as follows.

However, this approach makes it hard to modify the equation. Maybe you notice a weird typo in the middle and want to modify it. Or you want to add brackets. You wind up having to count how many equal signs deep you are to determine which equation to edit. It’s a mess. Now, look at the following snippet of $\LaTeX{}$ code.

Every equation is on its own line of code. You can see each part clearly. If you want to modify a whole equation, you can (usually) just double click on the line to select it. Even though the typeset version doesn’t feature these line breaks¹, it helps to have them on the code level. Of course, you should put simple display style equations on their own line. \[ 1 + 1 = 2 \] Should appear in your code as:

Pad it with lots of space on either side, so that it stand out. My colleague Ivan Khatchatourian like to put a tonne of spacing between section and page breaks, so that they visually stand out when viewing the code.

Another feature, not to be overlooked, is the ability to add indentation. Nesting everything with lots of levels of indentation can make your $\LaTeX{}$ more readable and maintainable. Here is another example.

This is a perfectly fine $2 \times 2$ matrix. This sort of things crops up all the time in linear algebra. $\LaTeX{}$ won’t care if you code it in the following terrifying manner. (Please, never write code like this.)

The computer will happily typeset anything that’s syntactically valid. But, that example is a hard to read and maintain. Compare it with the following.

With a lot of levels of indentation, you can see exactly what is going on. It is clear what the entries in the matrix are. It is clear what kinds of brackets you are using. Everything is much clearer with lots of indentation.

Use Lots of Comments

Leaving comments for yourself is underrated. It is incredibly helpful for keeping track of how the document came to be. For example, you can leave a link when including a computation from WolframAlpha. You might want to have students factor $x^2 - 5x + 6$. In your write-up of the solutions, you could code:

Or, if you’re including a graph from Desmos, you can include link to the original graph. This lets you go back and fiddle with the original graph if you need to modify the lesson plan later.

A little bit of copy and pasting during the typesetting phase can save a lot of work re-creating graphs later.

You can, of course, use comment to leave little notes for yourself. I like to use tk to let myself know where these notes are, as it is very rare² in English and thus easy to search for. I’ve surprised myself by writing whole sections of lesson plans as comments. It is a happy day when you find such comments, and save yourself a tonne of work.

Develop Your Own Style

It is entirely possible to use $\LaTeX{}$ as is without customization. There are some things that you won’t be able to do, but the documents you write will be perfectly reasonable. However, you can get a lot of functionality by defining a few macros and bundling them in to a style file.

Don’t be afraid of defining new commands. If you find yourself writing \mathbf{i} ten times then it would be worth adding: \newcommand{\ii}{\mathbf{i}} to your style file and using \ii from then on³.

If I’m making a bunch of documents with a similar layout, I will even “abstract out” certain key pieces of information in to macros. For example, in a series of worksheets, I would put the following in my preamble:

This centralizes all the information about the worksheet, and makes the layout less susceptible to copy and paste errors.

This command ignores anything that you put it in to. The code \ignore{typo} will leave your final document typo free!

Acknowledgements

Thanks to Ivan Khatchatourian for reading a draft of this note and suggesting the wide spacing around section breaks and the populatization of \ignore{}.

This idea of adding line breaks on the code side actually runs much deeper. People like adding semantic line breaks to help make mark-up more readable. Kernighan wrote about this idea in 1974 in UNIX for Beginners. Buckminster Fuller wrote this way in the 1930s. ↩︎
Sasha Chapin pointed out that ‘tk’ doesn’t even appear in the word tchotchke, which is about the only place I would think to look for it! Someone else, I regret that I forget who, pointed out that it occurs in Atkin which would come up fairly often if you write about health or dieting. My colleague Tom Kielstra was bewildered to find his initials everywhere in my code; he thought all the tk’s were personal to-dos for him. ↩︎
My colleague Tyler Holden disagrees with me about this particular choice of $\LaTeX{}$-nical convention. He thinks that one should write \bf i instead of \ii. This is the sort of thing that we squabble about. We’re gigantic nerds. ↩︎

LaTeX Best Practices

Write on Paper First

Use Lots of White Space And Indentation

Use Lots of Comments

Develop Your Own Style

Acknowledgements

Meta

Navigation Menu