hyperref Wiki .:. goLaTeX - Mein LaTeX-Forum


goLaTeX - Mein LaTeX-Forum

Mein LaTeX-Forum

goLaTeX.de - Wiki
 


hyperref

hyperref ist ein Paket zur automatischen und manuellen Erstellung von dynamischen Querverweisen in Dokumenten. Dabei werden viele unterschiedliche Möglichkeiten der PDF-Ausgabe, der PostScript-Ausgabe und der DVI-Ausgabe (beispielsweise HyperTeX-Erweiterung) sowie der HTML-Ausgabe (VTeX) unterstützt.

Inhaltsverzeichnis

[bearbeiten] Vorabbemerkung

Das Paket hyperref befindet sich unter ständiger Weiterentwicklung. Maintainter des Pakets ist Heiko Oberdiek. Während dieser Artikel entsteht, ist Version 6.81e aktuell. Bis Sie diesen Artikel lesen, sind eventuell schon wieder mehrere neuere Versionen erschienen. Da jedoch in der Regel die Kompatibilität erhalten bleibt und nur lediglich Bugs beseitigt und neue Möglichkeiten eingebaut werden, bleibt die Grundfunktionalität, auf die sich dieser Artikel in erster Linie bezieht, erhalten. Dennoch sollten Sie darauf achten, die hyperref-Version zu verwenden, die aktuell über den Paketmanager Ihres TeX-Systems angeboten wird. Beachten Sie auch immer die Anleitung zu der von Ihnen verwendeten hyperref-Version. Diese besteht in der Regel nicht nur aus dem Manual, sondern auch aus weiteren Dateien. Sehr wichtig ist in diesem Fall auch das README.

[bearbeiten] Besonderheiten und bekannte Probleme

  • Da TeX selbst ursprünglich keine aktiven Links kennt, können diese nur über Spracherweiterungen realisiert werden. Bei DVI-Ausgabe oder PDF-Ausgabe mit XeTeX erfolgt dies über das Einfügen entsprechender \special-Anweisungen. Dabei sind diese \special-Anweisungen nicht für alle DVI-Treiber gleich. Bei PDF-Ausgabe mit pdfTeX, luaTeX und bei PDF- oder HTML-Ausgabe mit VTeX erfolgt dies hingegen mit Hilfe neuer TeX-Primitiven. Damit ist das Erstellen solcher Links in extremer Weise von der Verarbeitungslinie abhängig. Um nun Dokumente erstellen zu können, die unabhängig von der Verarbeitunglinie sind, fügt das Paket hyperref eine zusätzliche Anwenderschicht ein. Die Wahl der tatsächlich zu verwenden Anweisungen, die sich darunter verbergen, erfolgt über die Wahl eines Treibers. Dieser Treiber kann als Option beim Laden von hyperref (oder als globale Option bei \documentclass) angegeben werden. Gleichzeitig ermittelt hyperref selbst, ob beispielsweise XeTeX oder ein pdfTeX/luaTeX im PDF-Ausgabemodus oder ein VTeX im PDF- oder HTML-Ausgabemodus verwendet wird. In diesen Fällen wählt hyperref automatisch den entsprechenden Treiber. Wurde ein Treiber manuell angegeben, der im Widerspruch dazu steht, wird außerdem eine Warnung ausgegeben. Eine solche Warnung wird auch ausgegeben, wenn manuell ein Treiber für einen der genannten Modi angegeben wurde, aber ein TeX im DVI-Modus verwendet wird. In diesem Fall wird auch automatisch der sogenannte Fallback- oder Default-Treiber verwendet. Dieser wird auch verwendet, wenn TeX im DVI-Modus verwendet wird und kein Treiber per Option vorgegeben wurde. Daraus ergibt sich, dass es nur dann sinnvoll ist manuell einen Treiber per Option anzugeben, wenn TeX im DVI-Modus mit einem anderen DVI-Treiber als dem Fallback-Treiber verwendet werden soll. Der in hyperref.sty voreingestellte Fallback-Treiber ist hypertex. Der Fallback-Treiber kann jedoch auch per hyperref.cfg anders voreingestellt werden. Bei aktuellen LaTeX-Distributionen wird eine systemweite hyperref.cfg mitgeliefert, die den Fallback-Treiber per
    \providecommand*{\Hy@defaultdriver}{hdvips}
    auf den Treiber für dvips ändert.
  • Da hyperref diverse LaTeX-Kern-Makros und auch Makros anderer Pakete umdefinieren muss, sollte hyperref in der Regel möglichst spät geladen werden. In der Anleitungsdatei README.pdf von hyperref sind jedoch Ausnahmen für diese Regel genannt. Ggf. sind auch die Anleitungen der verwendeten Paket auf entsprechende Hinweise zu prüfen.
  • hyperref verlinkt bei \ref und \pageref immer auf den letzten gültigen Anker, der vor dem zugehörigen \label gesetzt wurde. Anker in bereits geschlossenen Gruppen sind nicht mehr gültig. Automatisch setzt hyperref Anker bei \refstepcounter und einigen wenigen zusätzlichen Befehlen wie den Sternversionen der Standard-Gliederungsbefehle. \label selbst fügt keinen Anker ein. hyperref bietet jedoch mit \phantomsection die Möglichkeit explizit einen Anker vom Typ section* zu setzen.
  • hyperref setzt bei \addcontentsline und \addtocontents ebenfalls nicht automatisch einen Anker, sondern verwendet für die Verzeichniseinträge denselben Anker, der auch bei \ref oder \pageref verwendet würde. Ggf. kann also auch hier mit \phantomsection vor \addcontentsline oder \addtocontents das Linkziel korrigiert werden.
  • Es bestehen Inkompatibilitäten zu einigen wenigen Paketen. Einige dieser Pakete sind in der README-Datei von hyperref genannt. Teilweise sind dort auch Lösungen oder Teillösungen für die Probleme zu finden. So sollte beispielsweise bei Verwendung des Paket varioref das zu hyperref gehörende Paket nameref vor varioref geladen werden während hyperref selbst nach varioref zu laden ist. Laut dem Autor von hyperref sind dadurch aber nicht alle Probleme mit varioref zu lösen. Die Zusammenarbeit mit cleveref kann mit Hilfe des Pakets hypdvips verbessert werden.
  • Bei Verwendung des Pakets pdfx sollte hyperref nicht selbst geladen werden, das dieses Paket hyperref selbst mit passenden Optionen lädt. Dabei werden allerdings alle Optionen von hyperref, zum Setzen von PDF-Katalog-Informationen deaktiviert. Stattdessen sind dann die Anweisungen des Paket pdfx zu verwenden.
  • Optionen mit textuellem Wert sollten grundsätzlich per \hypersetup und nicht etwa per \documentclass oder \usepackage gesetzt werden. Die korrekte Textcodierung ist abhängig vom jeweiligen Treiber und kann von hyperref nur zuverlässig angepasst werden, wenn der Text per \hypersetup übergeben wurde und nicht bereits von LaTeX selbst bei \documentclass oder \usepackage gelesen wurde.
  • Treiberabhängig sind ggf. keine Zeilenumbrüche innerhalb von Links möglich. Dies führt beispielsweise bei Verwendung des Treibers dvips dazu, dass in der Voreinstellung in den Verzeichnissen keine Zeilenumbrüche mehr funktionieren. Um das Problem in den Verzeichnissen zu beseitigen, kann man mit Hilfe der Option linktocpage die Seitenzahlen statt der Texteinträge verlinken. Für URLs bietet hingegen das Paket breakurl eine Lösung. Bei Verwendung des Treiber dvips bietet das Paket hypdvips Abhilfe. Mit den Treibern pdftex oder dvipdfmx tritt das Problem jedoch beispielsweise nicht auf.

