Lesezeichen und Metadaten

Nehmen Sie ein LaTeX-Dokument, das hyperref lädt, löschen Sie die Hilfsdateien und übersetzen Sie genau einmal. Das entstandene PDF enthält überhaupt keine Lesezeichen – die Gliederung erscheint erst im zweiten Durchlauf. Der Grund liegt in der Bauweise: hyperref schreibt die Überschriften in eine Nebendatei namens jobname.out und liest sie zu Beginn des nächsten Laufs wieder ein, bevor irgendetwas ins PDF gelangt. Diese Seite verfolgt diesen Mechanismus, dann das Paket bookmark, das die .out-Datei ganz wegwirft und schon im ersten Lauf richtig liegt, die PDF-Metadaten via \hypersetup, den neueren Einstiegspunkt \DocumentMetadata sowie den Zeichensalat, der japanische Lesezeichen ruiniert – jede Aussage belegt durch echte pdfinfo-Ausgaben.

hyperref erzeugt die Lesezeichen aus den Überschriften

Ein \usepackage{hyperref} genügt, damit aus \chapter, \section und \subsection eine PDF-Gliederung wird. Konfiguriert wird über Paketoptionen oder \hypersetup{}, und vier Schlüssel decken das meiste ab: bookmarks (standardmäßig an), bookmarksnumbered (Abschnittsnummern in die Lesezeichen übernehmen), bookmarksopen (aufgeklappt starten) und bookmarksopenlevel=N (bis zu welcher Tiefe). Öffnet man die Zwischendatei jobname.out, findet man eine Folge von LaTeX-Makroaufrufen – und die Zeichenketten stehen nicht im Klartext, sondern in UTF-16BE, sodass selbst eine englische Überschrift als \376\377\000C\000o\000v\000e\000r erscheint, mit einem \000 vor jedem Zeichen. Das führende \376\377 ist die UTF-16-Bytereihenfolgemarke, denn so definiert PDF seine Textzeichenketten.

\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

Die voreingestellte Tiefe stammt nicht vom Lesezeichenmechanismus, sondern vom Inhaltsverzeichnis. Die Klasse report setzt tocdepth auf 2 (bis subsection), also erreicht ein \subsubsection die Gliederung nie. Das ist Absicht: Beide Listen sollen dieselbe Körnung haben. Sollen die Lesezeichen tiefer reichen als das Verzeichnis, hilft bookmarksdepth – gemessen brachte bookmarksdepth=4 einen \subsubsection in die Gliederung, während er dem Inhaltsverzeichnis fernblieb. Umgekehrt klappt bookmarksdepth=1 die Gliederung bis auf die Abschnittsebene zusammen.

Ein Lesezeichen ohne Überschrift setzen: \pdfbookmark

Für Stellen, die keinen Gliederungsbefehl durchlaufen – Deckblatt, Inhaltsverzeichnis, unnummeriertes Vorwort –, schreibt man direkt \pdfbookmark[level]{sichtbarer Text}{anchor}. Die Ebene im ersten Argument ist eine Zahl (\chapter ist 0, \section ist 1), und der Anker im dritten muss im Dokument eindeutig sein, sonst kollidieren die Sprungziele. Für einen Eintrag auf der aktuellen Ebene gibt es \currentpdfbookmark{Text}{anchor}, eine Ebene tiefer \belowpdfbookmark{Text}{anchor}. Der häufigste praktische Fall ist ein Lesezeichen für das Inhaltsverzeichnis selbst: eine Zeile vor \tableofcontents. Ohne sie entsteht jenes eigentümliche PDF, in dem man überallhin springen kann, nur nicht zurück zum Verzeichnis.

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

Das Paket bookmark: die .out-Datei wegwerfen und im ersten Lauf richtig liegen

Lädt man Heiko Oberdieks Paket bookmark nach hyperref (TeX Live 2024 liefert v1.31 vom 10.12.2023), wird der gesamte Lesezeichenmechanismus ersetzt. Die Wirkung zeigt sich sofort in der Messung: Mit bloßem hyperref enthält das PDF des ersten Laufs aus einem leeren Verzeichnis überhaupt kein /Outlines-Objekt, erst der zweite Lauf trägt die sieben Einträge. Mit bookmark sind schon im ersten Lauf alle sieben da. Der Kniff ist einfach: bookmark schreibt keine .out-Datei (nachprüfbar – im Verzeichnis erscheint keine). Es führt die Gliederung stattdessen über die .aux-Datei, wodurch der Schritt mit der veralteten Nebendatei entfällt. Die Lesezeichen von hyperref schalten sich selbst ab, ein Konflikt entsteht also nicht.

Der zweite Gewinn ist die Gestaltung. \bookmarksetup{} nimmt numbered (Abschnittsnummern einbeziehen), open und openlevel sowie das Aussehen einzelner Einträge entgegen: color=blue, bold, italic. Ein Blick ins erzeugte PDF zeigt, dass jeder Gliederungseintrag tatsächlich einen Farbeintrag /C [ … ] trägt. Um nur einen einzelnen Eintrag zu ändern, setzt man unmittelbar davor \bookmarksetupnext{color=red}. Färbt man in einem langen Bericht allein Anhänge und Register ein, wird die Seitenleiste auf einen Blick lesbar.

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

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

PDF-Metadaten: Titel und Autor mit \hypersetup angeben

