Légendes et sous-figures

Toutes les figures sont numérotées correctement et pourtant \ref imprime un autre numéro : le « mauvais numéro de figure », le problème le plus souvent signalé sous LaTeX, vient presque toujours d'un \label écrit avant \caption. Ni erreur, ni avertissement ; seul le chiffre imprimé ment en silence. La commande de légende paraît modeste, mais la numérotation, les renvois et la liste des figures se décident tous ici. Cette page traite des raisons pour lesquelles \caption ne fonctionne que dans un flottant, de la place de \label, de la mise en forme avec le package caption, de \captionof pour ce qui n'est pas un flottant, et des sous-figures étiquetées (a) et (b).

Pourquoi \caption ne fonctionne que dans un flottant

\caption{…} attache un texte explicatif à une figure ou à un tableau, mais ne fonctionne qu'à l'intérieur de figure ou table. Écrite dans le texte courant, elle s'arrête sur ! LaTeX Error: \caption outside float. La raison : la commande ne se contente pas de composer du texte, elle regarde dans quel type de flottant elle se trouve et incrémente le compteur correspondant. Dans figure elle avance le compteur figure, dans table le compteur table. Hors d'un flottant, cette information n'existe pas, donc aucun numéro n'est attribuable. C'est aussi pourquoi on n'écrit jamais le numéro soi-même — et qu'on ne doit pas le faire.

\begin{figure}
  \centering
  \includegraphics[width=0.6\textwidth]{plot}
  \caption{Measured values against the theoretical curve}
  \label{fig:plot}   % after \caption -- always
\end{figure}

Un mot sur l'usage : la légende d'une figure se place normalement sous la figure, celle d'un tableau au-dessus du tableau. Un tableau se lit de haut en bas, il est donc naturel d'annoncer d'abord ce qu'il contient. LaTeX compose \caption exactement là où elle est écrite : avant l'illustration pour une légende en haut, après pour une légende en bas. Le format lui-même — l'espace entre le numéro et le texte, etc. — ne dépend pas de la position. Cela dit, la revue tranche le plus souvent la question ; consultez d'abord ses consignes de présentation.

Ce qui arrive quand \label précède \caption

\label doit toujours suivre \caption. \label ne fait qu'enregistrer « le numéro courant », et c'est \caption qui met ce numéro courant à la valeur du numéro de la figure. Placé avant, \label enregistre donc le dernier compteur ayant bougé — d'ordinaire le numéro de section. Compilez, dans la section 5, une figure qui devrait porter le numéro 2 avec son \label avant le \caption : le fichier auxiliaire reçoit \newlabel{fig:before}{{5}{1}...} et le texte imprime « Figure 5 ». Ni erreur, ni avertissement. Sans relecture de la sortie, l'erreur survit jusqu'à la version finale.

Le piège a une forme reconnaissable. Il semble naturel d'écrire \label juste après \includegraphics, comme si l'on attachait une étiquette à l'image. Mais ce que \label désigne n'est pas l'image : c'est un compteur, et c'est \caption qui règle ce compteur. Le remède est simple : garder toujours \caption et \label sur deux lignes voisines. Sans rien entre les deux, l'ordre ne peut pas s'inverser. Il en va de même dans les sous-figures : un \label dans une subfigure suit le \caption de cette sous-figure. La mécanique générale de \label et \ref est traitée sur la page des renvois.

Intitulés courts et liste des figures : \caption[...]{...}, \caption*, \ContinuedFloat

Quand une légende est longue et qu'une seule ligne doit figurer dans la liste des figures, c'est l'argument optionnel qu'il faut : \caption[intitulé court]{texte long}. Ce qui est entre crochets va dans \listoffigures ; ce qui est entre accolades se compose auprès de la figure. Sans crochets, le texte complet part aussi dans la liste, ce qui la ruine dès que plusieurs figures portent des légendes de trois lignes. Dans un document d'essai, \caption[Short entry for the list]{A long caption that is only shown under the figure} n'inscrit que la forme courte dans le fichier .lof. Lorsque la légende contient des mathématiques ou un \cite, garder la version entre crochets toute simple évite en outre les accidents de composition dans la liste.

