Renvois croisés

« Voir la figure 3 », « d’après l’équation (2) », « se reporter à la page 2 » : si vous écrivez ces numéros et pages à la main, le déplacement d’une seule figure ou section les rend faux. LaTeX permet plutôt d’attacher un nom et de laisser la machine compter. Des commandes de base \label et \ref/\pageref à \eqref d’amsmath, \autoref et \nameref d’hyperref, puis varioref et cleveref, cette page présente les outils qui gardent les références correctes automatiquement.

Le cœur : \label et \ref

Tout le système repose sur deux commandes. \label{key} associe le nom key à la valeur du compteur qui vient d’être incrémenté le plus récemment à cet endroit. \ref{key} insère ensuite ce numéro dans le texte. LaTeX fait le comptage : vous ne tapez jamais le numéro vous-même. Le key est une chaîne de votre choix, le surnom par lequel votre source désigne une figure, une équation ou une section.

Le point crucial est « le plus récemment incrémenté » : ce que capture \label dépend de l’endroit où vous le placez. Pour une figure ou un tableau, mettez-le juste après \caption, car c’est \caption qui incrémente le compteur ; placé juste après \begin{figure}, il pourrait capturer le numéro de chapitre. Pour une équation, placez-le dans l’environnement equation ; pour un titre, juste après \section ou équivalent. Règle pratique : placez \label immédiatement après la commande qui produit le numéro.

\section{はじめに}
\label{sec:intro}

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

\begin{figure}
  \centering
  \includegraphics{leaf}
  \caption{葉脈の構造}
  \label{fig:leaf}
\end{figure}

第\ref{sec:intro}節で述べたように、式~\ref{eq:euler}と図~\ref{fig:leaf}を参照する。

\ref ne renvoie que le numéro : vous écrivez donc le mot vous-même, « Figure », « équation », « section ». La convention est de joindre le mot et le numéro par une espace insécable ~ plutôt qu’une espace ordinaire, afin qu’un saut de ligne ne sépare jamais le mot de son numéro, par exemple Figure~\ref{fig:leaf}. C’est précisément cette formulation manuelle, et le risque de se tromper de type, que \autoref et \cref suppriment plus bas.

Pourquoi compiler deux fois

Les références croisées ne se stabilisent pas en une seule compilation. Chaque fois que LaTeX rencontre un \label, il écrit ce numéro et cette page dans le fichier .aux, un fichier auxiliaire portant le même nom de base que le document. \ref utilise les informations écrites dans .aux lors de l’exécution *précédente*. Au premier passage, les numéros cibles ne sont donc pas encore connus : la sortie affiche un ?? gras, et le journal contient cet avertissement.

LaTeX Warning: Label(s) may have changed. Rerun to get cross references right.

Compilez une fois de plus : les valeurs de .aux sont relues et les ?? deviennent les bons numéros. Si la numérotation bouge et qu’une valeur référencée change, l’avertissement revient ; il faut donc répéter jusqu’à sa disparition. En pratique, deux passages suffisent souvent. Les outils comme latexmk exécutent cette boucle pour vous, et Overleaf compile plusieurs fois en arrière-plan, si bien que vous y voyez rarement les ??.

Références de page et nommage

Quand vous voulez la page plutôt que le numéro, utilisez \pageref{key}. La commande prend le même nom et renvoie le numéro de la page où se trouve ce \label. Vous pouvez ainsi citer numéro et page ensemble : « voir la figure 3 page 12 », par exemple Figure~\ref{fig:leaf} on page~\pageref{fig:leaf}.

Le key peut être n’importe quoi, mais une convention très répandue consiste à lui donner un préfixe indiquant son type : sec: pour section, fig: pour figure, tab: pour tableau, eq: pour équation, ch: pour chapitre, lst: pour listing. Deux avantages en découlent. Nommer par le sens, comme fig:leaf, évite de renommer les labels si l’ordre des figures change. Et un simple \ref{fig:...} indique le type de cible, tout en évitant les collisions entre noms de légende et de listing.

Références d’équations : \eqref (amsmath)

Les numéros d’équation s’écrivent conventionnellement entre parenthèses (« d’après l’équation (3) »). \ref seul renvoie seulement 3, ce qui oblige à ajouter les parenthèses à la main ; \eqref{key}, disponible avec amsmath, les ajoute pour vous et renvoie (3). Mieux encore, les parenthèses sont toujours composées droites, quelle que soit la police environnante, si bien qu’elles ne s’inclinent pas dans du texte italique. Pour les équations, \eqref est plus pratique que \ref.

