Contents

1 Introduction

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 specification¹ says that conformant viewers/translators must recognize the following set of \special constructs:

href:

html:<a href = "href_string">

name:

html:<a name = "name_string">

end:

html:</a>

image:

html:<img src = "href_string">

base_name:

html:<base href = "href_string">

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 (\), 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:

hypertex

DVI processors conforming to the HyperTEX guidelines (i.e. xdvi, dvips (with the -z option), OzTeX, and Textures)

dvips

produces \special commands tailored for dvips

dvipsone

produces \special commands tailored for dvipsone

ps2pdf

a special case of output suitable for processing by earlier versions of Ghostscript’s PDF writer; this is basically the same as that for dvips, but a few variations remained before version 5.21

tex4ht

produces \special commands for use with TEX4ht

pdftex

pdfTEX, Hàn Thê' Thành’s TEX variant that writes PDF directly

dvipdf

produces \special commands for the DVI to PDF driver dvipdf

dvipdfm

produces \special commands for Mark Wicks’ DVI to PDF driver dvipdfm

dviwindo

produces \special commands that Y&Y’s Windows previewer interprets as hypertext jumps within the previewer

vtex

produces \special commands that MicroPress’ HTML and PDF-producing TEX variants interpret as hypertext jumps within the previewer

textures

produces \special commands that Textures interprets as hypertext jumps within the previewer

Output from dvips or dvipsone must be processed using Acrobat Distiller to obtain a PDF file.² 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.

2 Implicit behavior

This package can be used with more or less any normal LATEX document by specifying in the document preamble

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.

3 Package options

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:

• a site-wide hyperref.cfg setting up the look of links, adding backreferencing, and setting a PDF display default:

  \hypersetup{backref,   pdfpagemode=FullScreen,   colorlinks=true}

• A global option in the file, which is passed down to hyperref:

  \documentclass[dvips]{article}

• File-specific options in the \usepackage commands, which override the ones set in hyperref.cfg:

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

3.1 General options

Firstly, the options to specify general behavior and page size.

3.2 Configuration options

3.3 Backend drivers

If no driver is specified, the package defaults to loading the hypertex driver. All of these are boolean options.

If you use dviwindo, you may need to redefine the macro \wwwbrowser (the default is C:\netscape\netscape) to tell dviwindo what program to launch. Thus, users of Internet Explorer might add something like this to hyperref.cfg:

3.4 Extension options

Note that all color names must be defined before use, following the normal system of the standard LATEX color package.

3.5 PDF-specific display options

Note that the color of link borders can be specified only as 3 numbers in the range 0..1, giving an RGB color. You cannot use colors defined in TEX.

The bookmark commands are stored in a file called jobname.out. The files is not processed by LATEX so any markup is passed through. You can postprocess this file as needed; as an aid for this, the .out file is not overwritten on the next TEX run if it is edited to contain the line

3.6 PDF display and information options

Each link in Acrobat carries its own magnification level, which is set using PDF coordinate space, which is not the same as TEX’s. pdfTEX works by supplying default values for XYZ (horizontal × vertical × zoom) and FitBH. However, drivers using pdfmark do not supply defaults, so hyperref passes in a value of -32768, which causes Acrobat to set (usually) sensible defaults. The following are possible values for the pdfview and pdfstartview parameters.

The pdfpagelayout can be one of the following values.

Finally, the pdfpagetransition can be one of the following values, where /Di stands for direction of motion in degrees, generally in 90^o steps, /Dm is a horizontal (/H) or vertical (/V) dimension (e.g. Blinds /Dm /V), and /M is for motion, either in (/I) or out (/O).

3.7 Big alphabetical list

The following is a complete listing of available options for hyperref, arranged alphabetically.

4 Additional user macros

If you need to make references to URLs, or write explicit links, the following low-level user macros are provided:

The text is made a hyperlink to the URL; this must be a full URL (relative to the base URL, if that is defined). The special characters # and ~ do not need to be escaped in any way.

Equivalent to \href{URL}{URL}.

Write URL as plain text, without creating a hyperlink.

A base URL is established, which is prepended to other specified URLs, to make it easier to write portable documents.

The image referenced by the URL is inserted.

A target area of the document (the text) is marked, and given the name category.name

text is made into a link to URL#category.name

A simple internal link is created with \hypertarget, with two parameters of an anchor name, and anchor text. \hyperlink has two arguments, the name of a hypertext object defined somewhere by \hypertarget, and the text which be used as the link on the page.

