Skip to content
Topos Uranos
English

Cross-references

Summary

This lesson teaches how to refer from one place in a document to another without ever typing a number by hand. It explains what a label records, namely the number of the last numbered element that precedes it, and from this it deduces where the label must go in a section, a figure, an equation and a list item, and why a label written before the caption of a figure refers to the section; it proposes a convention for naming labels; it shows why references need two passes and what happens in the first pass after a change; it presents hyperref, which turns references into links and sections into PDF bookmarks, with its options and the document's metadata; it presents cleveref, which writes the name of the referenced element by itself, with its English forms and the way to adjust them; it briefly presents nameref; and it ends with what is best avoided.

Learning objectives

  1. Explain which number a label records and, on that basis, place it correctly in sections, figures, equations and lists, predicting what a misplaced reference prints.
  2. Name labels with a convention that tells the writer what each one designates.
  3. Explain why references need two passes, interpret their warnings and predict what a reference shows after a single compilation.
  4. Load hyperref and cleveref in the proper order, choose the appearance of links and set the PDF metadata.
  5. Refer with \cref, \Cref, \pageref and \nameref so that the text reads correctly, with the right name, capitalization and form for what is referenced.

The problem of numbers typed by hand

An academic text constantly refers to itself: “as shown in Section 2”, “the data in Figure 3”, “equation (4)”, “see page 12”. If those numbers are typed by hand, every change to the document puts them at risk: a new section at the beginning shifts the numbering of all the following ones, a deleted figure renumbers the others, a page that grows moves the rest. The author must then hunt down every reference and correct it, and forgetting a single one is enough for the text to point to the wrong place without anything giving warning.

LaTeX's automatic numbering, which already numbers sections, notes and lists, also solves this problem. The place one wants to refer to is marked with a label, a name chosen by the author, and each reference writes that name instead of the number. The engine takes care of finding out the number and writing it; if the number changes, it changes everywhere at once.