Wednesday, May 08, 2013

Ten Common LaTeX Errors

I am the editor for an electronic journal, the Journal of Integer Sequences. We only accept submissions in LaTeX format, which are then converted to ps, dvi, and pdf files for publication.

While most authors do a reasonable job preparing their papers in LaTeX, a reasonable fraction do not. After more than ten years of editing this journal, I've noted the following ten common LaTeX errors that authors make again and again.

1. Failure to use built-in LaTeX commands when they are available. Don't reinvent the wheel. There are lots of useful constructs available in the packages amsmath, amssymb, amsfonts, and amsthm, so your LaTeX file should include the following line in the preamble:

\usepackage{amsmath,amssymb,amsfonts,amsthm}

For example, theorems should be done using \begin{theorem} ... \end{theorem}. Remarks should be done with \begin{remark} ... \end{remark}, and conjectures should be done with \begin{conjecture} ... \end{conjecture}. The easiest way to do this is to put the following text in the preamble:

And of course, don't forget to use \begin{proof} ... \end{proof} for proofs.

2. Failure to follow basic conventions of mathematical exposition. For example, a common convention is that one-letter functions should be given in the italic font (which in LaTeX can be achieved with, say
$f(x) = y$), while multi-letter functions are typically given in the roman font (and can be achieved, for example, with \sin, \cos, \tan, \log, \ln, \exp, \min, \max, etc.). But what to do when faced with a function like "lcm" for which there is no built-in definition? Then you just say

\DeclareMathOperator{\lcm}{lcm}

in the preamble, allowing you to write, for example, $\lcm(x,y) = z$ and have it appear correctly.

3. Failure to use "mod" correctly. If it is used as an equivalence relation, then you can write (for example)

$$ x \equiv y \pmod z $$

which displays correctly for centered equations. In-line, however, you should write
$x \equiv y$ (mod $z$) to get the proper spacing. Sometimes, however, you want to do this all in-line without moving in and out of math mode. Then you need a definition in the preamble like

\def\modd#1 #2{#1\ ({\rm mod}\ #2)}

which can be used like $x \equiv \modd{y} {z}$. I find it very useful and wish it were built-in in LaTeX.

If you use mod as a function, then the syntax is different. Write $x = y \bmod z$ in this case.

Note the backslash-space after the m and p; you need those because of the TeX convention that lower-case letters followed by a period are interpreted as the end of a sentence, which is conventionally followed by a double-space. If this is not the case, then you need to escape the space with the backslash.

5. Incorrect case statements. Sometimes writers use an array environment to make these, instead of the built-in case environment, which can be used as follows:

Note the use of the \text{...} command, which makes sure the enclosed material is in the default (roman) font.

6. Failure to use labels. Mathematicians are intimately familiar with the concept of variables; yet it is really amazing that they often do not use them when preparing LaTeX documents, preferring to "hard-wire" references to theorems, lemmas, and so forth. Everything in a document that is referred to later on should get a label: theorems, lemmas, corollaries, remarks, tables, figures, sections, and so forth. Doing so makes rearranging or inserting new results trivial.

7. Using the wrong quote marks. TeX distinguishes between left-quotes, which must be written ``, and right-quotes, which can be written either " or ''. Using the wrong left-quotes looks ugly.

8. Using the wrong kinds of dots. Never ever write "$x,...,y$". Instead write $x, \ldots, y $. Similarly, write $x y \cdots z$ for a product. The rule for distinguishing when to use \ldots and when to use \cdots is pretty easy: if the syntax to the left and right of the dots has a center of mass at the bottom of the line, use \ldots. If the syntax to the left and right of the dots has a center of mass at the center of the line, use \cdots.

9. Page ranges. Page ranges should be written with --, not -. So write 234--456, not 234-456.

10. Obsessive tweaking of the spacing. If your file contains lots of invocations of commands like \\, \noindent, \newpage, \bigskip, \medskip, \smallskip, \newline, \pagebreak, \linebreak, you're probably doing something wrong. LaTeX's own choice of spacing is usually pretty good, and the need to tweak it should be rather rare. In particular, I've had authors submit papers with \\ at the end of every paragraph!