Charger le package caption met deux variantes à portée. \caption*{…} produit une légende ni numérotée ni répertoriée — ce qu'il faut pour un frontispice ou une planche d'ouverture de chapitre. \ContinuedFloat fait qu'un flottant reprend le numéro du flottant précédent, ce dont on a besoin quand une grande figure doit être scindée en plusieurs flottants. Mettez \ContinuedFloat en tête d'un \begin{figure} puis \caption{Continued} : ce qui s'imprime est une seconde planche toujours numérotée « Figure 1 ». C'est le geste standard pour une grande figure de synthèse étalée sur plusieurs pages, sans gonfler la numérotation.

% short entry for the list, full text under the figure
\caption[Measured values and the model]{Measured values (dots) against the
  theoretical curve (solid). Error bars are one standard deviation.}

% no number, no entry in the list of figures
\caption*{Frontispiece}

% second sheet of a split figure keeps the previous number
\begin{figure}
  \ContinuedFloat
  \centering\includegraphics[width=\linewidth]{survey-part2}
  \caption{Continued}
\end{figure}

Mettre en forme avec le package caption : \captionsetup

Pour changer la police, le séparateur entre numéro et texte ou l'alignement, on emploie le package caption. Son auteur est Axel Sommerfeldt, sa mention de copyright remonte à 1994, et la version présente dans TeX Live 2024 est la v3.6o d'août 2023 — un outil entretenu par une seule personne pendant trois décennies. On le charge avec \usepackage{caption} et on le règle avec \captionsetup{clé=valeur, …}. L'essentiel de cette commande tient à sa portée : écrite dans le préambule, elle régit tout le document ; écrite dans un flottant, elle ne régit que cette légende-là.

La dernière clé, singlelinecheck, est le réglage par défaut le plus susceptible de surprendre. Si vous avez écrit justification=raggedright et que les légendes courtes se centrent malgré tout, voilà pourquoi : toute légende tenant sur une ligne est centrée automatiquement. Ajoutez singlelinecheck=false pour les garder alignées à gauche. Pour distinguer figures et tableaux, nommez le type de flottant entre crochets : \captionsetup[figure]{…} et \captionsetup[table]{…}. Les modèles de revue embarquent souvent leur propre \captionsetup ; avant d'ajouter le vôtre, vérifiez que vous n'écrasez pas le leur.

\usepackage{caption}
\captionsetup{labelfont=bf, labelsep=period, font=small,
              justification=raggedright, singlelinecheck=false}

% different rules per float type
\captionsetup[figure]{justification=centering}
\captionsetup[table]{font=footnotesize}

Légender ce qui n'est pas un flottant : \captionof

Quand une figure doit rester exactement à cet endroit du texte au lieu de flotter, tout en gardant une numérotation et des renvois normaux, la commande est \captionof{type}{texte}. Dans une minipage ou un center, où \caption refuse de fonctionner, \captionof{figure}{…} incrémente le compteur figure, ajoute une ligne à la liste des figures et permet à \ref de se résoudre correctement. Composez-la dans une minipage : si le flottant précédent était « Figure 1 », celle-ci devient dûment « Figure 2 » et obtient sa propre entrée dans le .lof. Tout l'intérêt de la commande est là : retirer la mécanique flottante, conserver la mécanique de numérotation.

Une réserve : \captionof n'est pas une commande standard de LaTeX ; l'écrire sans charger caption donne ! Undefined control sequence. Si vous voulez la commande sans la mise en forme du package, le paquet léger capt-of fournit \captionof à lui seul. Et la règle d'ordre ne change pas ici non plus : avec \captionof aussi, \label vient après.

\usepackage{caption}   % or the lightweight capt-of

\begin{center}
  \includegraphics[width=0.5\textwidth]{diagram}
  \captionof{figure}{A figure fixed in the text, outside any float}
  \label{fig:inline}
