Compiling Latex Documents: Why Multiple Passes Are Necessary

The Core Reasons Behind Multiple Passes

LaTeX, the high-quality typesetting system commonly used for academic and scientific documents, requires multiple compilation passes to fully process a document. This stems from key aspects of LaTeX's design:

Text Expansion During Compilation

When LaTeX compiles a document, it expands abbreviations, macros, environments, and other shorthand inserted by the user into full-formed content. For example, the user may define a shortcut such as \myapp to expand to "My Important Application". On the first pass, LaTeX encounters \myapp, but cannot yet expand it, as the definition may appear later in the document. So it saves \myapp to process on the next pass.

Cross-Referencing Between Passes

LaTeX includes referencing capabilities for numbered elements like tables, figures, sections, equations, and more. On the first compilation pass, these numbers are unknown, so LaTeX saves placeholders. On subsequent passes, the final numbers are inserted. For instance, a reference to "Figure 1" will resolve properly only once Figure 1's location is fixed.

Updating Table of Contents and Bibliographies

LaTeX automatically builds tables of contents and bibliographies by scanning document contents and pulling in elements like section headings or citation keys. However, on the first pass, the final page numbers are not yet fixed. So multiple passes allow the ToC and bibliography to resolve properly.

Seeing Multi-Pass Compilation in Action

Sample Document Requiring 3 Passes


Hello world, this is \myapp.

See Figure \ref{fig:diagram}.

\caption{Important diagram}


In this short example, on the first pass \myapp and \ref{fig:diagram} are unresolved. On the second pass, the figure number is fixed. And on the third pass, \myapp is expanded to the full phrase.

Interpreting LaTeX’s Log Messages

LaTeX logs detailed messages during each compilation pass. For example:

Pass 1:
LaTeX Warning: Reference `fig:diagram' on page 1 undefined

LaTeX Warning: Citation `myapp' undefined on page 1 

Pass 2:  
LaTeX Warning: Reference `fig:diagram' on page 1 undefined

[fig:diagram] => Figure 1   

Pass 3:
My Important Application

[1] [2] [3]

We can see LaTeX record unresolved references after Pass 1. On Pass 2, the figure number is set. And on Pass 3, \myapp expands properly.

When More Passes Are Needed

Some LaTeX documents require more than 3 passes to fully resolve. This often depends on:

Documents with Complex Packages

Specialized LaTeX packages like BibLaTeX for advanced bibliographies often demand additional compilation cycles. For example, BibLaTeX may require up to 5 passes to accurately display citation cross-references, pull in external bibliographic data sources, and build citation indexes.

Tuning the Number of Passes

When troubleshooting compilation issues, temporarily increasing the number of passes with a command line flag can help LaTeX resolve all references. For example:

pdflatex -halt-on-error -draftmode -jobname=test "\maxdeadcycles=9 \input{test}"

Here 9 maximum dead cycles forces LaTeX to make up to 9 passes before it aborts from any unresolved references.

Troubleshooting Issues with Compilation Passes

Fixing Unresolved References

If critical issues remain after multiple passes, common solutions include:

  • Checking reference syntax is valid
  • Moving figure/table definitions earlier before references
  • Verifying custom macro definitions visible to reference location
  • Adding more passes to help LaTeX resolve reference

Handling Large Documents

For longer documents, reducing passes can improve compilation speed. This requires manually resolving references. Strategies include:

  • Setting draft mode to temporarily disable complex elements like figures
  • Splitting into multiple tex files joined by \include
  • Specifying page ranges for partial compilation runs

Moving Beyond Multiple Passes

While mature and reliable, traditional LaTeX compilation often relies on multiple passes. Emerging alternatives aim to resolve this.

Emerging Single-Pass Technologies

New LaTeX engines like LuaLaTeX can resolve references in a single pass using modern programming techniques. However, full single-pass fidelity remains a challenge. Other tools like LaTeX-online-builder, Overleaf, and cloud services hide multi-pass runs behind easy web interfaces.

The Tradeoffs vs Traditional LaTeX

Despite moves toward single-pass, traditional multi-pass LaTeX still powers most production typesetting today. Reasons include:

  • Built up decades of reliable output routines
  • Supports enormous array of packages & custom macros
  • Integrates well into automated workflows
  • Lets users directly control compilation

So while promising options emerge, expect multi-pass LaTeX compilation to remain the gold standard for academic publishing.

Leave a Reply

Your email address will not be published. Required fields are marked *