The package derives from, and builds on, the work of the HyperTEX project, described at http://xxx.lanl.gov/hypertex/. It extends the functionality of all the LATEX cross-referencing commands (including the table of contents, bibliographies etc) to produce \special commands which a driver can turn into hypertext links; it also provides new commands to allow the user to write ad hoc hypertext links, including those to external documents and URLs.
This manual provides a brief overview of the hyperref package. For more details, you should read the additional documentation distributed with the package, as well as the complete documentation by processing hyperref.dtx. You should also read the chapter on hyperref in The LATEX Web Companion, where you will find additional examples.
The HyperTEX specification1 says that conformant viewers/translators must recognize the following set of \special constructs:
The href, name and end commands are used to do the basic hypertext operations of establishing links between sections of documents. The image command is intended (as with current HTML viewers) to place an image of arbitrary graphical format on the page in the current location. The base_name command is be used to communicate to the DVI viewer the full (URL) location of the current document so that files specified by relative URL’s may be retrieved correctly.
The href and name commands must be paired with an end command later in the TEX file—the TEX commands between the two ends of a pair form an anchor in the document. In the case of an href command, the anchor is to be highlighted in the DVI viewer, and when clicked on will cause the scene to shift to the destination specified by href_string. The anchor associated with a name command represents a possible location to which other hypertext links may refer, either as local references (of the form href="#name_string" with the name_string identical to the one in the name command) or as part of a URL (of the form URL#name_string). Here href_string is a valid URL or local identifier, while name_string could be any string at all: the only caveat is that ‘"’ characters should be escaped with a backslash (n), and if it looks like a URL name it may cause problems.
However, the drivers intended to produce only PDF use literal PostScript or PDF \special commands. The commands are defined in configuration files for different drivers, selected by package options; at present, the following drivers are supported:
Output from dvips or dvipsone must be processed using Acrobat Distiller to obtain a PDF file.2 The result is generally preferable to that produced by using the hypertex driver, and then processing with dvips -z, but the DVI file is not portable. The main advantage of using the HyperTEX \special commands is that you can also use the document in hypertext DVI viewers, such as xdvi.
This package can be used with more or less any normal LATEX document by specifying in the document preamble
\usepackage{hyperref}
|
Make sure it comes last of your loaded packages, to give it a fighting chance of not being over-written, since its job is to redefine many LATEX commands. Hopefully you will find that all cross-references work correctly as hypertext. For example, \section commands will produce a bookmark and a link, whereas \section* commands will only show links when paired with a corresponding \addcontentsline command.
In addition, the hyperindex option (see below) attempts to make items in the index by hyperlinked back to the text, and the option backref inserts extra ‘back’ links into the bibliography for each entry. Other options control the appearance of links, and give extra control over PDF output. For example, colorlinks, as its name well implies, colors the links instead of using boxes; this is the option used in this document.
All user-configurable aspects of hyperref are set using a single ‘key=value’ scheme (using the keyval package) with the key Hyp. The options can be set either in the optional argument to the \usepackage command, or using the \hypersetup macro. When the package is loaded, a file hyperref.cfg is read if it can be found, and this is a convenient place to set options on a site-wide basis.
As an example, the behavior of a particular file could be controlled by:
\hypersetup{backref,
pdfpagemode=FullScreen, colorlinks=true} |
\documentclass[dvips]{article}
|
\usepackage[pdftitle={A Perfect Day},colorlinks=false]{hyperref}
|
Some options can be given at any time, but many are restricted: before \begin{document}, only in \usepackage[...]{hyperref}, before first use, etc.
In the key descriptions that follow, many options do not need a value, as they default to the value true if used. These are the ones classed as ‘boolean’. The values true and false can always be specified, however.
Firstly, the options to specify general behavior and page size.
draft | boolean | false | all hypertext options are turned off |
final | boolean | true | all hypertext options are turned on |
debug | boolean | false | extra diagnostic messages are printed in |
the log file | |||
verbose | boolean | false | same as debug |
implicit | boolean | true | redefines LATEX internals |
hypertexnames | boolean | true | use guessable names for links |
naturalnames | boolean | false | use LATEX-computed names for links |
a4paper | boolean | true | sets paper size to 210mm |