\end{center}

Découper une figure en (a) et (b) avec subcaption

Pour aligner de petites figures dans une seule figure, chacune avec son sous-label (a), (b), (c), le standard actuel est le package subcaption — encore de Sommerfeldt. Écrire \usepackage{subcaption} charge caption en dessous, inutile donc de nommer les deux. L'outil principal est l'environnement subfigure (subtable pour les tableaux), qui exige une largeur en argument obligatoire, comme \begin{subfigure}[b]{0.45\textwidth}. C'est en pratique une minipage, que l'on remplit d'un \includegraphics et d'un \caption. Un \caption à l'intérieur d'une subfigure devient le sous-label (a)/(b) ; celui placé à l'extérieur numérote la figure entière.

\usepackage{graphicx}
\usepackage{subcaption}   % loads caption itself

\begin{figure}
  \centering
  \begin{subfigure}[b]{0.45\textwidth}
    \centering
    \includegraphics[width=\linewidth]{before}
    \caption{Before}
    \label{fig:before}
  \end{subfigure}
  \hfill
  \begin{subfigure}[b]{0.45\textwidth}
    \centering
    \includegraphics[width=\linewidth]{after}
    \caption{After}
    \label{fig:after}
  \end{subfigure}
  \caption{Before and after processing}
  \label{fig:compare}
\end{figure}

À la compilation, la figure entière devient « Figure 1 » tandis que les deux sous-figures se composent en « (a) Before » et « (b) After ». Dans le texte, \ref{fig:compare} renvoie « 1 » et \ref{fig:before} renvoie « 1a » : un renvoi à une sous-figure est le numéro de la figure accolé au sous-label. Pour n'obtenir que le sous-label, \subref{fig:before} donne « a » seul et \subref*{fig:before} donne « (a) ». Il existe aussi une forme d'une seule ligne, \subcaptionbox[entrée de liste]{titre}[largeur][pos interne]{contenu}. Sa syntaxe place le \label dans l'argument du titre, comme dans \subcaptionbox{Before\label{fig:before}}{\includegraphics{…}}. Pour une sous-figure ne contenant qu'une image, c'est plus court que plusieurs lignes de minipage.

subfigure, subfig, subcaption : trois générations et un conflit silencieux

Les packages de sous-figures existent en trois générations, et leurs noms voisins entretiennent les confusions. Le plus ancien, subfigure, est obsolète et repose sur une commande \subfigure ; son successeur subfig fournit \subfloat mais n'est plus activement maintenu non plus. Les documents neufs doivent employer subcaption. L'ennui survient en cours de migration : on ajoute subcaption sans remarquer que le modèle charge déjà subfig.

Ce qui rend ce conflit pénible, c'est que rien ne se passe au chargement. Mettez les deux dans le préambule et subcaption se contente d'écrire une ligne d'information dans le journal — Package subcaption Info: The counter 'subfigure' was already defined by... — sans avertissement ni erreur. Il renonce alors discrètement à définir son propre environnement subfigure. Le document avance sans encombre jusqu'au premier \begin{subfigure}, où tout s'écroule sur ! LaTeX Error: Environment subfigure undefined., suivi d'une cascade de Missing number et de Illegal unit of measure. Autrement dit, le lieu de l'erreur n'est pas le lieu de sa cause. Devant ce schéma, cherchez d'abord subfig et subfigure dans tout le préambule : le risque est le plus élevé à l'intérieur d'un modèle de revue.

• subcaption — le standard actuel : environnements subfigure / subtable, \subcaptionbox, \subref. Charge caption tout seul.
• subfig — la génération précédente, avec \subfloat. Acceptable dans les documents existants ; à ne pas choisir pour les nouveaux.
• subfigure — le plus ancien, avec \subfigure. Obsolète, à ne pas utiliser.
• Ne jamais les combiner — un seul, exactement. Vérifiez si le modèle en charge déjà un avant d'en ajouter un autre.