Marcadores y metadatos

Tome un documento LaTeX que cargue hyperref, borre los archivos auxiliares y compile exactamente una vez. El PDF resultante no contiene ningún marcador: el esquema aparece solo en la segunda pasada. La razón está en cómo se construyen los marcadores: hyperref escribe los títulos en un archivo lateral llamado jobname.out y lo vuelve a leer al comienzo de la ejecución siguiente, antes de poner nada en el PDF. Esta página recorre ese mecanismo y luego el paquete bookmark, que tira el archivo .out y acierta ya en la primera pasada; los metadatos PDF que se fijan con \hypersetup; el punto de entrada más reciente \DocumentMetadata; y el galimatías que arruina los marcadores japoneses, con cada afirmación comprobada sobre una salida real de pdfinfo.

hyperref construye los marcadores a partir de los títulos

Basta con escribir \usepackage{hyperref} para que \chapter, \section y \subsection se conviertan en un esquema del PDF. Se configura con opciones de paquete o con \hypersetup{}, y cuatro claves cubren lo esencial: bookmarks (activa por defecto), bookmarksnumbered (llevar también los números de sección a los marcadores), bookmarksopen (empezar desplegado) y bookmarksopenlevel=N (hasta qué profundidad). Abra el archivo intermedio jobname.out y encontrará una serie de llamadas a macros de LaTeX, con las cadenas no en texto llano sino en UTF-16BE, de modo que hasta un título inglés aparece como \376\377\000C\000o\000v\000e\000r, con un \000 delante de cada carácter. El \376\377 inicial es la marca de orden de bytes de UTF-16, porque así define el PDF sus cadenas de texto.

\usepackage[bookmarksnumbered,bookmarksopen,bookmarksopenlevel=1]{hyperref}
% or set the same keys later
\hypersetup{bookmarksopenlevel=1}

% report.out after three passes — hyperref stores the outline here
\BOOKMARK [0][]{cover.0}{\376\377\000C\000o\000v\000e\000r}{}% 1
\BOOKMARK [0][]{chapter.1}{...1 Foundations...}{}% 2
\BOOKMARK [1][-]{section.1.1}{...1.1 First section...}{chapter.1}% 3
\BOOKMARK [2][-]{subsection.1.1.1}{...1.1.1 A subsection...}{section.1.1}% 4

La profundidad por defecto no viene del mecanismo de marcadores sino del índice. La clase report fija tocdepth en 2 (hasta subsection), así que un \subsubsection nunca llega al esquema. Es deliberado: ambas listas deben tener el mismo grano. Cuando quiera los marcadores más profundos que el índice, use bookmarksdepth: medido, añadir bookmarksdepth=4 hizo que un \subsubsection apareciera en el esquema mientras seguía fuera del índice. A la inversa, bookmarksdepth=1 repliega el esquema hasta las secciones.

Poner un marcador donde no hay título: \pdfbookmark

Para los lugares que no pasan por ninguna orden de seccionado —portada, índice, prefacio sin numerar— escriba directamente \pdfbookmark[level]{texto visible}{anchor}. El nivel del primer argumento es un número (\chapter es 0, \section es 1) y el ancla del tercero debe ser única dentro del documento o los destinos chocan. Para añadir una entrada al nivel actual está \currentpdfbookmark{texto}{anchor}, y un nivel más abajo \belowpdfbookmark{texto}{anchor}. El uso más frecuente es marcar el propio índice: una línea antes de \tableofcontents. Sin ella se entrega ese PDF peculiar en el que el lector puede saltar a cualquier parte menos de vuelta al índice.

\begin{document}
\pdfbookmark[0]{Cover}{cover}      % level 0, same rank as \chapter
\maketitle
\clearpage
\pdfbookmark[1]{Contents}{toc}     % the classic missing bookmark
\tableofcontents
\chapter{Foundations}

El paquete bookmark: tirar el archivo .out y acertar en una pasada