[bearbeiten] Beispiele

Die folgenden Beispiele zeigen die Verwendung von hyperref.

[bearbeiten] Minimaldokument mit automatischen Links

Dieses Beispiel zeigt, wie man durch schlichte Verwendung des Pakets hyperref sein Dokument aufwerten kann, indem Querverweise und Verzeichnisse mit aktiven Links versehen werden. Auf die Verwendung erweiterter Einstellungen wird hier bewusst verzichtet.

\documentclass{report}
\usepackage[latin1]{inputenc}
\usepackage[ngerman]{babel}
 
\usepackage{hyperref}
 
\begin{document}
\tableofcontents
 
\chapter{Ein Kapitel}
\label{cha:beispiel}
 
\chapter{Ein weiteres Kapitel}
Siehe auch \autoref{cha:beispiel}.
 
\end{document}


[bearbeiten] Verwendung eines anderen Fallback-Treibers

Wie oben bereits erwähnt, verwendet hyperref im Fall der DVI-Ausgabe einen Fallback-Treiber, der entweder direkt in hyperref.sty oder über hyperref.cfg vorgegeben ist. Will man stattdessen einen anderen Fallback-Treiber vorschreiben, etwa weil man DVI-Dateien immer mit dvipdfmx weiterverarbeitet, so kann man diesen per Option driverfallback angeben:

\documentclass{report}
\usepackage[latin1]{inputenc}
\usepackage[ngerman]{babel}
 
\usepackage[driverfallback=dvipdfmx]{hyperref}
 
\begin{document}
\tableofcontents
 
\chapter{Ein Kapitel}
\label{cha:beispiel}
 
\chapter{Ein weiteres Kapitel}
Siehe auch \autoref{cha:beispiel}.
 
\end{document}