\usepackage{amsmath}
% ...
式~\eqref{eq:euler}はオイラーの等式である。
% 出力: 式 (1) はオイラーの等式である。

Extensions d’hyperref : \autoref et \nameref

Charger hyperref transforme chaque référence en lien cliquable dans le PDF et ajoute deux commandes pratiques. \autoref{key} préfixe automatiquement le mot correspondant au type de cible, « Figure », « section », etc. ; une section donne « section 3.4 », une figure « Figure 3 », et l’ensemble devient un lien. Cela évite d’écrire manuellement « Figure » dans Figure~\ref{...} et de se tromper de type. Le mot préfixé se change en redéfinissant \figureautorefname, \sectionautorefname et similaires ; c’est aussi la méthode de localisation.

L’autre commande, \nameref{key}, insère non pas un numéro mais le texte du titre de la cible. Référencer avec \nameref le label placé sur \section{Introduction} donne les mots « Introduction ». Utilisez-la pour référer par titre plutôt que par numéro, par exemple « comme discuté dans ‘Introduction’ ».

\usepackage{hyperref}
% ...
\autoref{fig:leaf}を参照。   % 出力: Figure 3 を参照。（リンク付き）
\nameref{sec:intro}で述べた。 % 出力: はじめに で述べた。

Références sensibles à la page : varioref

Dans un document relié, il est plus naturel d’écrire « la figure à la page suivante » quand elle est proche, ou « sur la page en regard » dans la même double page, plutôt que « la figure à la page N ». \vref{key} de varioref imprime le numéro comme \ref, mais vérifie si la cible est sur une autre page et ajoute automatiquement une indication de page : « on the next page », « on the facing page », « on page 5 ». Si la cible est sur la même page, il n’ajoute rien.

Quand vous voulez seulement l’indication de page, utilisez \vpageref{key} : pas de numéro, seulement « on the next page », etc. \vpageref prend deux arguments optionnels : le premier définit le texte employé quand la cible est sur la même page, le second l’introduction quand elle ne l’est pas. C’est utile lorsque la référence et sa cible sont proches et peuvent ou non être séparées par un saut de page. Comme sa sortie varie dynamiquement avec la position dans la page, varioref peut nécessiter une compilation supplémentaire.

\usepackage{varioref}
% ...
See~\vref{fig:leaf}.
% 同ページ: See figure 3.
% 別ページ: See figure 3 on the next page.  /  ... on page 12.

Références intelligentes : cleveref (\cref / \Cref)

cleveref élève les références d’un cran. \cref{key} préfixe le mot du type comme \autoref, par défaut « fig. 1 », ou « figure 1 » avec l’option noabbrev, mais sa vraie force est dans les références multiples et les plages. Passez les labels séparés par des virgules sans espaces, \cref{a,b,c}, et il trie et compacte automatiquement les numéros, produisant « figures 1, 2 and 3 » ou « equations~(2) and~(4) », avec le bon singulier/pluriel. Une plage continue se contracte avec \crefrange{first}{last} en « figures 1 to 3 ».

En début de phrase, on veut une majuscule : utilisez \Cref{key} avec initiale capitale, pour des débuts comme « Figure 3 shows … » ; au milieu d’une phrase, utilisez \cref. Pour tout capitaliser, chargez le paquet avec l’option capitalise. Le mot préfixé se définit ou se change avec \crefname{type}{singulier}{pluriel} ; la variante à majuscule est \Crefname. C’est aussi ainsi qu’on le localise en japonais et dans d’autres langues, par exemple \crefname{figure}{図}{図}. Pour obtenir seulement le numéro, comme avec \ref, utilisez \labelcref{key}.

L’ordre de chargement est décisif : cleveref doit venir en dernier, après hyperref. Si vous utilisez aussi varioref, chargez dans l’ordre varioref → hyperref → cleveref. Un mauvais ordre peut faire pointer les références vers une cible complètement différente, sans avertissement dans le journal.

\usepackage{varioref}
\usepackage{hyperref}
\usepackage{cleveref}   % 必ず最後に / always last
% ...
\cref{fig:a,fig:b,fig:c}   % figures 1 to 3
\cref{eq:euler,eq:max}     % equations (1) and (4)
\Cref{sec:intro} discusses % Section 1 discusses ...

En cas d’hésitation, il est recommandé de standardiser tout le document sur cleveref. Il gère automatiquement le mot du type, le singulier/pluriel, les références multiples et les plages ; l’erreur possible avec Figure~\ref{...}, comme écrire « Table » au lieu de « Figure », ne peut tout simplement plus se produire.