And, for lagniappe, here's number 11:

11. Wrong angle brackets.. Use \langle and \rangle for left and right angle brackets, for example, in group presentations. Don't use < and >, which result in ugly output.

If you have other pet peeves about lousy LaTeX usage, feel free to add them here.

10 comments:

Thanks for the post! These are a lot of my LaTeX pet peeves too. Raw references without using \ref are the worst!

Only thing I have to add is that if you're inserting an aside in a sentence—like this one—use a proper em-dash('---' in LaTeX), or an en-dash with surrounding spaces (' -- '). Not a mechanic often used in academic writing, but if you're going to use it, at least do it correctly!

My company composes and produces technical books and journals for publishers, including the Journal of Differential Geometry. All eleven of your common errors are spot on. The most time-consuming error is number 1. It's not only a failure to use built-in LaTeX commands, but a failure to use the commands and environments provided by whichever class is being used to format the papers. In particular, authors just love making up their own enunciation environments (theorems, conjectures, proofs, etc.).

Probably the second most time-consuming issue is fonts. I know that mathematicians love to use lots of fonts and I realize why this is necessary. But let's face it, two styles of calligraphic letters is crazy. No one can tell them apart. Blackboard bold was invented to write bold on the blackboard. Okay, so now it's a separate font. But do we really need bold blackboard bold? Watch out when using both calligraphic and fraktur. And please, don't use a font that your graduate student invented last Tuesday, because it's not available on the Net and it's probably broken anyway.

Also, don't use pstricks and other PostScript hacking packages. They barely work with your TeX system and probably not with the compositor's. And don't get me started about \psfrag. We have to redraw all those figures in Illustrator.

One important suggestion if you are writing a book in LaTeX: Use a root file with \include commands to include each chapter, each front and backmatter section, and each part. Process the book as a coherent whole. Many authors simply process each chapter as a separate LaTeX book. Nothing prevents duplicate cross-reference labels, duplicate citation labels, or duplicate commands. We just completed a book where the author's personal command definitions were duplicated in each chapter and then changed a little bit here and there. Sorting it out was a true nightmare.

Here is my most important rule of thumb. In particular, it addresses your point 10:

The final book is not going to look like your manuscript. Don't assume that it will.

I hope no one will mind if I post additional suggestions as they occur to me.

By default, LaTeX uses "non-French spacing," which produces extra space after certain punctuation characters such as period and question mark. No publisher has typeset a book with such extra space in three decades. It causes trouble with periods that are not sentence-ending punctuation. Jeff had to compensate for this problem in point 4:

\cite[Thm.\ 6, p.\ 10]{ref1}.

Do yourself a favor and switch to French spacing using this command in the preamble:

\frenchspacing

If you have figures or tables in your paper, do not force them to appear at specific points in the text using the [h] option on the \begin{figure} command. Instead, assign figure numbers and refer to the figures by number from the text. The problem with specific placement is that the figure might fall toward the bottom of a page but not fit on the page. Then the poor compositor (layout person) has to assign a figure number anyway. Or leave a disgusting loose page in the paper and appear to be incompetent.

When a proof ends in math environment (like align or equation) instead of inline, the box appears at the end of an empty line. This can be fixed with the \qedhere command placed at the end of the math environment.

Another common problem with books and especially journal articles occurs when the author changes the text measure (line width) so that it is wider than the measure in the final book/article. This means that math displays and program code examples are sometimes wider than the final text measure and the compositor has to break the lines to make them narrower. It's work for the compositor and sometimes results in breaks that the author does not like.

If you do not know the text measure of the final book/article, then assume 30 picas (= 5 inches). Most books and journals are that wide, or at least 28 picas.

Note that LaTeX's default text measure is an absurd 36 picas. Change that to 30 picas.

In the proper spirit of LaTeX \modd should be defined thus:\newcommand\modd[2]{(#1\,\,\mathrm{mod}\,\,#2)}(\rm deprecated and \,\, is what Knuth used in \pmod) In point 4 I would use Thm.~6, p.~10 to prohibit linebreaks.