Cargue el paquete bookmark de Heiko Oberdiek después de hyperref (TeX Live 2024 trae la v1.31, de 2023-12-10) y todo el mecanismo de marcadores queda sustituido. La medición lo muestra al instante: con hyperref a secas, el PDF de la primera pasada desde un directorio limpio no contiene objeto /Outlines alguno, y solo la segunda pasada trae las siete entradas. Con bookmark, las siete están ya en la primera pasada. El truco es simple: bookmark no escribe archivo .out (compruébelo: no aparece ninguno en el directorio). Hace pasar el esquema por el archivo .aux, con lo que desaparece el paso del archivo lateral caducado. Los marcadores propios de hyperref se desactivan solos, así que nada choca.

La segunda ganancia es el aspecto. \bookmarksetup{} admite numbered (incluir los números de sección), open y openlevel, y el estilo entrada por entrada: color=blue, bold, italic. Mire dentro del PDF generado y cada elemento del esquema lleva realmente una entrada de color /C [ … ]. Para cambiar solo una entrada, ponga justo antes \bookmarksetupnext{color=red}. En un informe largo, colorear solo los apéndices y el índice hace la barra lateral mucho más legible de un vistazo.

\usepackage{hyperref}
\usepackage{bookmark}      % must come after hyperref
\bookmarksetup{numbered, open, openlevel=1, color=blue}

% one entry only
\bookmarksetupnext{color=red, bold}
\chapter{Appendix}

Metadatos PDF: declarar título y autor con \hypersetup

Lo que el visor muestra en «Propiedades del documento» lo deciden cuatro claves de \hypersetup{}: pdftitle, pdfauthor, pdfsubject y pdfkeywords. No se copian de \title ni de \author, así que hay que escribir ambos: hyperref necesita los valores antes de que se ejecute \maketitle. Una sola llamada a pdfinfo dice si funcionó. Los campos pdfcreator y pdfproducer identifican el software productor y suelen rellenarse solos: pdfLaTeX con hyperref informa Creator: LaTeX with hyperref y Producer: pdfTeX-1.40.26. Se pueden sobrescribir, pero eso borra el único rastro de cómo se hizo el archivo, así que es más prudente dejarlos.

\usepackage{hyperref}
\hypersetup{
  pdftitle={Measured Bookmarks},
  pdfauthor={Ada Lovelace},
  pdfsubject={PDF navigation},
  pdfkeywords={LaTeX, hyperref, bookmarks}
}

$ pdfinfo report.pdf
Title:           Measured Bookmarks
Subject:         PDF navigation
Keywords:        LaTeX, hyperref, bookmarks
Author:          Ada Lovelace
Creator:         LaTeX with hyperref
Producer:        pdfTeX-1.40.26
Pages:           5
Page size:       595.276 x 841.89 pts (A4)
PDF version:     1.5

Los caracteres acentuados ya se escriben tal cual. La versión 7.01h de hyperref, incluida en TeX Live 2024, activa internamente \Hy@unicodetrue por defecto, así que pdftitle={Théorie des catégories — Übersicht} sale intacto de pdfinfo incluso bajo pdfLaTeX; la opción unicode que antes hacía falta ya no es necesaria. Lo que sí sigue mordiendo es que los valores de \hypersetup se escriben tal cual como cadenas en el PDF, de modo que la regla práctica es no meter macros dentro: pdftitle={Usar \LaTeX{}} invita a un fallo de expansión, mientras que un simple pdftitle={Usar LaTeX} funciona siempre.

\DocumentMetadata: la nueva entrada para metadatos y etiquetado

\DocumentMetadata{…} es una declaración más reciente del núcleo de LaTeX que va antes de \documentclass. Funciona de verdad en TeX Live 2024 y admite claves como lang=en-GB (el idioma del documento), pdfversion=2.0, pdfstandard=A-2B (el nivel PDF/A, de A-1B a A-4) y uncompress (desactivar toda compresión). Una sola línea ya tiene efecto visible: en pdfinfo, Metadata Stream pasa de no a yes, porque el PDF lleva ahora un flujo de metadatos XMP. Las claves \hypersetup existentes siguen funcionando junto a ella, y ambos juegos de valores acaban correctamente en el PDF.

