Querverweise

LaTeX liest ein Dokument genau einmal, von oben nach unten. Steht also auf Seite 2 ein \ref{fig:leaf} und die genannte Abbildung auf Seite 40, dann existiert diese Nummer noch gar nicht – und die gesamte Querverweis-Maschinerie von LaTeX, \label und \ref, löst genau dieses eine Problem: der Verweis kommt vor seinem Ziel. Die Antwort ist erstaunlich schlicht: Im ersten Lauf werden die Nummern in eine .aux-Datei geschrieben, im zweiten wieder eingelesen. Diese Seite verfolgt den Gedanken durch die zwei Kompilierläufe, das fette ?? dazwischen, den Grund, warum ein vor seiner \caption gesetztes \label die falsche Nummer meldet, und die Verbesserungen durch cleveref und varioref.

\label und \ref: beim Namen nennen, nie bei der Nummer

Querverweise beruhen auf zwei Befehlen. \label{key} bindet den Namen key an den Wert des zuletzt erhöhten Zählers an dieser Stelle und gibt selbst nichts aus. \ref{key} fügt nur die Nummer ein, für die dieser Name steht. Gezählt wird von LaTeX, es muss also keine einzige Ziffer getippt werden. Der key ist eine beliebige Zeichenkette, und da das Label am Objekt hängt, lassen sich Abbildungen umsortieren oder ganze Abschnitte in ein anderes Kapitel verschieben – jeder Verweis zieht mit. Ein Dokument mit handgeschriebenem „Abbildung 3“ zerfällt nach einer solchen Verschiebung; dieses nicht.

\section{Introduction}
\label{sec:intro}

\begin{equation}
  \label{eq:euler}
  e^{i\pi} + 1 = 0
\end{equation}

\begin{figure}
  \centering
  \includegraphics{leaf}
  \caption{Vein structure of a leaf}
  \label{fig:leaf}          % after \caption, always
\end{figure}

As shown in Section~\ref{sec:intro}, equation~\eqref{eq:euler}
and Figure~\ref{fig:leaf} agree on page~\pageref{fig:leaf}.

An einem Punkt stolpern fast alle: \ref liefert nur die Nummer. Wörter wie „Abbildung“, „Gleichung“ oder „Abschnitt“ kommen nicht mit; sie werden selbst geschrieben und mit einem geschützten Leerzeichen ~ statt eines gewöhnlichen Leerzeichens an die Nummer gebunden. Bei Figure \ref{fig:leaf} kann eine Zeile nach „Figure“ enden und die „3“ allein auf der nächsten stehen lassen; bei Figure~\ref{fig:leaf} ist an dieser Stelle kein Umbruch möglich. Genau diese kleine Handarbeit – die Art des Ziels zu benennen – nehmen \cref und \autoref weiter unten ab.

Warum zweimal kompiliert wird: die .aux-Datei und das ??

Querverweise werden nicht in einem Lauf stabil. Jedes Mal, wenn LaTeX auf ein \label trifft, schreibt es Nummer und Seite in eine .aux-Datei mit demselben Basisnamen wie das Dokument – und \ref kann nur lesen, was der vorige Lauf dort abgelegt hat. Im ersten Durchgang existieren die Zielwerte also nirgends: Die Ausgabe zeigt ein fettes ??, und im Log stehen zwei Warnungen nebeneinander. Beide lohnen sich zu kennen, denn genau sie tippt man später in ein Suchfeld.

