Renvois croisés

LaTeX lit un document une seule fois, de haut en bas. Lorsque \ref{fig:leaf} apparaît page 2 alors que la figure nommée se trouve page 40, le numéro n'existe donc pas encore — et toute la mécanique de renvois de LaTeX, \label et \ref, ne sert qu'à résoudre ce problème unique : la référence précède sa cible. La réponse est d'une simplicité désarmante : écrire les numéros dans un fichier .aux au premier passage, les relire au second. Cette page suit cette idée à travers les deux compilations, le ?? gras qui apparaît entre-temps, la raison pour laquelle un \label placé avant sa \caption annonce le mauvais numéro, et les améliorations qu'apportent cleveref et varioref.

\label et \ref : appeler par le nom, jamais par le numéro

Les renvois reposent sur deux commandes. \label{key} lie le nom key à la valeur du compteur incrémenté en dernier à cet endroit, et n'imprime rien. \ref{key} insère seulement le numéro que ce nom désigne. C'est LaTeX qui compte : aucun chiffre à saisir. Le key est une chaîne libre, et comme l'étiquette voyage avec l'objet, on peut réordonner des figures ou déplacer une section entière dans un autre chapitre sans qu'aucun renvoi ne décroche. Un document où « figure 3 » est écrit à la main s'effondre après un tel déplacement ; celui-ci ne bouge pas.

\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}.

Un détail fait trébucher presque tout le monde : \ref ne renvoie que le numéro. Les mots « figure », « équation », « section » ne suivent pas ; il faut les écrire soi-même et les relier au numéro par une espace insécable ~ plutôt qu'une espace ordinaire. Avec Figure \ref{fig:leaf}, une ligne peut se terminer après « Figure » et abandonner le « 3 » à la ligne suivante ; avec Figure~\ref{fig:leaf}, aucune coupure n'est possible à cet endroit. C'est précisément cette petite corvée manuelle — nommer le type — que \cref et \autoref reprennent plus bas.

Pourquoi compiler deux fois : le fichier .aux et le ??

Les renvois ne se stabilisent pas en une compilation. Chaque fois que LaTeX rencontre un \label, il écrit ce numéro et cette page dans un fichier .aux portant le même nom de base que le document — et \ref ne peut lire que ce qu'y a déposé l'exécution précédente. Au premier passage, les valeurs cibles n'existent donc nulle part : la sortie affiche un ?? gras et le journal contient deux avertissements. Il vaut la peine de les reconnaître, car ce sont exactement les chaînes que l'on tape ensuite dans un moteur de recherche.

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.

Ce ?? n'est pas un accident mais une règle inscrite dans le noyau de LaTeX. Dans latex.ltx, la macro \@setref compose \reset@font\bfseries ?? lorsqu'une étiquette se révèle indéfinie, et émet l'avertissement « Reference … undefined » à la ligne suivante. Le gras est délibéré : il ne se fond pas dans la fonte environnante, si bien que le trou saute aux yeux. Une compilation de plus rapatrie les valeurs du .aux et transforme les ?? en vrais numéros. Si la numérotation bouge et qu'une valeur référencée change, l'avertissement revient : la bonne méthode est donc de répéter jusqu'à sa disparition ; deux passages suffisent le plus souvent. latexmk fait tourner cette boucle pour vous, et Overleaf compile plusieurs fois en coulisses, d'où la rareté des ?? là-bas.

Le fichier .aux est du texte brut : il suffit de l'ouvrir et de le lire. Chaque étiquette y ajoute une ligne \newlabel, et cette ligne porte cinq champs : le numéro, la page, le texte du titre, le nom d'ancre vers lequel pointer, et un dernier tenu en réserve. C'est grâce au troisième champ que \nameref peut insérer le titre lui-même ; grâce au quatrième que hyperref sait où doit mener un clic. Quand un renvoi se comporte mal sans raison apparente, le chemin le plus court passe par le .aux : la ligne y est-elle ? Si elle manque, le \label n'a jamais été capté ; si la valeur semble fausse, c'est une question de placement — le sujet de la section suivante.

% 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}{}}

Quand \ref donne le mauvais numéro : \label va après \caption

Un renvoi de figure qui ne correspond pas à la figure : la cause tient presque toujours à l'emplacement du \label. Un \label ne capte pas le numéro de figure parce qu'il se trouve dans un environnement figure. Il capte la valeur du compteur incrémenté juste avant lui, et l'environnement figure n'incrémente aucun compteur. Celui qui fait avancer le compteur, c'est \caption. Un \label écrit juste après \begin{figure} capture donc non pas le numéro de figure, mais le dernier compteur incrémenté — le plus souvent le numéro de la section ou du chapitre en cours.

L'expérience convainc plus vite qu'un discours. Placez une figure dans la septième section, attachez une étiquette avant et une après la \caption, puis compilez avec pdfLaTeX de TeX Live 2024 : le .aux enregistre 7 pour l'étiquette placée avant — le numéro de section — et 1 pour celle placée après, le numéro de figure. Et pas le moindre avertissement. Les deux sont des numéros plausibles ; LaTeX n'a aucun moyen de trancher. C'est justement parce qu'aucune erreur n'arrête la compilation que cette bévue passe la relecture et arrive à l'impression.

\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}{}{}{}}