Más allá está el PDF etiquetado. Añada testphase={phase-III}, ejecute pdflatex dos veces y pdfinfo informará Tagged: yes: LaTeX ha empezado a escribir la estructura de párrafos y títulos en el árbol de estructura del PDF. Como indica el nombre de la clave, sigue siendo una fase de prueba y no algo que activar sin más en una versión final para entregar; pero conviene saber que una versión funcional viene ya en el TeX Live estándar. Tenga en cuenta además que \DocumentMetadata tiene un efecto colateral sobre el tamaño del papel, así que compruebe las dimensiones del PDF al añadirlo a un documento existente; los detalles están en «Generar y controlar el PDF».

\DocumentMetadata{pdfversion=2.0, lang=en-GB, testphase={phase-III}}
\documentclass{article}
\usepackage{hyperref}
\hypersetup{pdftitle={Tagged Test}, pdfauthor={Ada Lovelace}}
% pdfinfo then reports: Tagged: yes / Metadata Stream: yes / PDF version: 2.0

Cuando los marcadores japoneses se vuelven ilegibles: pxjahyper y la opción dvipdfmx

Conseguir marcadores japoneses correctos con upLaTeX y dvipdfmx exige dos arreglos distintos. El primero es decirle a hyperref para qué controlador está escribiendo. Con un simple \usepackage{hyperref}, el registro dice Package hyperref Info: Driver (default): hdvips.: se está produciendo DVI, pero hyperref emite \special dirigidos a dvips. Pase ese DVI a dvipdfmx y aparecerá una ristra de dvipdfmx:warning: Unknown token "SDict" y Interpreting special command ps: (ps:) failed., y un PDF sin marcador ni enlace alguno. Escriba en su lugar \usepackage[dvipdfmx]{hyperref} y el registro dirá Driver: hdvipdfm. sin una sola advertencia.

El segundo arreglo es la codificación de caracteres. Con el controlador corregido el esquema vuelve, pero un título japonés llega como æ鞥æ鲬èꪞã膮èꚋå螺ã膗. El archivo .out explica por qué: 日 debería convertirse en los dos bytes \145\345 en UTF-16BE, pero sus tres bytes UTF-8 se tratan cada uno como carácter aparte y se inflan a \000\346\000\227\000\245. Añada \usepackage{pxjahyper} (de Takayuki Yato; TeX Live 2024 trae la v1.3) y el .out pasa a ser UTF-16BE correcto —\376\377\145\345\147\054\212\236…— mientras pdfinfo informa un Title: 日本語のタイトル legible. Lo decisivo: eso repara pdftitle y pdfauthor a la vez que los marcadores.

% upLaTeX -> dvipdfmx: both lines are needed
\documentclass{ujarticle}
\usepackage[dvipdfmx]{hyperref}   % without this: dvipdfmx warning, no outline
\usepackage{pxjahyper}            % without this: mojibake in the outline
\hypersetup{pdftitle={...}, pdfauthor={...}}

Este doble arreglo solo hace falta en la ruta DVI de (u)pLaTeX. LuaLaTeX con LuaTeX-ja llega con un simple \usepackage{hyperref}: el registro dice Driver (autodetected): hluatex. y el archivo .out es UTF-16BE correcto desde el principio. XeLaTeX con xeCJK produce igualmente marcadores legibles sin paquete extra. Si los marcadores japoneses ilegibles le persiguen, cambiar de motor suele ser la salida más corta. Una nota sobre el orden: hyperref se carga lo más tarde posible, pero cleveref debe ir después de hyperref, y hacerlo al revés detiene la compilación con ! Package cleveref Error: cleveref must be loaded after hyperref!. Si además interviene varioref, el orden es hyperref, luego varioref, luego cleveref.