Next: Explicit hyperlinks, Up: Hyperlinks
The original TeX engine has no built-in support for hyperlinks
(a.k.a. hypertext links).
Many of the present-day file formats with hyperlinking capabilities
did not even exist at the time TeX was written. However, TeX's
\special primitive can be used to instruct TeX to write
special directives into its .dvi output file. These directives
are not interpreted by TeX in any way; they are intended for programs
which process the .dvi files produced by TeX, be it printing
or converting to other formats, such as
.ps or .pdf.
Another approach is to extend the original TeX engine with the ability to generate one of the hyperlinking formats; TeX's set of primitives can be extended to include hyperlink commands. This is the approach used by the pdfTeX engine, which is capable of producing .pdf files directly from the TeX source, skipping the .dvi generation and processing step.
It turns out that the sets of commands for different formats are mostly not interchangeable, as each of the file formats has its own quirks and capabilities. And this is where Eplain hyperlink drivers come into play.
In order for Eplain to generate proper commands, Eplain has to know two things: which engine or .dvi processor you are using, and the set of commands it understands.
The knowledge about the commands that the various processors
understand is programmed into Eplain's hyperlink drivers. Eplain
provides three drivers: hypertex (implementation of the
HyperTeX standard, see http://arxiv.org/hypertex), and
pdftex and dvipdfm (named after the programs which
process the hyperlink commands,
pdfTeX and
dvipdfm). Therefore, Eplain can only produce HyperTeX commands and
hyperlink commands for one of these two programs—except that the
extended dvipdfmx program can be used as well as the original
dvipdfm, since they are compatible.
To tell Eplain which .dvi processor or extended TeX engine you
are using, use the command
\enablehyperlinks.
For example:
\enablehyperlinks
instructs Eplain to attempt to automatically detect which
driver to use, as follows: if it detects pdfTeX in PDF
mode, it loads the pdftex driver. If it does not detect
pdfTeX in PDF mode, the hypertex driver is loaded.
The detection is based on the
\ifpdf switch (see Checking for PDF output).
If necessary, you can explicitly specify the driver name:
\enablehyperlinks[pdftex]
will start producing hyperlinks under the assumption that you are using pdfTeX.
Eplain does not produce any hyperlinks until you explicitly enable
them with \enablehyperlinks. For one thing, this keeps Eplain
backward-compatible with previous releases without hyperlink support.
For another, you may be using a program other than pdfTeX or
dvipdfm, which does not understand their hyperlink commands or
the HyperTeX commands.
In general, hyperlinks work as follows. You mark some place in your document as a hyperlink destination, associating a hyperlink label with that destination. Next, somewhere within your document, you create a hyperlink, using a label to identify the destination you want this link to point to. A hyperlink is a region in the document (which can take many forms, for example, text or a picture); when a user clicks on that region, they will be taken to a place in the document marked by the corresponding destination. The following two sections (Explicit hyperlinks, and Implicit hyperlinks) describe the macros you can use to define destinations and create links pointing to those destinations.
In the rest of this chapter, we will often need to refer to links and destinations jointly, in which case we will use the term hyperlinks. We will use the terms links and destinations in cases when we need to refer specifically to links or destinations.
Hyperlink drivers provide several kinds of links and destinations. We will refer to them as link types and destination types.
For example, one of the destination types that the pdftex
driver provides is the `xyz' type; when the user follows a link
pointing to an `xyz' destination, the exact location marked by
that destination is displayed. Another destination type provided by
the pdftex driver is the `fit' type; when the user follows
a link pointing to a `fit' destination, the page containing that
destination is zoomed to fit into the window in which the document is
displayed.
Similarly, drivers support various link types. For example, with the
pdftex driver, the usual link type used to refer to
destinations in the current document is called `name'. You can
also create a link pointing to another local document (by using the
`filename' link type) or to a URL (by using the
`url' link type).
In addition, each hyperlink driver supports a number of destination and link options. By setting these options you can customize hyperlink parameters (e.g., the thickness of the border drawn around a hyperlink) or pass information to hyperlinks (for example, file name of a document, for a link pointing to a destination in another document).
See Hyperlink drivers, for the description of hyperlink types and options supported by the drivers. See Setting hyperlink types and options, for the information on how to set hyperlink options.