La règle tient en une phrase : placer \label immédiatement après la commande qui produit le numéro. Pour les figures et tableaux, après \caption (dans son argument, c'est également correct) ; pour les titres, juste après \section et consorts ; pour les équations numérotées, à l'intérieur de l'environnement equation ; pour les entrées de liste, après \item. Dans une figure portant plusieurs légendes, une étiquette unique renverra au numéro de la \caption qui la précède. Quant à écrire \label avant une \caption, la seule raison valable est qu'il n'y a pas de \caption du tout.

\pageref et le nommage des étiquettes

Pour désigner la page plutôt que le numéro, on utilise \pageref{key}. La commande prend la même étiquette et renvoie le numéro de la page où ce \label a été composé, ce qui permet de citer les deux : Figure~\ref{fig:leaf} on page~\pageref{fig:leaf}. Structurellement, c'est simplement le deuxième champ de la ligne \newlabel qui revient. Elle prend tout son sens dans les documents que l'on feuillette vraiment — rapports longs, thèses reliées — plutôt qu'à l'écran.

Un key peut porter n'importe quel nom, mais l'usage courant consiste à le préfixer par la nature de la cible : sec:, fig:, tab:, eq:, ch:, lst:. Deux conséquences. D'abord, nommer par le contenu — fig:leaf — évite tout renommage lors d'une réorganisation, alors qu'un nom comme fig:3 devient mensonger dès qu'une deuxième figure s'intercale. Ensuite, la seule vue de \ref{fig:...} indique le type de la cible, ce qui rend la source mécaniquement lisible le jour où le document passe à \cref.

\eqref : des numéros d'équation avec leurs parenthèses (amsmath)

Les numéros d'équation s'écrivent par convention entre parenthèses — « d'après l'équation (3) » — mais \ref seul ne renvoie que 3. Avec amsmath chargé, \eqref{key} fournit les parenthèses et renvoie (3). Le vrai gain n'est pas la frappe mais la fonte : les parenthèses produites par \eqref sont toujours composées droites, quelle que soit la fonte environnante ; dans un environnement de théorème au corps italique, elles restent verticales. Écrites à la main, (\ref{eq:euler}) verrait ces mêmes parenthèses s'incliner avec l'italique.

cleveref : \cref et \Cref s'occupent du mot et du pluriel

cleveref élève le renvoi d'un cran. \cref{key} préfixe le mot correspondant au type de la cible (abrégé par défaut — « fig. 1 » — ou « figure 1 » avec l'option noabbrev), et \Cref{key} le met en capitale pour ouvrir une phrase. Sa vraie force tient aux listes et aux plages : passez les étiquettes séparées par des virgules sans espaces — \cref{fig:a,fig:b,fig:c} — et les numéros sont triés et joints, le mot passant au pluriel au passage, pour donner par exemple « figs. 1, 2 and 4 ». Mieux : une suite continue se replie d'elle-même en plage, si bien que ces trois-là ressortent en « figs. 1 to 3 ». \crefrange{first}{last} obtient la même contraction en ne nommant que les deux extrémités.

Le mot préfixé se redéfinit avec \crefname{type}{singulier}{pluriel} (\Crefname pour la forme capitalisée). C'est aussi ainsi qu'on localise : \crefname{figure}{figure}{figures}. Pour capitaliser dans tout le document, on charge le paquet avec l'option capitalise. À l'inverse, là où seul le numéro est souhaité, sans aucun mot — entre parenthèses, dans une cellule de tableau —, \labelcref{key} donne exactement ce que produirait un \ref ordinaire.

L'ordre de chargement obéit à une règle absolue : cleveref vient après hyperref, varioref et amsmath — les trois sont vérifiés. cleveref construit ses commandes en détectant ce qu'a défini hyperref ; l'inverse ne peut tout simplement pas fonctionner. Heureusement, l'échec n'est pas silencieux : le cleveref.sty livré avec TeX Live 2024 vérifie l'ordre à \begin{document} et s'arrête avec le message ci-dessous. La combinaison avec varioref est un autre cas : le manuel de cleveref prescrit l'ordre varioref → hyperref → cleveref et avertit qu'un mauvais ordre peut faire pointer les renvois vers tout autre chose, sans aucun avertissement dans la sortie ni dans le journal.

\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 : « à la page suivante » plutôt qu'un numéro nu

Dans un document relié, « la figure 3 à la page suivante » se lit mieux qu'un mécanique « la figure 3 page 12 », et « sur la page en regard » mieux encore quand les deux occupent une même double page. \vref{key} de varioref imprime le même numéro que \ref, puis examine la position relative du renvoi et de sa cible pour ajouter la formule qui convient. Sur une même page, il n'ajoute rien. Si seule l'indication de page importe, \vpageref{key} s'en charge, et ses deux arguments optionnels fixent la formule pour le cas de la même page et l'amorce pour celui d'une autre page.

Cette intelligence a un coût. Ce qu'imprime \vref dépend du résultat de la composition — sur quelle page les choses sont tombées — et la longueur de cette impression peut elle-même déplacer une coupure de page ; il faut donc parfois une compilation supplémentaire pour que les valeurs se stabilisent. Un journal qui répète « Rerun to get cross-references right » a le plus souvent cette cause. Chargé avec cleveref, \vref adopte la mise en forme de cleveref : si les deux servent, respectez l'ordre (varioref → hyperref → cleveref) et alignez tout le document sur la famille \cref ; il y aura moins à surveiller.

\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}.

Dans le doute, la réponse pratique consiste à aligner tout le document sur cleveref. Il gère seul le mot du type, le pluriel, les renvois multiples et les plages, ce qui rend structurellement impossible la bévue classique : écrire Figure~\ref{tab:...} alors que la cible est un tableau. \ref et \pageref restent indispensables pour comprendre la mécanique ; \eqref garde sa place en mathématiques et \vref dans l'imprimé relié. Le tableau ci-dessous résume ce que chacun imprime.