Hyperlinks
**********

This chapter describes the support which Eplain provides for hypertext links (hyperlinks for short).  Hyperlinks can be created implicitly by the cross-reference, indexing and other macros in Eplain.  Macros for constructing explicit hyperlinks are also provided.

Introduction to hyperlinks
==========================

The original TeX engine has no built-in support for hyperlinks. 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 two drivers, pdftex and dvipdfm, named after the programs which process the hyperlink commands, pdfTeX and dvipdfm.  Therefore, Eplain can only produce 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 dvipdfm 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.

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

Explicit hyperlinks
===================

Explicit hyperlinks are created by you, in the source of your document.  The simplest command is \hldest, which marks the current position in your document as a destination:

     \hldest{TYPE}{OPTIONS}{LABEL}

Here TYPE is one of the destination types supported by the hyperlink driver (see Hyperlink drivers), OPTIONS is a comma-separated list of option assignments, and LABEL is the hyperlink label to associate with this destination.  This label will identify the destination when creating links pointing to this destination.  For example, with the pdftex driver, the command

     \hldest{xyz}{zoom=2000}{index}

creates a destination of type xyz (``the current position''), sets the magnification ratio for this destination to be 200%, and associates the label index with the destination.

Another command, \hlstart, paired with \hlend, turns all intervening material into a link:

     \hlstart{TYPE}{OPTIONS}{LABEL} ... \hlend

Here TYPE, OPTIONS and LABEL have the same meaning as for \hldest.  Continuing the previous example,

     \hlstart{name}{bstyle=U,bwidth=2}{index} Index\hlend

typesets the word `Index' as a link with underline border of width 2 PostScript points, pointing to the named destination index defined in the previous example.  (The other options, like highlight mode and border color, are determined by the defaults, see Setting default types and options).

Both \hldest and \hlstart ignore following spaces.

Both \hldest and \hlstart expand the first token of OPTIONS once, so you can save a list of options in a macro and pass it for the OPTIONS.  For example:

     \def\linkopts{bstyle=U,bwidth=2}
     \hlstart{name}{\linkopts}{index}Index\hlend

is functionally equivalent to the previous example.

Implicit hyperlinks
===================

Implicit hyperlinks are hyperlinks created implicitly by various Eplain macros, such as the macros for citations, cross-references, indexing, etc.

All such macros are divided into link groups and destination groups (or linkgroups and destgroups for short) so that parameters can be set individually for each group.  For example, all equation macros which define a destination are assigned to the `eq' destgroup; equation macros which create a link are assigned to the `eq' linkgroup.  By setting parameters for the `eq' linkgroup (destgroup), you can uniformly customize all links (destinations) related to equation references, without interfering with settings for the other groups.

See Setting hyperlink types and options, for information on how to set parameters for a group.

Here is the list of the linkgroups:

     cite, ref, xref, eq, idx, foot, footback, url.

And here are the destgroups:

     bib, li, definexref, xrdef, eq, idx, foot, footback.

The following subsections describe each of the linkgroups and destgroups and the hyperlink support provided.

URL hyperlinks: url
-------------------

The `url' linkgroup covers the \url command from the LaTeX package url (see Packages known to work), as well as any new \url-like commands you define.  The type for this linkgroup is set to url by the drivers which support this link type. url links use the parameter to the \url command as the URL to point to.

You may be using the \url command to typeset something other than a URL, e.g., a path, for which you do not want a link to be created; in that case, you can disable the `url' linkgroup with the command \hloff[url] (see Turning hyperlinks on/off for a group).

Citation hyperlinks: cite, bib
------------------------------

The `cite' linkgroup includes only the \cite command (see Citations).  \cite turns each of the references in the list into a link pointing to the respective bibliography entry produced by the \bibliography command.

The `bib' destgroup includes the macros related to the \bibliography command (see Citations).  \bibliography inputs a .bbl file, which contains a list of bibliography entries.  For each of the entries, a destination is defined.

Both commands use the citation label as the hyperlink label.

List hyperlinks: li
-------------------

The `li' destgroup consists of the \li command (see Lists), which defines a destination if you supply the optional argument (cross-reference label).  This label is also used as the hyperlink label.