LaTeX Warning: Reference `fig:leaf' on page 1 undefined on input line 17.
LaTeX Warning: There were undefined references.
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.

Dieses ?? ist kein Unfall, sondern eine im LaTeX-Kern festgeschriebene Vorgabe. In latex.ltx setzt das Makro \@setref bei einem undefinierten Label \reset@font\bfseries ?? und gibt in der unmittelbar folgenden Zeile die Warnung „Reference … undefined“ aus. Der Fettdruck ist Absicht: Fett verschwimmt nicht mit der umgebenden Schrift, die Lücke ist also nicht zu übersehen. Ein weiterer Lauf holt die Werte aus .aux zurück und macht aus ?? echte Nummern. Verschiebt sich die Nummerierung und ändert sich ein Verweiswert, kehrt die Warnung zurück – richtig ist daher, bis zu ihrem Verschwinden zu wiederholen; zwei Läufe reichen meist. latexmk dreht diese Schleife automatisch, und Overleaf kompiliert im Hintergrund mehrfach, weshalb ?? dort selten zu sehen ist.

Die .aux-Datei ist reiner Text und lässt sich einfach öffnen und lesen. Jedes Label steuert eine \newlabel-Zeile bei, und diese Zeile trägt fünf Felder: die Nummer, die Seite, den Text der Überschrift, den Ankernamen für den Link und ein weiteres in Reserve. Wegen des dritten Feldes kann \nameref den Titel selbst einsetzen; wegen des vierten weiß hyperref, wohin ein Klick führen soll. Verhält sich ein Verweis seltsam und die Ursache ist unklar, führt der kürzeste Weg über die .aux-Datei: existiert die Zeile? Fehlt sie ganz, wurde das \label nie erfasst; sieht der Wert falsch aus, liegt es an seiner Position – das Thema des nächsten Abschnitts.

% one line per label: {number}{page}{title}{anchor}{spare}
\newlabel{sec:intro}{{1}{1}{Introduction}{section.1}{}}
\newlabel{fig:leaf}{{2}{3}{Vein structure of a leaf}{figure.2}{}}

Wenn \ref die falsche Nummer liefert: \label gehört hinter \caption

Ein Abbildungsverweis, der nicht zur Abbildung passt – die Ursache ist fast ausnahmslos die Position des \label. Ein \label greift die Abbildungsnummer nicht deshalb ab, weil es zufällig innerhalb einer figure-Umgebung steht. Es greift den Wert des unmittelbar zuvor erhöhten Zählers ab, und die figure-Umgebung erhöht überhaupt keinen Zähler. Erhöht wird er von \caption. Ein \label direkt nach \begin{figure} erfasst daher nicht die Abbildungsnummer, sondern den zuletzt erhöhten Zähler – meist die Nummer des Abschnitts oder Kapitels, in dem man gerade steckt.

Ausprobieren überzeugt schneller als jede Erklärung. Eine Abbildung in den siebten Abschnitt setzen, je ein Label vor und nach die \caption schreiben und mit pdfLaTeX aus TeX Live 2024 kompilieren: Die .aux-Datei verzeichnet 7 für das vorangestellte Label – die Abschnittsnummer – und 1 für das nachgestellte, die Abbildungsnummer. Dabei erscheint keine einzige Warnung. Beides sind plausible Nummern, LaTeX kann also gar nicht entscheiden, dass eine davon falsch ist. Gerade weil kein Fehler den Lauf anhält, rutscht dieser Fehlgriff durch die Korrektur bis in den Druck.

\section{A}\section{B}\section{C}
\section{D}\section{E}\section{F}\section{G}   % we are now in section 7

\begin{figure}
  \label{fig:before}      % WRONG: no counter stepped yet -> picks up 7
  \centering\rule{2cm}{1cm}
  \caption{A leaf}        % <- this is what steps the figure counter
  \label{fig:after}       % RIGHT: picks up 1
\end{figure}

% .aux after two runs:
%   \newlabel{fig:before}{{7}{1}{}{}{}}
%   \newlabel{fig:after}{{1}{1}{}{}{}}

Die Regel lässt sich in einen Satz fassen: \label unmittelbar hinter den Befehl setzen, der die Nummer erzeugt. Bei Abbildungen und Tabellen also hinter \caption (auch innerhalb des Arguments ist in Ordnung), bei Überschriften direkt hinter \section und Verwandte, bei nummerierten Gleichungen innerhalb der equation-Umgebung, bei Listenpunkten hinter \item. Trägt eine Abbildung mehrere Bildunterschriften und nur ein Label, hängt die Nummer davon ab, hinter welche \caption es geraten ist. Und der einzige triftige Grund, ein \label vor eine \caption zu schreiben, ist schlicht: es gibt gar keine \caption.

\pageref und die Benennung der Labels

Soll statt der Nummer die Seite genannt werden, dient \pageref{key}. Der Befehl nimmt dasselbe Label und liefert die Nummer der Seite, auf der dieses \label gesetzt wurde, sodass sich beides zusammen zitieren lässt: Figure~\ref{fig:leaf} on page~\pageref{fig:leaf}. Strukturell kommt damit schlicht das zweite Feld der \newlabel-Zeile zurück. Seinen Nutzen entfaltet es in Dokumenten, in denen wirklich geblättert wird – lange Berichte, gebundene Arbeiten –, weniger auf dem Bildschirm.

Ein key darf beliebig heißen, verbreitet ist jedoch ein Präfix für die Art des Ziels: sec:, fig:, tab:, eq:, ch:, lst:. Daraus folgt zweierlei. Erstens erspart eine inhaltliche Benennung wie fig:leaf beim Umsortieren jedes Umbenennen, während ein Name wie fig:3 in dem Moment zur Lüge wird, in dem eine zweite Abbildung dazukommt. Zweitens verrät schon der Anblick von \ref{fig:...} die Art des Ziels, was die eigene Quelle mechanisch lesbar macht, sobald das Dokument später auf \cref umgestellt wird.

\eqref: Gleichungsnummern samt Klammern (amsmath)

Gleichungsnummern werden üblicherweise in Klammern geschrieben – „nach Gleichung (3)“ –, ein schlichtes \ref liefert aber nur 3. Mit geladenem amsmath ergänzt \eqref{key} die Klammern und liefert (3). Der eigentliche Gewinn liegt nicht bei den Tastenanschlägen, sondern beim Schriftschnitt: Die von \eqref erzeugten Klammern stehen immer aufrecht, gleich welche Schrift sie umgibt. In einer Satzumgebung mit kursivem Grundtext bleiben sie also senkrecht. Wer (\ref{eq:euler}) von Hand tippt, sieht genau diese Klammern mitkippen.

cleveref: \cref und \Cref besorgen Wort und Numerus

cleveref hebt das Verweisen eine Stufe an. \cref{key} stellt das Wort für die Art des Ziels voran (standardmäßig abgekürzt – „fig. 1“ – oder „figure 1“ mit der Option noabbrev), und \Cref{key} schreibt es groß, sodass der Verweis einen Satz eröffnen kann. Seine eigentliche Stärke sind Listen und Bereiche: Labels kommasepariert ohne Leerzeichen übergeben – \cref{fig:a,fig:b,fig:c} – und die Nummern werden sortiert und verbunden, das Wort dabei in den Plural gesetzt, etwa zu „figs. 1, 2 and 4“. Noch besser: Eine zusammenhängende Folge klappt sich selbsttätig zu einem Bereich zusammen, jene drei ergeben also „figs. 1 to 3“. \crefrange{first}{last} liefert dieselbe Verdichtung, wobei nur die beiden Endpunkte genannt werden.

Das vorangestellte Wort wird mit \crefname{type}{Singular}{Plural} neu definiert (\Crefname für die großgeschriebene Form). Auf demselben Weg erfolgt die Lokalisierung, etwa \crefname{figure}{Abbildung}{Abbildungen}. Soll im ganzen Dokument großgeschrieben werden, lädt man das Paket mit der Option capitalise. Wo umgekehrt nur die Nummer ohne jedes Wort gebraucht wird – in Klammern, in einer Tabellenzelle –, liefert \labelcref{key} genau das, was auch ein schlichtes \ref liefern würde.

Für die Ladereihenfolge gilt eine unbedingte Regel: cleveref kommt nach hyperref, varioref und amsmath – auf alle drei wird geprüft. cleveref baut seine Befehle auf dem auf, was hyperref definiert hat; umgekehrt kann es schlicht nicht funktionieren. Erfreulicherweise scheitert das nicht stillschweigend – das mit TeX Live 2024 ausgelieferte cleveref.sty prüft die Reihenfolge bei \begin{document} und bricht mit der folgenden Meldung ab. Anders liegt der Fall bei zusätzlich geladenem varioref: Das cleveref-Handbuch schreibt die Reihenfolge varioref → hyperref → cleveref vor und warnt, dass Verweise bei falscher Reihenfolge auf etwas völlig anderes zeigen können, ohne Warnung in Ausgabe oder Log.

\usepackage{varioref}
\usepackage{hyperref}
\usepackage{cleveref}   % always last of the three

% If cleveref is loaded before hyperref, TeX Live 2024 stops with:
%   ! Package cleveref Error: cleveref must be loaded after hyperref!.
%   Package load order is wrong: load cleveref *after* hyperref.

\cref{fig:a,fig:b,fig:c}       % figs. 1 to 3   (consecutive: compressed)
\cref{eq:euler,eq:max}         % eqs. (1) and (4)
\Cref{sec:intro} explains ...  % Section 1 explains ...
\labelcref{fig:a}              % 1   (number only, like \ref)

% with \usepackage[noabbrev]{cleveref} the same lines give
%   figures 1 to 3 / equations (1) and (4)

varioref: „auf der nächsten Seite“ statt einer nackten Seitenzahl

In einem gebundenen Dokument liest sich „Abbildung 3 auf der nächsten Seite“ besser als das mechanische „Abbildung 3 auf Seite 12“ – und „auf der gegenüberliegenden Seite“ noch besser, wenn beide auf einer Doppelseite stehen. \vref{key} aus varioref gibt dieselbe Nummer aus wie \ref und prüft dann die Seitenlage von Verweis und Ziel zueinander, um die passende Formulierung zu ergänzen. Liegen beide auf einer Seite, wird nichts ergänzt. Ist nur die Seitenangabe gefragt, leistet \vpageref{key} genau das; seine beiden optionalen Argumente legen die Formulierung für denselben Fall beziehungsweise die Einleitung für eine andere Seite fest.

Diese Klugheit hat ihren Preis. Was \vref ausgibt, hängt vom Satzergebnis ab – davon, auf welcher Seite etwas gelandet ist –, und die Länge der Ausgabe kann ihrerseits einen Seitenumbruch verschieben. Es kann also ein zusätzlicher Kompilierlauf nötig sein, bis sich die Werte beruhigen. Ein Log, das immer wieder „Rerun to get cross-references right“ meldet, hat meist genau diese Ursache. Gemeinsam mit cleveref geladen, wird \vref in cleveref-Formatierung gesetzt; wer beides einsetzt, hält also die Reihenfolge (varioref → hyperref → cleveref) ein und stellt das ganze Dokument auf die \cref-Familie um – das gibt weniger zu bedenken.

\usepackage{varioref}

See~\vref{fig:leaf}.
%   same page : See figure 3.
%   next page : See figure 3 on the next page.
%   far away  : See figure 3 on page 12.

The data is summarised \vpageref[above][]{tab:data}.

Wer sich nicht entscheiden kann, fährt praktisch am besten damit, das ganze Dokument auf cleveref umzustellen. Artwort, Numerus, Mehrfachverweise und Bereiche werden selbsttätig erledigt, womit der klassische Ausrutscher – Figure~\ref{tab:...} bei einer Tabelle – strukturell unmöglich wird. \ref und \pageref bleiben unverzichtbar, um die Mechanik zu verstehen; \eqref behauptet seinen Platz in der Mathematik, \vref im gebundenen Werk. Die folgende Tabelle fasst zusammen, was jeder Befehl ausgibt.