Note that in HTML parlance, the \hyperlink command inserts a notional # in front of each link, making it relative to the current testdocument; \href expects a full URL.

This is a replacement for the usual \ref command that places a contextual label in front of the reference. This gives your users a bigger target to click for hyperlinks (e.g. ‘section 2’ instead of merely the number ‘2’).

The label is worked out from the context of the original \label command by hyperref by using the macros listed below (shown with their default values). The macros can be redefined in documents using \renewcommand; note that some of these macros are already defined in the standard document classes. The mixture of lowercase and uppercase initial letters is deliberate and corresponds to the author’s practice.

For each macro below, hyperref checks \*autorefname before \*name. For instance, it looks for \figureautorefname before \figurename.

For instances where you want a reference to use the correct counter, but not to create a link, there are two starred forms:

A typical use would be to write

We want \ref*{other} to generate the correct number, but not to form a link, since we do this ourselves with \hyperref.

\pdfstringdef returns a macro containing the PDF string. (Currently this is done globally, but do not rely on it.) All the following tasks, definitions and redefinitions are made in a group to keep them local:

• Switching to PD1 or PU encoding
• Defining the octal sequence commands (\345): \edef\3{\string\3}
• Special glyphs of TEX: \{, \%, \&, \space, \dots, etc.
• National glyphs (german.sty, french.sty, etc.)
• Logos: \TeX, \eTeX, \MF, etc.
• Disabling commands that do not provide useful functionality in bookmarks: \label, \index, \glossary, \discretionary, \def, \let, etc.
• LATEXŠs font commands like \textbf, etc.
• Support for \xspace provided by the xspace package

In addition, parentheses are protected to avoid the danger of unsafe unbalanced parentheses in the PDF string. For further details, see Heiko Oberdiek’s EuroTEX paper distributed with hyperref.

4.1 Replacement macros

hyperref takes the text for bookmarks from the arguments of commands like \section, which can contain things like math, colors, or font changes, none of which will display in bookmarks as is.

For example,

\pdfstringdef executes the hook before it expands the string. Therefore, you can use this hook to perform additional tasks or to disable additional commands.

However, for disabling commands, an easier way is via \pdfstringdefDisableCommands, which adds its argument to the definition of \pdfstringdefPreHook (‘@’ can here be used as letter in command names):

5 Acrobat-specific behavior

If you want to access the menu options of Acrobat Reader or Exchange, the following macro is provided in the appropriate drivers:

The text is used to create a button which activates the appropriate menuoption. The following table lists the option names you can use—comparison of this with the menus in Acrobat Reader or Exchange will show what they do. Obviously some are only appropriate to Exchange.

File	Open, Close, Scan, Save, SaveAs, Optimizer:SaveAsOpt, Print, PageSetup, Quit
FileImport	ImportImage, ImportNotes, AcroForm:ImportFDF
FileExport	ExportNotes, AcroForm:ExportFDF
FileDocumentInfo	GeneralInfo, OpenInfo, FontsInfo, SecurityInfo, Weblink:Base, AutoIndex:DocInfo
FilePreferences	GeneralPrefs, NotePrefs, FullScreenPrefs, Weblink:Prefs, AcroSearch:Preferences(Windows) or, AcroSearch:Prefs(Mac), Cpt:Capture
Edit	Undo, Cut, Copy, Paste, Clear, SelectAll, Ole:CopyFile, TouchUp:TextAttributes, TouchUp:FitTextToSelection, TouchUp:ShowLineMarkers, TouchUp:ShowCaptureSuspects, TouchUp:FindSuspect,
	Properties
EditFields	AcroForm:Duplicate, AcroForm:TabOrder
Document	Cpt:CapturePages, AcroForm:Actions, CropPages, RotatePages, InsertPages, ExtractPages, ReplacePages, DeletePages, NewBookmark, SetBookmarkDest, CreateAllThumbs, DeleteAllThumbs
View	ActualSize, FitVisible, FitWidth, FitPage, ZoomTo, FullScreen, FirstPage, PrevPage, NextPage, LastPage, GoToPage, GoBack, GoForward, SinglePage, OneColumn, TwoColumns, ArticleThreads, PageOnly, ShowBookmarks, ShowThumbs
Tools	Hand, ZoomIn, ZoomOut, SelectText, SelectGraphics, Note, Link, Thread, AcroForm:Tool, Acro_Movie:MoviePlayer, TouchUp:TextTool, Find, FindAgain, FindNextNote, CreateNotesFile
ToolsSearch	AcroSrch:Query, AcroSrch:Indexes, AcroSrch:Results, AcroSrch:Assist, AcroSrch:PrevDoc, AcroSrch:PrevHit, AcroSrch:NextHit, AcroSrch:NextDoc
Window	ShowHideToolBar, ShowHideMenuBar, ShowHideClipboard, Cascade, TileHorizontal, TileVertical, CloseAll
Help	HelpUserGuide, HelpTutorial, HelpExchange, HelpScan, HelpCapture, HelpPDFWriter, HelpDistiller, HelpSearch, HelpCatalog, HelpReader, Weblink:Home
Help(Windows)	About

6 PDF and HTML forms

You must put your fields inside a Form environment (only one per file).

There are six macros to prepare fields:

The way forms and their labels are laid out is determined by:

These macros default to #1 #2

What is actually shown in as the field is determined by:

These macros default to \vbox to #2{\hbox to #1{\hfill}\vfill}, except the last, which defaults to #1; it is used for buttons, and the special \Submit and \Reset macros.

You may also want to redefine the following macros:

6.1 Forms environment parameters

6.2 Forms optional parameters

Note that all colors must be expressed as RGB triples, in the range 0..1 (i.e. color=0 0 0.5)

7 Defining a new driver

A hyperref driver has to provide definitions for eight macros:

1. \hyper@anchor

2. \hyper@link

3. \hyper@linkfile

4. \hyper@linkurl

5. \hyper@anchorstart

6. \hyper@anchorend

7. \hyper@linkstart

8. \hyper@linkend

The draft option defines the macros as follows

8 Special support for other packages

hyperref aims to cooperate with other packages, but there are several possible sources for conflict, such as

• Packages that manipulate the bibliographic mechanism. Peter William’s harvard package is supported. However, the recommended package is Patrick Daly’s natbib package that has specific hyperref hooks to allow reliable interaction. This package covers a very wide variety of layouts and citation styles, all of which work with hyperref.
• Packages that typeset the contents of the \label and \ref macros, such as showkeys. Since the hyperref package redefines these commands, you must set implicit=false for these packages to work.
• Packages that do anything serious with the index.

The hyperref package is distributed with variants on two useful packages designed to work especially well with it. These are xr and minitoc, which support crossdocument links using LATEX’s normal \label/\ref mechanisms and per-chapter tables of contents, respectively.

9 History and acknowledgments

The original authors of hyperbasics.tex and hypertex.sty, from which this package descends, are Tanmoy Bhattacharya (tanmoy@qcd.lanl.gov) and Thorsten Ohl (thorsten.ohl@physik.th-darmstadt.de). hyperref started as a simple port of their work to LATEX2 standards, but eventually I rewrote nearly everything, because I didn’t understand a lot of the original, and was only interested in getting it to work with LATEX. I would like to thank Arthur Smith, Tanmoy Bhattacharya, Mark Doyle, Paul Ginsparg, David Carlisle, T. V. Raman and Leslie Lamport for comments, requests, thoughts and code to get the package into its first useable state. Various other people are mentioned at the point in the source where I had to change the code in later versions because of problems they found.

Tanmoy found a great many of the bugs, and (even better) often provided fixes, which has made the package more robust. The days spent on RevTEX are entirely due to him! The investigations of Bill Moss (bmoss@math.clemson.edu) into the later versions including native PDF support uncovered a good many bugs, and his testing is appreciated. Hans Hagen (pragma@pi.net) provided a lot of insight into PDF.

Berthold Horn provided help, encouragement and sponsorship for the dvipsone and dviwindo drivers. Sergey Lesenko provided the changes needed for dvipdf, and Hàn Thê' Thành supplied all the information needed for pdftex. Patrick Daly kindly updated his natbib package to allow easy integration with hyperref. Michael Mehlich’s hyper package (developed in parallel with hyperref) showed me solutions for some problems. Hopefully the two packages will combine one day.

The forms creation section owes a great deal to: T. V. Raman, for encouragement, support and ideas; Thomas Merz, whose book Web Publishing with Acrobat/PDF provided crucial insights; D. P. Story, whose detailed article about pdfmarks and forms solved many practical problems; and Hans Hagen, who explained how to do it in pdftex.

Steve Dandy recreated the manual source in July 2003 after it had been lost.

Especial extra thanks to David Carlisle for the backref module, the ps2pdf and dviwindo support, frequent general rewrites of my bad code, and for working on changes to the xr package to suit hyperref.