Skip to content
Topos Uranos
English

Compiling and fixing errors

Summary

This lesson teaches how to compile with confidence and how to fix what goes wrong. It explains that a compilation proceeds in passes, why cross-references and the table of contents need a second one, and how latexmk repeats the passes on its own, in Texmaker and in the terminal. It teaches how to read the log: where it is, how to read an error with its exclamation-mark line, its line number and its context split in two, and what distinguishes an error from a warning and from an overfull box message. It goes through the most frequent errors with their actual messages, the interaction modes of the engine and a debugging strategy: read the first error first, split the source in halves, reduce the problem to a minimal example, clean the auxiliary files and search for the text of the message. It ends with the warnings that deserve attention.

Learning objectives

  1. Explain why a document with cross-references or a table of contents needs more than one pass, and compile it with latexmk.
  2. Read an error in the log and identify its message, the line where the engine detected it and the exact point within that line.
  3. Recognize the most frequent errors by their message and relate each one to its likely causes.
  4. Locate the real cause of an error when it is not on the line reported, by reading the first error first and splitting the source in halves.
  5. Distinguish the warnings that call for a correction from those that can be ignored.

What a compilation does

The engine reads the source only once, from beginning to end, and typesets each page as it goes. That single reading has a consequence: when a reference to Section 5 appears on the second page, or when the table of contents on the first page must list sections that have not yet been read, the engine cannot yet know which number or which page they correspond to. The LaTeX solution is to work in passes. In each pass, it records in the .aux file the number and page of every label (the ones set with \label), and in the .toc file the section titles; in the next pass, it reads those files at the start and uses what was recorded. It follows that, in the first compilation, the references appear as two question marks and the table of contents comes out empty, and that compiling once more is enough to fill them in. If a change shifts the numbers, a third pass may be needed; the bibliography, as its unit will show, adds one more program, Biber, between passes.

Counting passes by hand is tedious and error-prone. That is what latexmk is for, a program that comes with the distributions: it runs the engine, examines the log and the auxiliary files, and repeats the passes, or calls Biber, until nothing changes. Its option -lualatex tells it to use LuaLaTeX, and its option -c deletes the auxiliary files while keeping the PDF.

Examplelatexmk in the terminal

The first command compiles thesis.tex with LuaLaTeX as many times as necessary; the second cleans up the auxiliary files.

Terminal
$ latexmk -lualatex thesis.tex$ latexmk -c thesis.tex

In Texmaker, one of the predefined Quick Build sequences uses latexmk (LatexMk + View PDF); in the list of commands of the configuration dialog, the latexmk command is changed to latexmk -lualatex -synctex=1 -interaction=nonstopmode %.tex, so that it uses LuaLaTeX and keeps synchronization with the PDF.