Gegenüber der direkten Verwendung der Option dvipdfmx hat dies den Vorteil, dass hyperref keine Warnung ausgibt, wenn es stattdessen die Notwendigkeit für die Verwendung eines anderen Treibers wie pdftex, xetex, vtex, vtexpdfmark oder textures erkennt und sich deshalb für einen dieser Treiber entscheidet. Dies ist also vor allem für Dokumente mit alternativen Verarbeitungsmöglichkeiten nützlich, die bei DVI-Ausgabe einen bestimmten Treiber verwenden sollen, aber bei automatischer Erkennung des korrekten Treibers den automatisch erkannten.


[bearbeiten] Verwendung von \phantomsection und setzen von Dokument-Infos

Dieses Beispiel zeigt die Verwendung von hyperref mit makeidx und \phantomsection. Siehe dazu auch hyperref-manual S. 13.

\documentclass[a4paper]{book}
 
\usepackage[latin1]{inputenc}% Die Seiten von goLaTeX.de verwenden diese Codierung!
 
\usepackage[ngerman]{babel}% Die Hauptsprache unseres Dokuments ist Deutsch!
\usepackage[T1]{fontenc}% Fonts in 8-Bit-Codierung verwenden.
\usepackage{lmodern}% Optimierte Standardschrift verwenden.
 
% Wir definieren einige Dinge nur einmal und verwenden sie dann mehrfach.
% Es sei darauf hingeweisen, dass man vergleichbares für Titel und Autor
% stattdessen auch mit Hilfe der hyperref-Option pdfusetitle (siehe README.pdf)
% erreichen kann.
\newcommand*\Title{LaTeX-hyperref-Paket}
\newcommand*\Subject{Beispieldatei}
\newcommand*\Author{diverse}
\newcommand*\Keywords{Dynamische Links, Postscript, PDF, hyperref, LaTeX}
 
% Wir wollen einen Index:
\usepackage{makeidx}\makeindex
 
% Wir wollen aktive Links und einige Dokumentinformationen:
\usepackage{hyperref}
\hypersetup{%
  pdftitle={\Title},
  pdfsubject={\Subject},
  pdfauthor={\Author},
  pdfkeywords={\Keywords}
}
% Falls in den Verzeichnissen nicht die Texteinträge, sondern die Seitenzahlen
% Links sein sollen (siehe Bemerkungen oben):
\hypersetup{linktocpage}
 
\begin{document}
 
\frontmatter
\title{\Title}
\author{\Author}
\maketitle   
 
\tableofcontents% Inhaltsverzeichnis
 
%%-------------------------------------------------------------------
\mainmatter
\chapter{Hallo Welt Kapitel}\label{ch:hallowelt}
\section{Erste Section}
\label{sec:level-1-first}
Etwas Text um des Textes willen. Das Beispiel ist \index{nicht zweisprachig} einsprachig . 
 
\subsection{Link zeigt auf die falsche Seite}
\label{sec:link-zeigt-auf}
Wenn mal ein Link auf die falsche Seite rutscht hilft oft ein 
\index{cleardoublepage@\texttt{\textbackslash cleardoublepage}}\texttt{\textbackslash cleardoublepage}\footnote{%
\texttt{\textbackslash cleardoublepage} tut immer das Richtige, da
es im Falles eines einseitigen Dokumentes oder im Fall von \texttt{openany} genau wie
\texttt{\textbackslash clearpage} funktioniert.} 
kombiniert mit \index{phantomsection@\texttt{\textbackslash phantomsection}}\texttt{\textbackslash phantomsection}.
 
\subsection{Unterüberschrift}
\label{sec:level-2-first} 
Irgend ein Text.
 
\section{Eine Unterüberschrift}
\label{sec:level-1-second}
Weiterer \index{hilfreicher Text} hilfreicher Text.
 
\subsection{Wieder eine Überschrift}
\label{sec:level-2-second}
Noch ein paar Worte.
 
\appendix
\chapter{Eine Verlinkung}
Zum Kapitelanfang von \autoref{ch:hallowelt} auf Seite \pageref{ch:hallowelt}.
Zum \hyperref[ch:hallowelt]{Kapitelanfang von \autoref*{ch:hallowelt} auf Seite \pageref*{ch:hallowelt}}.
 
\cleardoublepage
\phantomsection% Anker für den Link des folgenden Inhaltsverzeichniseintrags
\addcontentsline{toc}{chapter}{\indexname}
\printindex
\end{document}

Es sei an dieser Stelle darauf hingewiesen, dass man den Index einschließlich eines Eintrags in das Inhaltsverzeichnis auch sehr einfach mit entsprechenden Klassen (beispielsweise KOMA-Script) oder Paketen (beispielsweise idxlayout) realisieren kann.

[bearbeiten] Links




Impressum | FAQ | goLaTeX RSS Button RSS-Feed

Copyright © 2008 - 2015 goLaTeX.de