Cross-reference hyperlinks: definexref, ref
-------------------------------------------

The `definexref' destgroup is for the \definexref command (see Defining generic references).  \definexref defines a destination using the cross-reference label (the first argument) as the hyperlink label.

The `ref' linkgroup includes \refn and \xrefn (they are synonyms), \ref, and \refs (see Using generic references).

\refn turns the cross-reference it produces into a link, using the cross-reference label as the hyperlink label.  If an optional argument is present, it is tied by \reftie to the reference and become part of the link.

\ref works similarly to \refn.  It takes an optional argument, which is treated the same way as the optional argument to \refn.  In addition, \ref can produce a ``class word''. Both the optional argument and the class word become part of the link, when present.  The cross-reference is tied by \reftie to the preceding word.  The optional argument is separated from the class word by \refspace.

Unlike \ref, \refs does not take an optional argument and does not make the class word part of the link, which is appropriate for its intended use.

Page reference hyperlinks: xrdef, xref
--------------------------------------

The `xrdef' destgroup is for \xrdef (see Page references). \xrdef defines a destination using cross-reference label as the hyperlink label.

The `xref' linkgroup includes the \xref command (see Page references).  \xref turns its optional argument (followed by \refspace), \xrefpageword and the cross-reference (page number) into a link, using the cross-reference label as the hyperlink label.

Equation reference hyperlinks: eq
---------------------------------

All commands that define equation labels are part of the `eq' destgroup. These are \eqdef, \eqdefn, \eqsubdef and \eqsubdefn (see Equation references).  All these commands use the equation label as the hyperlink label.  However, if the equation label is empty, they make up a (hopefully) unique hyperlink label for the destination.  This label will be used for the link when you refer to this empty-labeled equation with one of the equation reference macros.

The command \phantomeqlabel is called to generate hyperlink labels for the empty-labeled equations.  By default, it produces the labels in the format PHEQNUMBER, where NUMBER comes from the count register \phantomeqnumber; this count register is incremented at every empty-labeled equation definition.

The commands \eqref and \eqrefn (see Equation references) form the `eq' linkgroup.  These commands take an optional argument, which, when present, is tied with \reftie to the equation reference and becomes part of the link.  The equation label is used for the hyperlink label; if the label is empty, the link is for the label generated for the last empty-labeled equation.

Index hyperlinks: idx
---------------------

All indexing commands (\idx, \idxname, \idxmarked, \idxsubmarked and their silent equivalents, see Indexing commands) form the `idx' destgroup.  The `idx' linkgroup consists of the macros which are used to typeset the index when you say \readindexfile{INDEX-LETTER} (see Typesetting an index).

To create the links in index entries, Eplain uses MakeIndex's ``encapsulation'' feature.  When you use an indexing macro to mark an index term, Eplain writes out a line to the .idx file of the following general form:

     \indexentry{ENTRY|PAGEMARKUP}{PAGENO}

where ENTRY is the index entry (converted into the internal format that MakeIndex understands), CS is the markup command you specified with the pagemarkup=CS optional argument to the indexing commands (see Modifying index entries), and PAGENO is the page number on which the term appeared.  When processing the .idx file, MakeIndex makes the page number an argument to the page markup command (``encapsulates'' the page number), so the page number in the .ind file appears as \CS{PAGENO}.  Eplain internally replaces the CS command name with its own command, which, in addition to calling the original \CS encapsulator, turns the page number into a link.

Eplain provides two approaches to linking page numbers in the index to locations of index terms in the text.

Exact destinations for index terms
..................................

In this approach, each command that marks an index term defines a unique destination and passes its label on to the .idx file as part of the \indexentry command.  The \indexentry line that Eplain writes to the .idx file becomes

     \indexentry{ENTRY|hlidx{LABEL}{CS}}{PAGENO}

where \hlidx is the command that is defined by Eplain to take three arguments:  a hyperlink label (LABEL), a name of page number encapsulator (CS) and a page number (PAGENO). In the .ind file that MakeIndex will generate, the page number will now appear as

     \hlidx{LABEL}{CS}{PAGENO}

