Referencias cruzadas

LaTeX lee un documento una sola vez, de arriba abajo. Así que cuando \ref{fig:leaf} aparece en la página 2 y la figura que nombra está en la página 40, ese número todavía no existe: toda la maquinaria de referencias cruzadas de LaTeX, \label y \ref, existe para resolver ese único problema, la referencia llega antes que su destino. La respuesta es de una sencillez desarmante: escribir los números en un archivo .aux en la primera pasada y volver a leerlos en la segunda. Esta página sigue esa idea a través de las dos compilaciones, el ?? en negrita que aparece por el camino, el motivo por el que un \label colocado antes de su \caption da el número equivocado, y las mejoras que aportan cleveref y varioref.

\label y \ref: llamar por el nombre, nunca por el número

Las referencias cruzadas se apoyan en dos comandos. \label{key} vincula el nombre key al valor del contador incrementado más recientemente en ese punto, y no imprime nada. \ref{key} inserta solo el número que ese nombre representa. Cuenta LaTeX, de modo que no se teclea ni una cifra. El key es una cadena libre y, como la etiqueta viaja con el objeto, se pueden reordenar figuras o mover una sección entera a otro capítulo sin que ningún renvío se descuelgue. Un documento que dice “Figura 3” escrito a mano se desmorona tras un solo traslado; este no.

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

Hay un punto en el que tropieza casi todo el mundo: \ref devuelve solo el número. Las palabras “Figura”, “ecuación”, “Sección” no vienen con él; hay que escribirlas y unirlas al número con un espacio no separable ~ en lugar de un espacio ordinario. Con Figure \ref{fig:leaf}, una línea puede terminar tras “Figure” y dejar el “3” abandonado en la siguiente; con Figure~\ref{fig:leaf} no cabe ruptura ahí. Esa pequeña tarea manual —nombrar el tipo— es justo lo que \cref y \autoref asumen más abajo.

Por qué se compila dos veces: el archivo .aux y el ??

Las referencias cruzadas no se estabilizan en una sola compilación. Cada vez que LaTeX encuentra un \label escribe ese número y esa página en un archivo .aux con el mismo nombre base que el documento, y lo único que \ref puede leer es lo que dejó allí la ejecución anterior. En la primera pasada, por tanto, los valores de destino no existen en ninguna parte: la salida muestra un ?? en negrita y el registro trae dos advertencias. Conviene reconocer ambas, porque son justo las cadenas que uno acaba escribiendo en un buscador.

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.

Ese ?? no es un accidente sino una regla escrita en el núcleo de LaTeX. En latex.ltx, la macro \@setref compone \reset@font\bfseries ?? cuando una etiqueta resulta indefinida, y emite el aviso “Reference … undefined” en la línea inmediatamente siguiente. La negrita es deliberada: no se funde con la letra circundante, de modo que el hueco resulta imposible de pasar por alto. Una compilación más recupera los valores del .aux y convierte los ?? en números reales. Si la numeración se desplaza y cambia un valor referenciado, la advertencia vuelve, así que lo correcto es repetir hasta que desaparezca; dos pasadas suelen bastar. latexmk da esa vuelta por usted, y Overleaf compila varias veces entre bastidores, por lo que allí el ?? es una rareza.

El archivo .aux es texto plano, así que basta con abrirlo y leerlo. Cada etiqueta aporta una línea \newlabel, y esa línea lleva cinco campos: el número, la página, el texto del encabezado, el nombre del ancla al que enlazar y uno más en reserva. Gracias al tercer campo, \nameref puede insertar el título mismo; gracias al cuarto, hyperref sabe adónde debe llevar un clic. Cuando una referencia se comporta mal y la causa no es evidente, el camino más corto pasa por el .aux: ¿está esa línea? Si falta del todo, el \label nunca se recogió; si el valor parece equivocado, es cuestión de dónde está colocado, el tema de la sección siguiente.

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

Cuando \ref da el número equivocado: \label va después de \caption

Una referencia a una figura que no coincide con la figura: la causa es, casi sin excepción, dónde está el \label. Un \label no capta el número de figura por estar dentro de un entorno figure. Capta el valor del contador incrementado justo antes de él, y el entorno figure no incrementa contador alguno. Quien hace avanzar el contador es \caption. De modo que un \label escrito justo después de \begin{figure} captura no el número de figura, sino el último contador incrementado: casi siempre el número de la sección o el capítulo en curso.

Comprobarlo convence más rápido que explicarlo. Coloque una figura dentro de la séptima sección, ponga una etiqueta antes y otra después del \caption y compile con pdfLaTeX de TeX Live 2024: el .aux registra 7 para la etiqueta escrita antes —el número de sección— y 1 para la escrita después, el número de figura. Y no aparece ni una advertencia. Ambos son números plausibles, así que LaTeX no tiene manera de decidir cuál está mal. Justamente porque no se detiene con un error, este desliz atraviesa la revisión y llega a imprenta.

\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 regla se resume en una línea: coloque \label inmediatamente después del comando que produce el número. Para figuras y tablas, tras \caption (dentro de su argumento también vale); para encabezados, justo después de \section y afines; para ecuaciones numeradas, dentro del entorno equation; para entradas de lista, tras \item. En una figura con varias leyendas, una sola etiqueta apunta al número de la \caption que la precede. Y en cuanto a escribir \label antes de un \caption, la única razón legítima es que no haya \caption en absoluto.

