(eplain.info)Introduction to hyperlinks

---

Next: Explicit hyperlinks Up: Hyperlinks

---

Enter node , (file) or (file)node

5.1 Introduction to 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 (Note: 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.

Concepts and Terminology
------------------------

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 (Note: Explicit
hyperlinks, and Note: 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).

   Note: Hyperlink drivers, for the description of hyperlink types and
options supported by the drivers. Note: Setting hyperlink types and
options, for the information on how to set hyperlink options.