The result of this command is \CS{PAGENO}, wrapped up into a link pointing to LABEL destination.

The hyperlink labels for the index terms are generated by the \hlidxlabel command, by default in the format IDXNUMBER, where NUMBER is the value of the count register \hlidxlabelnumber.  This count register is incremented at each index term.

The advantage of this approach, as compared to the second approach described below, is that links in the index point to exact locations of the indexed terms on the page.  The disadvantage of this approach is that MakeIndex will regard all index entries as distinct, because each one contains a (unique) hyperlink label.  This disadvantage can be partially overcome by the script idxuniq distributed with Eplain in the util directory. This script filters out \indexentry lines differing only in the hyperlink label but identical otherwise.  You should process the .idx with this script before passing it on to MakeIndex.  For example:

     prompt$ ./idxuniq file.idx | makeindex > file.ind

Still, this solution is not ideal, as the page-range formation ability of MakeIndex will not work, and there will be problems of apparently identical index entries clashing (e.g., when a range-end entry appears on the same page as another entry with the same definition; idxuniq will not filter out the second entry).

Page destinations for index terms
.................................

In the second approach, Eplain does not write out any destination labels for the index terms.  Instead, Eplain writes out a wrapper for page number encapsulator which can parse the page number and generate a link pointing to the page on which the term appeared.  On top of each page containing an index term, Eplain defines a destination with label produced by \hlidxpagelabel.  The \hlidxpagelabel command takes a single argument (page number NUMBER) and by default produces the label in the format IDXPGNUMBER.

With this approach, the \indexentry line which Eplain writes to the .idx file looks like this:

     \indexentry{ENTRY|hlidxpage{CS}}{PAGENO}

where \hlidxpage is the command that is defined by Eplain to take two arguments:  a name of page number encapsulator (CS) and a page number (PAGENO).  In the .ind file that MakeIndex will generate, the page number will appear as

     \hlidxpage{CS}{PAGENO}

The advantage of this approach is that all features of MakeIndex are intact.  The drawback is that links in the index do not point to exact locations of indexed terms on a page, but to the top of a page on which the term appears.

Another disadvantage is that this approach depends on the page range and page list separators which MakeIndex was configured to output. \hlidxpage must be able to parse the first page number in a page range like 1--4.  In addition, page list parsing is needed because MakeIndex combines two consecutive page numbers in one call to the page number encapsulator, so \hlidxpage can be passed, e.g., 1, 2 for the PAGENO.  In this last case, \hlidxpage splits the two page numbers, applies \CS to each of them, and makes each of the page numbers a link to the appropriate page.  Note that this will alter typesetting slightly, because now the page list separator (a comma followed by a space, by default) is not typeset using the page number encapsulator (\CS).

Eplain's defaults for the page list and page number delimiters are the same as those in MakeIndex, a comma followed by a space (, ) and two dashes (--), respectively.  If you customize MakeIndex to use different delimiters, you must not forget to let Eplain know about them with the commands

     \setidxpagelistdelimiter{LIST-DELIM}
     \setidxpagerangedelimiter{PAGE-DELIM}

(see Page list and page range parsers).

Choosing destination placement
..............................

The approach that Eplain should use for the index terms can be selected in the \enablehyperlinks command.  The optional argument it accepts is a comma-separated list of options.  The idxexact option selects the first approach, idxpage the second, and idxnone disables hyperlink support for the index terms altogether, in case you want to stop Eplain from writing its link wrappers into the .idx file.  The default is idxpage.

For example:

     \enablehyperlinks[idxexact]

selects the first approach (``exact index links'').

Index page list and page range parsers
......................................

The macros that Eplain uses to parse page lists and page ranges, \idxparselist and \idxparserange, can sometimes be useful when defining page number encapsulators.  See Page list and page range parsers, for the description of these commands and an example of their usage.

Hyperlinks in see and see also entries
......................................

