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 297mm |
| a5paper | boolean | false | sets paper size to 148mm 210mm |
| b5paper | boolean | false | sets paper size to 176mm 250mm |
| letterpaper | boolean | false | sets paper size to 8.5in 11in |
| legalpaper | boolean | false | sets paper size to 8.5in 14in |
| executivepaper | boolean | false | sets paper size to 7.25in 10.5in |
| setpagesize | boolean | true | sets page size by special driver commands |
| raiselinks | boolean | true |
In the hypertex driver, the height of links is normally calculcated by the driver as simply the base line of contained text; this options forces \special commands to reflect the real height of the link (which could contain a graphic) |
| breaklinks | boolean | false |
Allows link text to break across lines; since this cannot be accommodated in PDF, it is only set true by default if the pdftex driver is used. This makes links on multiple lines into different PDF links to the same target. |
| pageanchor | boolean | true |
Determines whether every page is given an implicit anchor at the top left corner. If this is turned off, \printindex will not contain valid hyperlinks. |
| plainpages | boolean | false |
Forces page anchors to be named by the arabic form of the page number, rather than the formatted form. |
| nesting | boolean | false |
Allows links to be nested; no drivers currently support this. |
Note for option breaklinks: The correct value is automatically set according to the driver features. It can be overwritten for drivers that do not support broken links. However, at any case, the link area will be wrong and displaced.
If no driver is specified, the package defaults to loading the hypertex driver.
| dvipdfm |
Sets up hyperref for use with the dvipdfm driver. |
| dvipdfmx |
Sets up hyperref for use with the dvipdfmx driver. |
| dvips |
Sets up hyperref for use with the dvips driver. |
| dvipsone |
Sets up hyperref for use with the dvipsone driver. |
| dviwindo |
Sets up hyperref for use with the dviwindo Windows previewer. |
| hypertex |
Sets up hyperref for use with the HyperTEX-compliant drivers. |
| latex2html |
Redefines a few macros for compatibility with latex2html. |
| nativepdf |
An alias for dvips |
| pdfmark |
An alias for dvips |
| pdftex |
Sets up hyperref for use with the pdftex program. |
| ps2pdf |
Redefines a few macros for compatibility with Ghostscript’s PDF writer, otherwise identical to dvips. |
| tex4ht |
For use with TEX4ht |
| textures |
For use with Textures |
| vtex |
For use with MicroPress’ VTeX; the PDF and HTML backends are detected automatically. |
| vtexpdfmark |
For use with VTeX’s PostScript backend. |
| xetex |
For use with XeTEX(using backend for dvipdfm). |
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:
\renewcommand{wwwbrowser}{C:\string\Program\space
Files\string\Plus!\string\Microsoft\space Internet\string\iexplore.exe} |
| extension | text |
Set the file extension (e.g. dvi) which will be appended to file links created if you use the xr package. |
|
| hyperfigures | boolean |
|
|
| backref | boolean | false |
Adds ‘backlink’ text to the end of each item in the bibliography, as a list of section numbers. This can only work properly if there is a blank line after each \bibitem. |
| pagebackref | boolean | false |
Adds ‘backlink’ text to the end of each item in the bibliography, as a list of page numbers. |
| hyperindex | boolean | true |
Makes the page numbers of index entries into hyperlinks. Relays on unique page anchors (pageanchor, …) |
| pageanchors and plainpages=false. | |||
| hyperfootnotes | boolean | true |
Makes the footnote marks into hyperlinks to the footnote text. Easily broken … |
| encap |
Sets encap character for hyperindex |
||
| linktocpage | boolean | false |
make page number, not text, be link on TOC, LOF and LOT |
| breaklinks | boolean | false |
allow links to break over lines by making links over multiple lines into PDF links to the same target |
| colorlinks | boolean | false |
Colors the text of links and anchors. The colors chosen depend on the the type of link. At present the only types of link distinguished are citations, page references, URLs, local file references, and other links. |
| linkcolor | color | red |
Color for normal internal links. |
| anchorcolor | color | black |
Color for anchor text. |
| citecolor | color | green |
Color for bibliographical citations in text. |
| filecolor | color | magenta |
Color for URLs which open local files. |
| menucolor | color | red |
Color for Acrobat menu items. |
| runcolor | color | filecolor |
Color for run links (launch annotations). |
| urlcolor | color | cyan |
Color for linked URLs. |
| frenchlinks | boolean | false |
use small caps instead of color for links |
Note that all color names must be defined before use, following the normal system of the standard LATEX color package.
| bookmarks | boolean | true |
A set of Acrobat bookmarks are written, in a manner similar to the table of contents, requiring two passes of LATEX. Some postprocessing of the bookmark file (file extension .out) may be needed to translate LATEX codes, since bookmarks must be written in PDFEncoding. To aid this process, the .out file is not rewritten by LATEX if it is edited to contain a line \let\WriteBookmarks\relax |
| bookmarksopen | boolean | false |
If Acrobat bookmarks are requested, show them with all the subtrees expanded. |
| bookmarksopenlevel | parameter |
level (\maxdimen) to which bookmarks are open |
|
| bookmarksnumbered | boolean | false |
If Acrobat bookmarks are requested, include section numbers. |
| bookmarkstype | text | toc |
to specify which ‘toc’ file to mimic |
| CJKbookmarks | boolean | false |
This option should be used to produce CJK bookmarks. Package hyperref supports both normal and preprocessed mode of the CJK package; during the creation of bookmarks, it simply replaces CJK’s macros with special versions which expand to the corresponding character codes. Note that without the ‘unicode’ option of hyperref you get PDF files which actually violate the PDF specification because non-Unicode character codes are used – some PDF readers localized for CJK languages (most notably Acroread itself) support this. Also note that option ‘CJKbookmarks’ cannot be used together with option ‘unicode’. No mechanism is provided to translate non-Unicode bookmarks to Unicode; for portable PDF documents only Unicode encoding should be used. |
| pdfhighlight | name | /I |
How link buttons behave when selected; /I is for inverse (the default); the other possibilities are /N (no effect), /O (outline), and /P (inset highlighting). |
| citebordercolor | RGB color | 0 1 0 |
The color of the box around citations |
| filebordercolor | RGB color | 0 .5 .5 |
The color of the box around links to files |
| linkbordercolor | RGB color | 1 0 0 |
The color of the box around normal links |
| menubordercolor | RGB color | 1 0 0 |
The color of the box around Acrobat menu links |
| urlbordercolor | RGB color | 0 1 1 |
The color of the box around links to URLs |
| runbordercolor | RGB color | 0 .7 .7 |
color of border around ‘run’ links |
| pdfborder | 0 0 1 |
The style of box around links; defaults to a box with lines of 1pt thickness, but the colorlinks option resets it to produce no border. |
|
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
\let\WriteBookmarks\relax
|
| baseurl | URL |
Sets the base URL of the PDF document |
|
| pdfpagemode | text | empty |
Determines how the file is opening in Acrobat; the possibilities are UseNone, UseThumbs (show thumbnails), UseOutlines (show bookmarks), FullScreen, UseOC (PDF 1.5), and UseAttachments (PDF 1.6). If no mode if explicitly chosen, but the bookmarks option is set, UseOutlines is used. |
| pdftitle | text |
Sets the document information Title field |
|
| pdfauthor | text |
Sets the document information Author field |
|
| pdfsubject | text |
Sets the document information Subject field |
|
| pdfcreator | text |
Sets the document information Creator field |
|
| pdfproducer | text |
Sets the document information Producer field |
|
| pdfkeywords | text |
Sets the document information Keywords field |
|
| pdfview | text | XYZ |
Sets the default PDF ‘view’ for each link |
| pdfstartpage | text | 1 |
Determines on which page the PDF file is opened. |
| pdfstartview | text | Fit |
Set the startup page view |
| pdfpagescrop | n n n n |
Sets the default PDF crop box for pages. This should be a set of four numbers |
|
| pdfcenterwindow | boolean | false |
position the document window in the center of the screen |
| pdfdirection | text | empty |
direction setting |
| pdfdisplaydoctitle | boolean | false |
display document title instead of file name in title bar |
| pdfduplex | text | empty |
paper handling option for print dialog |
| pdffitwindow | boolean | false |
resize document window to fit document size |
| pdflang | text | empty |
PDF language identifier (RFC 3066) |
| pdfmenubar | boolean | true |
make PDF viewer’s menu bar visible |
| pdfnewwindow | boolean | false |
make links that open another PDF file start a new window |
| pdfnonfullscreenpagemode | boolean | empty |
page mode setting on exiting full-screen mode |
| pdfnumcopies | integer | empty |
number of printed copies |
| pdfpagelayout | text | empty |
set layout of PDF pages |
| pdfpagelabels | boolean | true |
set PDF page labels |
| pdfpagetransition | text | empty |
set PDF page transition style |
| pdfpicktrackbypdfsize | text | empty |
set option for print dialog |
| pdfprintarea | text | empty |
set /PrintArea of viewer preferences |
| pdfprintclip | text | empty |
set /PrintClip of viewer preferences |
| pdfprintpagerange | n n (n n)* | empty |
set /PrintPageRange of viewer preferences |
| pdfprintscaling | text | empty |
page scaling option for print dialog; valid values are None and AppDefault |
| pdftoolbar | boolean | true |
make PDF toolbar visible |
| pdfviewarea | text | empty |
set /ViewArea of viewer preferences |
| pdfviewclip | text | empty |
set /ViewClip of viewer preferences |
| pdfwindowui | boolean | true |
make PDF user interface elements visible |
| unicode | boolean | false |
Unicode encoded PDF strings |
Each link in Acrobat carries its own magnification level, which is set using PDF coordinate space, which is not the same as TEX’s. The unit is bp and the origin is in the lower left corner. See also \hypercalcbp that is explained on page 35. 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.
| XYZ | left top zoom |
Sets a coordinate and a zoom factor. If any one is null, the source link value is used. null null null will give the same values as the current page. |
| Fit |
Fits the page to the window. |
|
| FitH | top |
Fits the width of the page to the window. |
| FitV | left |
Fits the height of the page to the window. |
| FitR | left bottom right top |
Fits the rectangle specified by the four coordinates to the window. |
| FitB |
Fits the page bounding box to the window. |
|
| FitBH | top |
Fits the width of the page bounding box to the window. |
| FitBV | left |
Fits the height of the page bounding box to the window. |
The pdfpagelayout can be one of the following values.
| SinglePage |
Displays a single page; advancing flips the page |
| OneColumn |
Displays the document in one column; continuous scrolling. |
| TwoColumnLeft |
Displays the document in two columns, odd-numbered pages to the left. |
| TwoColumnRight |
Displays the document in two columns, odd-numbered pages to the right. |
Finally, the pdfpagetransition can be one of the following values, where /Di stands for direction of motion in degrees, generally in 90 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).
| Blinds | /Dm |
Multiple lines distributed evenly across the screen sweep in the same direction to reveal the new page. |
| Box | /M |
A box sweeps in or out. |
| Dissolve |
The page image dissolves in a piecemeal fashion to reveal the new page. |
|
| Glitter | /Di |
Similar to Dissolve, except the effect sweeps across the screen. |
| Split | /Dm /M |
Two lines sweep across the screen to reveal the new page. |
| Wipe | /Di |
A single line sweeps across the screen to reveal the new page. |
The following is a complete listing of available options for hyperref, arranged alphabetically.
| a4paper |
use A4 paper |
|
| a5paper |
use A5 paper |
|
| anchorcolor | black |
set color of anchors |
| b5paper |
use B5 paper |
|
| backref | false |
do bibliographical back references |
| baseurl | empty |
set base URL for document |
| bookmarks | true |
make bookmarks |
| bookmarksnumbered | false |
put section numbers in bookmarks |
| bookmarksopen | false |
open up bookmark tree |
| bookmarksopenlevel | \maxdimen |
level to which bookmarks are open |
| bookmarkstype | toc |
to specify which ‘toc’ file to mimic |
| breaklinks | false |
allow links to break over lines |
| CJKbookmarks | false |
to produce CJK bookmarks |
| citebordercolor | 0 1 0 |
color of border around cites |
| citecolor | green |
color of citation links |
| colorlinks | false |
color links |
| true |
(tex4ht, dviwindo) |
|
| debug | false |
provide details of anchors defined; same as verbose |
| draft | false |
do not do any hyperlinking |
| dvipdfm |
use dvipdfm backend |
|
| dvipdfmx |
use dvipdfmx backend |
|
| dvips |
use dvips backend |
|
| dvipsone |
use dvipsone backend |
|
| dviwindo |
use dviwindo backend |
|
| encap |
to set encap character for hyperindex |
|
| executivepaper |
use executivepaper |
|
| extension | dvi |
suffix of linked files |
| filebordercolor | 0 .5 .5 |
color of border around file links |
| filecolor | cyan |