|
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.
The HyperTeX specification1 says that conformant viewers/translators must recognize the following set of \special constructs:
html:<a href = "href_string">
html:<a name = "name_string">
html:</a>
html:<img src = "href_string">
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:
Output from dvips or dvipsone must be processed using Acrobat Distiller to obtain a PDF file. The result is generally prefererable to that produced by using the `hypertex' driver, and then processing with dvips -z, but the dvi file is not portable.
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. 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.If you need to make references to URLs, or write explicit links, the following low-level user macros are provided:
| \href{URL}{text} |
~ do not need to be escaped in any
way.
| \hyperbaseurl{URL} |
| \hyperimage{image URL} |
| \hyperdef{category}{name}text |
| \hyperref{URL}{category}{name}{text} |
| \hyperlink{name}{text} |
| \hypertarget{name}{text} |
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.
If you want to access the meno options of Acrobat Reader or Exchange, the following macro is provided in the appropriate drivers:
| \Acrobatmenu{menuoption}{text} |
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.
|
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 behaviour of a particular file could be controlled by:
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 behaviour and page size.
|
|
If no driver is specified, the package defaults to loading the hypertex driver.
|
c:\netscape\netscape) to tell dviwindo what program to launch. Thus, users
of Internet Explorer might add something like this to hyperref.cfg:
|
|
|
You must put your fields inside a Form environment (only one per file).
There are six macros to prepare fields:
| \TextField[parameters]{label} |
| \CheckBox[parameters]{label} |
| \ChoiceMenu[parameters]{label}{choices} |
| \PushButton[parameters]{label} |
| \Submit[parameters]{label} |
| \Reset[parameters]{label} |
The way forms and their labels are laid out is determined by:
| \LayoutTextField{label}{field} |
| \LayoutChoiceField{label}{field} |
| \LayoutCheckboxField{label}{field} |
#1 #2
What is actually shown in as the field is determined by:
| \MakeRadioField{width}{height} |
| \MakeCheckField{width}{height} |
| \MakeTextField{width}{height} |
| \MakeChoiceField{width}{height} |
| \MakeButtonField{text} |
\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:
\def\DefaultHeightofSubmit{12pt}
\def\DefaultWidthofSubmit{2cm}
\def\DefaultHeightofReset{12pt}
\def\DefaultHeightofCheckBox{0.8\baselineskip}
\def\DefaultWidthofCheckBox{0.8\baselineskip}
\def\DefaultHeightofChoiceMenu{0.8\baselineskip}
\def\DefaultWidthofChoiceMenu{0.8\baselineskip}
Note that all colors must be expressed as RGB triples, in the range 0..1 (ie color=0 0 0.5)
|
A hyperref driver has to provide definitions for eight macros:
The draft option defines the macros as follows
\gdef\hyper@link##1##2##3{##3}%
\def\hyper@linkurl##1##2{##1}%
\def\hyper@linkfile##1##2##3{##1}%
\let\hyper@anchorstart\@gobble
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 LaTeX2e 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 Han The Thanh 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 Publishling 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.
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.