There is no automatic support for hyperlinks with ``see'' and ``see also'' index entries, as there is not enough information to trace the parameters of \indexsee and \indexseealso to corresponding index entries.  But if desired, this can be implemented with \hldest and \hlstart (see Explicit hyperlinks); for example:

     \sidx{semantic theory of truth@%
           \leavevmode\hldest{}{}{idx:theo truth}semantic theory of truth}
     ...
     \sidx[seealso]{truth}[definition of]%
           {\hlstart{}{}{idx:theo truth}semantic theory of truth\hlend}

Footnote hyperlinks: foot, footback
-----------------------------------

The `foot' link and destination groups include the \numberedfootnote and \footnote macros (see Footnotes).  The `footback' groups include the same macros, but control parameters for links and destinations created inside the footnote to point back to the footnote mark within the text body.

The macros use hyperlink labels generated by \hlfootlabel and \hlfootbacklabel.  The default formats for the labels are FOOTNUMBER and FOOTBNUMBER, respectively, where NUMBER is the value of the count register \hlfootlabelnumber.  This register is incremented at every footnote.

Contents hyperlinks
-------------------

There is currently no special support for hyperlinks in the table of contents (see Contents), but implementing them with the \hldest and \hlstart ... \hlend commands (see Explicit hyperlinks) should be possible.

Hyperlink drivers
=================

This section describes the hyperlink drivers: the types of hyperlinks they support, and the options they accept.  During the first reading, you may only want to skim through this section.

Some of the descriptions below come from Portable Document Format Reference Manual Version 1.3, March 11, 1999.

Options supported by all drivers
--------------------------------

This subsection describes the destination and link options which are supported by all hyperlink drivers.

Destination options supported by all drivers
............................................