Was der Viewer unter „Dokumenteigenschaften“ zeigt, bestimmen vier Schlüssel in \hypersetup{}: pdftitle, pdfauthor, pdfsubject und pdfkeywords. Sie werden nicht aus \title und \author übernommen, man muss also beides schreiben – hyperref braucht die Werte, bevor \maketitle läuft. Ob es geklappt hat, verrät ein einziger pdfinfo-Aufruf. Die Felder pdfcreator und pdfproducer benennen die erzeugende Software und werden normalerweise automatisch gefüllt: pdfLaTeX mit hyperref meldet Creator: LaTeX with hyperref und Producer: pdfTeX-1.40.26. Beide lassen sich überschreiben, doch damit verschwindet die einzige Spur, wie die Datei entstanden ist – besser unangetastet lassen.

\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

Akzentbuchstaben lassen sich heute unverändert eintragen. Das mit TeX Live 2024 ausgelieferte hyperref 7.01h setzt intern \Hy@unicodetrue als Voreinstellung, sodass pdftitle={Théorie des catégories — Übersicht} selbst unter pdfLaTeX unversehrt aus pdfinfo zurückkommt; die früher nötige Option unicode erübrigt sich. Was weiterhin beißt: Die Werte von \hypersetup wandern unverändert als Zeichenketten ins PDF, weshalb die praktische Regel lautet, keine Makros hineinzuschreiben. pdftitle={\LaTeX{} in der Praxis} lädt zu einem Expansionsfehler ein, während ein schlichtes pdftitle={LaTeX in der Praxis} immer funktioniert.

\DocumentMetadata: der neue Einstieg für Metadaten und Tagging

\DocumentMetadata{…} ist eine neuere Deklaration des LaTeX-Kerns und steht vor \documentclass. In TeX Live 2024 funktioniert sie tatsächlich und nimmt Schlüssel wie lang=en-GB (die Dokumentsprache), pdfversion=2.0, pdfstandard=A-2B (die PDF/A-Stufe, von A-1B bis A-4) und uncompress (alle Komprimierung abschalten) entgegen. Schon eine einzige Zeile zeigt Wirkung: In pdfinfo springt Metadata Stream von no auf yes, weil das PDF nun einen XMP-Metadatenstrom trägt. Die vorhandenen \hypersetup-Schlüssel arbeiten daneben weiter, und beide Wertsätze landen nachweislich im PDF.

Dahinter steht das getaggte PDF. Ergänzt man testphase={phase-III} und lässt pdflatex zweimal laufen, meldet pdfinfo Tagged: yes – LaTeX schreibt nun die Struktur von Absätzen und Überschriften in den Strukturbaum des PDF. Wie der Schlüsselname sagt, ist das noch eine Testphase und nichts, was man in einer endgültigen Einreichung bedenkenlos einschaltet; bemerkenswert bleibt, dass eine funktionierende Fassung bereits im normalen TeX Live steckt. Zu beachten ist außerdem eine Nebenwirkung auf das Papierformat: Prüfen Sie beim Nachrüsten eines bestehenden Dokuments die Maße des PDF – Einzelheiten stehen unter „PDF erzeugen und steuern“.

\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

Wenn japanische Lesezeichen zu Zeichensalat werden: pxjahyper und die Option dvipdfmx

Damit japanische Lesezeichen mit upLaTeX und dvipdfmx stimmen, braucht es zwei getrennte Eingriffe. Der erste besteht darin, hyperref mitzuteilen, für welchen Treiber es schreibt. Bei bloßem \usepackage{hyperref} meldet das Log Package hyperref Info: Driver (default): hdvips. – erzeugt wird DVI, doch hyperref schreibt \specials für dvips. Gibt man dieses DVI an dvipdfmx, folgt eine Reihe von dvipdfmx:warning: Unknown token "SDict" und Interpreting special command ps: (ps:) failed., und heraus kommt ein PDF ganz ohne Lesezeichen und ohne Verweise. Mit \usepackage[dvipdfmx]{hyperref} steht im Log Driver: hdvipdfm. und es bleibt bei null Warnungen.

Der zweite Eingriff betrifft die Zeichenkodierung. Mit korrigiertem Treiber erscheint die Gliederung wieder, doch eine japanische Überschrift kommt als etwas wie æ鞥æ鲬èꪞã膮èꚋå螺ã膗 an. Die .out-Datei zeigt den Grund: 日 sollte in UTF-16BE zu den zwei Bytes \145\345 werden, stattdessen werden seine drei UTF-8-Bytes je als eigenes Zeichen behandelt und zu \000\346\000\227\000\245 aufgebläht. Ergänzt man \usepackage{pxjahyper} (von Takayuki Yato; TeX Live 2024 liefert v1.3), wird die .out zu korrektem UTF-16BE – \376\377\145\345\147\054\212\236… –, und pdfinfo meldet ein lesbares Title: 日本語のタイトル. Entscheidend: Das repariert pdftitle und pdfauthor gleich mit, nicht nur die Lesezeichen.

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

Dieses zweistufige Verfahren braucht nur die DVI-Route von (u)pLaTeX. LuaLaTeX mit LuaTeX-ja kommt mit einem schlichten \usepackage{hyperref} ans Ziel – im Log steht Driver (autodetected): hluatex., und die .out-Datei ist von Anfang an korrektes UTF-16BE. XeLaTeX mit xeCJK liefert ebenso lesbare Lesezeichen ohne zusätzliches Paket. Wer sich mit Zeichensalat in japanischen Lesezeichen dauernd herumschlägt, findet im Wechsel der Engine oft den kürzesten Ausweg. Eine Anmerkung zur Reihenfolge: hyperref gehört möglichst weit nach hinten, doch cleveref muss nach hyperref kommen; andernfalls bricht der Lauf mit ! Package cleveref Error: cleveref must be loaded after hyperref!. ab. Kommt varioref hinzu, lautet die Folge hyperref, varioref, cleveref.