\pageref y cómo nombrar las etiquetas

Cuando se quiere la página en lugar del número, se usa \pageref{key}. Toma la misma etiqueta y devuelve el número de la página en la que se compuso ese \label, de modo que ambos pueden citarse juntos: Figure~\ref{fig:leaf} on page~\pageref{fig:leaf}. Estructuralmente es, sin más, el segundo campo de la línea \newlabel que regresa. Rinde de verdad en documentos que el lector hojea físicamente —informes largos, tesis encuadernadas— más que en pantalla.

Un key puede llamarse como se quiera, pero la práctica extendida es anteponerle la clase de destino: sec:, fig:, tab:, eq:, ch:, lst:. De ahí se siguen dos cosas. Primero, nombrar por contenido —fig:leaf— evita renombrar al reordenar, mientras que un nombre como fig:3 se vuelve mentira en cuanto se intercala una segunda figura. Segundo, ver \ref{fig:...} revela de inmediato el tipo de destino, lo que hace la fuente mecánicamente legible el día en que el documento se pase a \cref.

\eqref: números de ecuación con sus paréntesis (amsmath)

Los números de ecuación se escriben por convención entre paréntesis —“por la ecuación (3)”—, pero \ref a secas devuelve solo 3. Con amsmath cargado, \eqref{key} aporta los paréntesis y devuelve (3). La ganancia real no está en las pulsaciones sino en la letra: los paréntesis que produce \eqref se componen siempre rectos, sea cual sea la fuente que los rodea, de modo que dentro de un entorno de teorema con cuerpo en cursiva siguen verticales. Escrito a mano, (\ref{eq:euler}) vería esos mismos paréntesis inclinarse con la cursiva.

cleveref: \cref y \Cref se encargan de la palabra y del plural

cleveref sube el renvío un peldaño. \cref{key} antepone la palabra que corresponde al tipo del destino (abreviada por defecto —“fig. 1”— o “figure 1” con la opción noabbrev), y \Cref{key} la capitaliza para poder abrir una frase. Su verdadera fuerza son las listas y los rangos: pase las etiquetas separadas por comas sin espacios —\cref{fig:a,fig:b,fig:c}— y los números se ordenan y se unen, poniendo la palabra en plural por el camino, para dar algo como “figs. 1, 2 and 4”. Mejor aún: una serie consecutiva se pliega sola en un rango, así que esos tres salen como “figs. 1 to 3”. \crefrange{first}{last} consigue esa misma contracción nombrando solo los dos extremos.

La palabra antepuesta se redefine con \crefname{type}{singular}{plural} (\Crefname para la forma capitalizada). Así se localiza también: \crefname{figure}{figura}{figuras}. Para capitalizar en todo el documento, se carga el paquete con la opción capitalise. A la inversa, allí donde solo se quiere el número sin palabra alguna —entre paréntesis, en una celda de tabla—, \labelcref{key} entrega exactamente lo mismo que un \ref corriente.

Sobre el orden de carga hay una regla absoluta: cleveref va después de hyperref, varioref y amsmath; comprueba los tres. cleveref construye sus comandos detectando lo que hyperref ha definido, así que al revés sencillamente no puede funcionar. Por fortuna no falla en silencio: el cleveref.sty que trae TeX Live 2024 comprueba el orden en \begin{document} y se detiene con el mensaje de abajo. La combinación con varioref es otro asunto: el manual de cleveref prescribe el orden varioref → hyperref → cleveref y advierte de que equivocarse puede hacer que las referencias apunten a algo completamente distinto, sin advertencia ni en la salida ni en el registro.

\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: “en la página siguiente” en lugar de un número desnudo

En un documento encuadernado, “la figura 3 en la página siguiente” se lee mejor que un mecánico “la figura 3 en la página 12”, y “en la página enfrentada” aún mejor cuando ambas ocupan la misma apertura. \vref{key} de varioref imprime el mismo número que \ref y luego mira dónde caen el renvío y su destino uno respecto del otro, añadiendo la fórmula que corresponde. Si comparten página, no añade nada. Cuando solo interesa la indicación de página, \vpageref{key} hace justo eso, y sus dos argumentos opcionales fijan la fórmula para el caso de la misma página y la entradilla para el de otra página.

Esa inteligencia tiene un precio. Lo que imprime \vref depende del resultado de la composición —en qué página cayó cada cosa— y la longitud de lo impreso puede a su vez desplazar un salto de página, de modo que a veces hace falta una compilación adicional para que los valores se asienten. Un registro que repite “Rerun to get cross-references right” suele deberse a esto. Cargado junto a cleveref, \vref se compone con el formato de cleveref: si se usan ambos, respete el orden (varioref → hyperref → cleveref) y alinee todo el documento con la familia \cref; habrá menos que vigilar.

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

Ante la duda, la respuesta práctica es alinear todo el documento con cleveref. Se encarga por sí solo de la palabra del tipo, del plural, de los renvíos múltiples y de los rangos, lo que vuelve estructuralmente imposible el desliz clásico: escribir Figure~\ref{tab:...} cuando el destino es una tabla. \ref y \pageref siguen siendo imprescindibles para entender la mecánica; \eqref conserva su lugar en matemáticas y \vref en la obra encuadernada. La tabla siguiente resume qué imprime cada uno.