raise
     Specifies how much to raise destinations above the baseline.  When set to zero or empty, destinations are placed at the baseline.

     It is usually convenient to set this option to some variable parameter, so that the height to which destinations are raised is automatically adjusted according to the current context.  For example, setting it to \normalbaselineskip (or some fraction of it, like 1.7\normalbaselineskip) makes the setting appropriate for different point sizes, in case your document uses more than one.

     The default setting is \normalbaselineskip.  Initially, the destgroups do not define this option, so they fall back on the default, except for the `eq' destgroup, for which this option is set to 1.7\normalbaselineskip, to accommodate the usual cases of large operators in displayed math.

     Example:  \hldestopts[eq]{raise=2.5\normalbaselineskip}

Link options supported by all drivers
.....................................

colormodel
color
     These two options define the color to be used for rendering the link text.  The colors are used only when a \color command is defined, e.g., by loading the LaTeX `color' package (see Packages known to work).  The \color command is called as \color[COLORMODEL]{COLOR}, where COLORMODEL and COLOR are the definitions of the colormodel and color options, respectively.  However, if COLORMODEL is empty, the optional argument to \color is omitted; and if COLOR is empty, the \color command is omitted altogether. The default setting is COLORMODEL=cmyk and COLOR=0.28,1,1,0.35.

     When specifying colors with several components delimited by commas (e.g., RGB and CMYK colors in the LaTeX `color' package), it is not possible to specify the components directly in the option list of \hlopts, because comma is the option list delimiter.  With the `color' package, it is possible to specify such colors by defining a custom color with \definecolor and using the new color name with an empty COLORMODEL (see examples below).

     Examples:

          \hlopts{colormodel=,color=blue}% predefined color
          \definecolor{mycolor}{rgb}{.3,.8,.95}
          \hlopts{colormodel=,color=mycolor}% custom color
          \hlopts{colormodel=gray,color=.4}

Hyperlink drivers pdftex and dvipdfm
------------------------------------

This subsection describes link and destination types and options supported by the pdftex and dvipdfm drivers.  Many of the hyperlink types and options are common to both drivers, so we describe them together.

Destination types for pdftex and dvipdfm
........................................

xyz
     ``Current position''.  The option zoom specifies magnification to use (zero or empty means leave magnification unchanged, which is the default).  This is the default type.

     For dvipdfm:  the options left and top specify position coordinates to use (empty options mean current position coordinate, which is the default).

     Example:  \hldest{xyz}{zoom=2000}{dest123}

fit
     Fit the page to the window.

     Example:  \hldest{fit}{}{dest123}

fith
     Fit the width of the page to the window.

     For dvipdfm:  the top option specifies vertical position (default is empty, meaning current position).

     Example:  \hldest{fith}{}{dest123}

fitv
     Fit the height of the page to the window.

     For dvipdfm:  The option left specifies horizontal position (default is empty, meaning current position).

     Example:  \hldest{fitv}{}{dest123}

fitb
     Fit the page's bounding box to the window.

     Example:  \hldest{fitb}{}{dest123}

fitbh
     Fit the width of the page's bounding box to the window.

     For dvipdfm:  the option top specifies vertical position (default is empty, meaning current position).

     Example:  \hldest{fitbh}{}{dest123}

fitbv
     Fit the height of the page's bounding box to the window.

     For dvipdfm:  the option left specifies horizontal position (default is empty, meaning current position).

     Example:  \hldest{fitbv}{}{dest123}

fitr
     For pdftex:  fit the rectangle specified by the options width, height and depth (as a TeX rule specification) in the window.  For dimensions set to empty, the corresponding value of the parent box is used (these are the defaults).

     For dvipdfm:  fit the rectangle specified by the options left, bottom, right and top (in PostScript points, 72 points per inch) in the window.  For dimensions set to empty, current position coordinate is substituted (these are the defaults).

     Example for pdftex:

          \hldest{fitr}{width=\hsize,height=.5\vsize,depth=0pt}{dest123}

     Example for dvipdfm:

          \hldest{fitr}{left=72,bottom=72,right=720,top=360}{dest123}

raw
     The destination specification (in the form of a pdfTeX command or a dvipdfm \special) is taken from the command sequence \CS, where CS is the value of the cmd option.  In the definition of \CS, use \@hllabel to refer to the hyperlink label.  This option is intended to be used with destgroups (see Setting hyperlink types and options), as it does not make sense to use it in a direct call to \hldest---you can just call the raw command.

     Example for pdftex:

          \makeatletter
          \def\mydest{\pdfdest name{\@hllabel} xyz}
          \hldesttype{raw}
          \hldestopts{cmd=mydest}
          \resetatcatcode

     Example for dvipdfm:

          \makeatletter
          \def\mydest{\special{pdf: dest (\@hllabel)
                                    [@thispage /XYZ @xpos @ypos 0]}}
          \hldesttype{raw}
          \hldestopts{cmd=mydest}
          \resetatcatcode

Destination options for pdftex and dvipdfm
..........................................

With respect to the destination options, the pdftex and dvipdfm differ in the way the fit rectangle is specified (relative coordinates for pdftex, absolute coordinates for dvipdfm).

Common destination options
..........................

cmd
     Name of the macro (without the leading \) containing a pdfTeX command or a dvipdfm \special for the raw destination.

     For an example of usage, see Destination types for pdftex and dvipdfm, description of the raw destination.

zoom
     Magnification ratio times 1000 (like TeX's scale factor). Zero or empty means leave magnification unchanged, which is the default.

     Example:  \hldest{xyz}{zoom=2000}{dest123}

pdftex-specific destination options
...................................

The dimension options below must be specified as a TeX rule specification.  When set to empty, the corresponding value of the parent box is used (this is the default for all dimension options).

depth
     Depth of the fit rectangle for the fitr destination.

height
     Height of the fit rectangle for the fitr destination.

width
     Width of the fit rectangle for the fitr destination.

     Example:

          \hldest{fitr}{width=\hsize,height=.5\vsize,depth=0pt}{dest123}

dvipdfm-specific destination options
....................................

The dimension options below must be specified in PostScript points (72 points per inch), as a number without the bp unit name.  When set to empty, the current position coordinate is used (this is the default for all dimension options).

bottom
     Bottom position coordinate of a box specification for the various destination types.

left
     Left position coordinate of a box specification for the various destination types.

right
     Right position coordinate of a box specification for the various destination types.

top
     Top position coordinate of a box specification for the various destination types.

     Example:

          \hldest{fitr}{left=72,bottom=72,right=720,top=360}{dest123}

Link types for pdftex and dvipdfm
.................................

Link types are the same for the pdftex and dvipdfm drivers, except that the pdftex driver provides one additional link type num (link to a numbered destination).  dvipdfm does not support numbered destinations, therefore it does not have this link type.  Note that all destinations created by Eplain hyperlink macros are named destinations; to define a numbered destination, you have to use low-level pdfTeX commands.

Common link types
.................

name
     Go to a ``named destination''.  The label is the destination name. All destinations created with \hldest are named destinations. This is the default type.

     Example:  \hlstart{name}{}{dest123}Link to dest123\hlend

page
     Go to a page.  The label is the page number (counting from 1). Page fitting is specified by the pagefit option.

     Example:

          \hlstart{page}{pagefit=/FitH 600}{123}Link to page~123\hlend

filename
     Go to a named destination in another file.  The label is the destination name.  The file name is specified by the file option.  Page fitting is specified by the pagefit option.  The newwin option specifies whether the destination document is opened in the same window or in a new window.

     Example:

          \hlstart{filename}{file=book.pdf,newwin=1}{dest123}
            Link to dest123 in file `book.pdf'\hlend

filepage
     Go to a page in another file.  The label is the page number (counting from 1).  The file name is specified by the file option.  Page fitting is specified by the pagefit option.  The newwin option specifies whether the destination document is opened in the same window or in a new window.

     Example:

          \hlstart{filepage}{file=book.pdf,newwin=,%
                             pagefit=/FitR 50 100 300 500}{1}
            Link to page~1 in file `book.pdf'\hlend

url
     Go to a URL.  The label is the URL.

     Example:  \hlstart{url}{}{http://tug.org/eplain/}Eplain home\hlend

raw
     The link specification (in the form of a pdfTeX command or a dvipdfm \special primitive) is taken from the command sequence \CS, where CS is the value of the cmd option.  This option is intended to be used with linkgroups (see Setting hyperlink types and options), as it does not make sense to use it in a direct call to \hlstart---you can just call the raw command.

     Example for pdftex:

          % Redirect all \url links to the first page
          \def\mycmd{\pdfstartlink goto page 1 {/Fit}}
          \hltype[url]{raw}
          \hlopts[url]{cmd=mycmd}

     Example for dvipdfm:

          % Redirect all \url links to the first page
          \def\mycmd{\special{pdf: beginann <</Type/Annot /Subtype/Link
                                              /Dest[0 /Fit]>>}}
          \hltype[url]{raw}
          \hlopts[url]{cmd=mycmd}

pdftex-specific link types
..........................

num
     Go to a ``numbered destination''.  The label is the destination number.

     Example:  \hlstart{num}{}{123}Link to 123\hlend

Link options for pdftex and dvipdfm
...................................

Link options are mostly the same for the pdftex and dvipdfm drivers.  The pdftex driver has additional options to specify link dimensions.

Common link options
...................

bcolor
     Border color.  An array of three numbers in the range 0 to 1, representing a color in DeviceRGB.

     Example:  \hlstart{name}{bcolor=.1 .5 1}{dest123}Link\hlend

bdash
     Array of numbers representing on and off stroke lengths for drawing dashes.

     Example:  \hlstart{name}{bstyle=D,bdash=2 4}{dest123}Link\hlend

bstyle
     Link border style:

     S
          The border is drawn as a solid line.

     D
          The border is drawn with a dashed line (the dash pattern is specified by the bdash option).

     B
          The border is drawn in a beveled style.

     I
          The border is drawn in an inset style.

     U
          The border is drawn as a line on the bottom of the link rectangle.

     The default is S.

     Example:  \hlstart{name}{bstyle=D,bdash=2 4}{dest123}Link\hlend

bwidth
     Border width in PostScript points (72 points per inch).  The default is 1.

     Example:  \hlstart{name}{bwidth=2}{dest123}Link\hlend

cmd
     Name of the macro (without the leading \) containing a pdfTeX command or a dvipdfm \special for the raw link.

     For an example of usage, see Link types for pdftex and dvipdfm, description of the raw link.

file
     File name for the filename and filepage link types.

     For an example of usage, see Link types for pdftex and dvipdfm, description of the filename and filepage links.

hlight
     Link border highlight modes:

     I
          The rectangle specified by the bounding box of the link is inverted.

     N
          No highlighting is done.

     O
          The border of the link is inverted.

     P
          The region underneath the bounding box of the link is drawn inset into the page.

     The default is I.

     Example:  \hlstart{name}{bstyle=S,hlight=O}{dest123}Link\hlend

newwin
     For the filename and filepage links, specifies whether the destination document is opened in the same window or in a new window.  The settings are:

     0
          Open in the same window.

     non-0
          Open in a new window.

     empty
          Behavior according to the viewer settings.

     The default is empty.

     For an example of usage, see Link types for pdftex and dvipdfm, description of the filename and filepage links.

pagefit
     For the page and filepage links, specifies how the page must be fitted to the window.  pagefit specification is written to the PDF file as is, so it must conform to the PDF standard.

     For an example of usage, see Link types for pdftex and dvipdfm, description of the page and filepage links.

pdftex-specific link options
............................

The dimension options below must be specified as a TeX rule specification.  When set to empty, the corresponding value of the parent box is used (this is the default for all dimension options).

depth
     Depth of the link.

height
     Height of the link.

width
     Width of the link.

     Example:

          \hlstart{name}{width=5in,height=20pc,depth=0pt}{dest123}
            Link\hlend

Hyperlink driver nolinks
------------------------

Select this driver to suppress all hyperlinks in your document.

Selecting this driver is quite different from not selecting any driver at all, or from selecting some driver and then turning hyperlinks off for the entire document with \hloff and \hldestoff (see Turning hyperlinks on/off).

The purpose of \hldestoff and \hloff is to mark (parts) of your document where hyperlinks should never appear.  (Imagine you want to prevent a cross-referencing macro from generating a link at a certain spot in your document.)

If instead you have prepared a document with hyperlinks and just want to compile a version without them, it is better to select the driver nolinks.  This ensures that spacing and page-breaking are the same as what you were getting with hyperlinks enabled.

The reason for this is that hyperlinks are produced by the \special primitives or low-level hyperlink commands.  Each such command is placed inside a whatsit (an internal TeX object), which may introduce legitimate breakpoints at places where none would exist without the whatsits.  The macros \hldestoff and \hloff disable the hyperlink macros completely, so that no whatsits are produced.

In contrast, the nolinks driver does not completely disable hyperlink macros.  Instead, it defines them to merely write to the log file (what gets written is unimportant).  This also produces whatsits, thus imitating the whatsits from the hyperlink commands. (This trick was borrowed from the LaTeX `color' package.)

Another reason for using nolinks is that in horizontal mode \hldest places destinations inside boxes of zero width, height, and depth.  When you say \hldestoff, \hldest will omit both destination definitions and these boxes.  The missing boxes can again cause the typesetting to be inconsistent with that with destinations enabled.  Here again, the nolinks driver helps by defining \hldest to produce the empty boxes.

Setting hyperlink types and options
===================================

You can define default types for links and destinations, which will be used when you do not specify a type in \hlstart or \hldest.  Similarly, you can define default values for the options; the default value for an option is used when you do not set the option in the argument to \hlstart or \hldest.

The parameters for implicit links and destinations can be customized by setting the ``group'' types and options.  When not set, the defaults are used.

All these settings are local to the current (TeX) group, so if you want to set an option temporarily, you can do so inside a \begingroup...\endgroup block; when the group ends, the previous settings are restored.

Setting default types and options
---------------------------------

The default types for links and destinations can be set with the following commands:

     \hltype{TYPE}
     \hldesttype{TYPE}

where TYPE is one of the link/destination types supported by the selected hyperlink driver (see Hyperlink drivers).

Default values for the options can be set with the following commands:

     \hlopts{OPTIONS}
     \hldestopts{OPTIONS}

where OPTIONS is a comma-separated list of option assignments in the format OPTION=VALUE.  Again, what options are allowed depends on the selected hyperlink driver.

Setting group types
-------------------

When called with an optional argument, as in

     \hltype[GROUPS]{TYPE}
     \hldesttype[GROUPS]{TYPE}

where GROUPS is a comma-separated list of groups, \hltype and \hldesttype set the type for each group from GROUPS to TYPE.  The default type is used for all groups with an empty type (this is the initial setting for all groups, except that the type for the `url' linkgroup is set to url by the drivers which support this link type).

There are two special ``groups'' which can be used inside the GROUPS list.  An empty group sets the default type.  This allows to set the default type and group types in one command, for example:

     \hltype[eq,]{TYPE}

sets the link type for the `eq' linkgroup and the default link type to TYPE.

Another special group is a star (*) group, which signifies all defined groups.  For example, the command

     \hldesttype[*,]{TYPE}

sets the destination type to TYPE for each group, as well as the default destination type.

Setting group options
---------------------

Option values for each group are stored as a list of option assignments.  This list does not have to contain every supported option.  Values for options missing from this list are taken from the default option values.

To manipulate the list of option values for the groups, you use the \hlopts and \hldestopts commands with an optional argument:

     \hlopts[GROUPS]{OPTIONS}
     \hldestopts[GROUPS]{OPTIONS}
     \hlopts![GROUPS]{OPTIONS}
     \hldestopts![GROUPS]{OPTIONS}

where GROUPS is a comma-separated list of groups and OPTIONS is a comma-separated list of option assignments.  The two special ``groups'', the empty group and the star (*) group, have the same meaning as for \hltype and \hldesttype. When used without the exclamation mark, \hlopts and \hldestopts preserve the current list of options for the groups, and only update the options listed in OPTIONS.  If you add the exclamation mark, the current list of options for each group in GROUPS is discarded and the new list is set to OPTIONS.

The ``overriding'' nature of the ! is appropriate when you give a complete specification of the options for a group, e.g., at the beginning of your document.  On the other hand, when you want to adjust some option(s) and leave others intact, you should use the macros without the !.

For example, with displayed mathematical formulas, you often need to adjust the raise option for the `eq' destgroup, because the formulas often contain large parentheses and brackets.  But when doing so, you want to leave the other settings unchanged.  To achieve this, call \hldestopts without the !, for example:

     $$\hldestopts[eq]{raise=2.5\normalbaselineskip}
     ...
     $$

The display commands ($$) implicitly put the entire formula inside a (TeX) group (\begingroup...\endgroup), so you do not need to isolate the setting of the raise option---it will be restored after the closing $$.

Initially, Eplain sets the option lists for almost all groups to empty, so that the groups fall back on the default values for all options.  The one exception to this rule is the `eq' destgroup, whose initial option list contains one setting:

     raise=1.7\normalbaselineskip

This setting usually accommodates the large operators, which often appear in displayed math.

Turning hyperlinks on/off
=========================

Links and/or destinations can be turned on or off globally by disabling the low-level commands, or for each group individually.

All these settings are local to the current (TeX) group, so if you want to enable or disable links/destinations temporarily, you can do so inside a \begingroup...\endgroup block; when the group ends, the previous settings are restored.

Turning low-level commands on/off
---------------------------------

The low-level commands \hlstart, \hlend and \hldest can be turned on/off with the following commands:

     \hldeston
     \hldestoff
     \hlon
     \hloff

See Hyperlink driver nolinks, for the implications of using these commands to disable hyperlinks for the entire document.

Turning hyperlinks on/off for a group
-------------------------------------

If you want to disable links/destinations produced by certain groups, you can give a list of the groups as an optional argument to these commands:

     \hldeston[GROUPS]
     \hldestoff[GROUPS]
     \hlon[GROUPS]
     \hloff[GROUPS]

where GROUPS is the list of linkgroups/destgroups.  This list can contain two special groups.  The empty group switches the low-level commands (see Turning low-level commands on/off), and the star (*) group operates on all defined groups.

Note that turning off the low-level commands disables all hyperlinks globally, including groups which have them enabled.  Turning off certain linkgroups/destgroups records the fact that the macros in the group should not produce links/destinations.  To illustrate the distinction, assume that all links are on; after the following sequence of commands:

     \hloff
     \hloff[eq]
     \hlon

all links are on except for the `eq' linkgroup.