path: root/Master/texmf-dist/doc/eplain/base/hlink.texi

@c This is part of the Eplain manual.  Public domain.

@node Hyperlinks
@chapter Hyperlinks

@cindex links, hypertext
@cindex hypertext links
This chapter describes the support which Eplain provides for hypertext
links (@dfn{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.

@menu
* Introduction to hyperlinks::
* Explicit hyperlinks::
* Implicit hyperlinks::
* Hyperlink drivers::
* Setting hyperlink types and options::
* Turning hyperlinks on/off::
@end menu


@node Introduction to hyperlinks
@section Introduction to hyperlinks

@cindex hyperlink drivers
@cindex drivers, hyperlink
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
@findex special
@code{\special} primitive can be used to instruct @TeX{} to write
special directives into its @file{.dvi} output file.  These directives
are not interpreted by @TeX{} in any way; they are intended for programs
which process the @file{.dvi} files produced by @TeX{}, be it printing
or converting to other formats, such as
@pindex .ps @r{files}
@pindex .pdf @r{files}
@file{.ps} or @file{.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 pdf@TeX{} engine, which is capable of producing
@file{.pdf} files directly from the @TeX{} source, skipping the
@file{.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 @dfn{hyperlink drivers} come
into play.

In order for Eplain to generate proper commands, Eplain has to know
two things: which engine or @file{.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, @code{pdftex} and @code{dvipdfm}, named after
the programs which process the hyperlink commands,
@pindex pdftex
pdf@TeX{} and
@pindex dvipdfm
dvipdfm.  Therefore, Eplain can only produce hyperlink commands for one
of these two programs---except that the extended @code{dvipdfmx} program
can be used as well as the original @code{dvipdfm}, since they are
compatible.

To tell Eplain which @file{.dvi} processor or extended @TeX{} engine you
are using, use the command
@findex enablehyperlinks
@code{\enablehyperlinks}.

For example:

@example
\enablehyperlinks
@end example

@noindent instructs Eplain to attempt to automatically detect which
driver to use, as follows: if it detects pdf@TeX{} in PDF mode, it
loads the @code{pdftex} driver.  If it does not detect pdf@TeX{} in
PDF mode, the @code{dvipdfm} driver is loaded.  The detection is based
on the
@findex ifpdf
@code{\ifpdf} switch (@pxref{Checking for PDF output}).

If necessary, you can explicitly specify the driver name:

@example
\enablehyperlinks[pdftex]
@end example

@noindent will start producing hyperlinks under the assumption that
you are using pdf@TeX{}.

Eplain does not produce any hyperlinks until you explicitly enable
them with @code{\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 pdf@TeX{} or
@code{dvipdfm}, which does not understand their hyperlink commands.

@subheading Concepts and Terminology

In general, hyperlinks work as follows.  You mark some place in your
document as a hyperlink destination, associating a @dfn{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 (@ref{Explicit hyperlinks}, and @ref{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
@dfn{hyperlinks}.  We will use the terms @dfn{links} and
@dfn{destinations} in cases when we need to refer specifically to
links or destinations.

@cindex link type
@cindex destination type
@cindex type, link and destination
Hyperlink drivers provide several kinds of links and destinations.  We
will refer to them as @dfn{link types} and @dfn{destination types}.

For example, one of the destination types that the @code{pdftex}
driver provides is the @samp{xyz} type; when the user follows a link
pointing to an @samp{xyz} destination, the exact location marked by
that destination is displayed.  Another destination type provided by
the @code{pdftex} driver is the @samp{fit} type; when the user follows
a link pointing to a @samp{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
@code{pdftex} driver, the usual link type used to refer to
destinations in the current document is called @samp{name}.  You can
also create a link pointing to another local document (by using the
@samp{filename} link type) or to a URL (by using the @samp{url} link
type).

@cindex link options
@cindex destination options
@cindex options, link and destination
In addition, each hyperlink driver supports a number of destination and
link @dfn{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).

@xref{Hyperlink drivers}, for the description of hyperlink types and
options supported by the drivers.  @xref{Setting hyperlink types and
options}, for the information on how to set hyperlink options.


@node Explicit hyperlinks
@section Explicit hyperlinks

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

@example
\hldest@{@var{type}@}@{@var{options}@}@{@var{label}@}
@end example

@noindent Here @var{type} is one of the destination types supported by
the hyperlink driver (@pxref{Hyperlink drivers}), @var{options} is a
comma-separated list of option assignments, and @var{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 @code{pdftex} driver, the command

@example
\hldest@{xyz@}@{zoom=2000@}@{index@}
@end example

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

@findex hlstart
@findex hlend
Another command, @code{\hlstart}, paired with @code{\hlend}, turns all
intervening material into a link:

@example
\hlstart@{@var{type}@}@{@var{options}@}@{@var{label}@} @dots{} \hlend
@end example

@noindent Here @var{type}, @var{options} and @var{label} have the same
meaning as for @code{\hldest}.  Continuing the previous example,

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

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

Both @code{\hldest} and @code{\hlstart} ignore following spaces.

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

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

@noindent is functionally equivalent to the previous example.


@node Implicit hyperlinks
@section Implicit hyperlinks

@cindex implicit hyperlinks
@cindex hyperlinks, implicit
@dfn{Implicit hyperlinks} are hyperlinks created implicitly by various
Eplain macros, such as the macros for citations, cross-references,
indexing, etc.

@cindex link group
@cindex linkgroup
@cindex group, link
@cindex destination group
@cindex destgroup
@cindex group, destination
All such macros are divided into @dfn{link groups} and
@dfn{destination groups} (or @dfn{linkgroups} and @dfn{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.

@xref{Setting hyperlink types and options}, for information on how to
set parameters for a group.

Here is the list of the linkgroups:

@display
cite, ref, xref, eq, idx, foot, footback, url.
@end display

And here are the destgroups:

@display
bib, li, definexref, xrdef, eq, idx, foot, footback.
@end display

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

@menu
* URL hyperlinks::                  url
* Citation hyperlinks::             cite, bib
* List hyperlinks::                 li
* Cross-reference hyperlinks::      definexref, ref
* Page reference hyperlinks::       xrdef, xref
* Equation reference hyperlinks::   eq
* Index hyperlinks::                idx
* Footnote hyperlinks::             foot, footback
* Contents hyperlinks::
@end menu


@node URL hyperlinks
@subsection URL hyperlinks:  url

@cindex URL hyperlink
@cindex hyperlinks, URL
@cindex group `url'
@cindex linkgroup `url'
The `url' linkgroup covers the
@findex url @r{(hyperlinks)}
@code{\url} command from the @LaTeX{} package
@pindex url.sty
@file{url} (@pxref{Packages known to work}), as well as any new
@code{\url}-like commands you define.  The type for this linkgroup is
set to @samp{url} by the drivers which support this link type.
@samp{url} links use the parameter to the @code{\url} command as the URL
to point to.

You may be using the @code{\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
@code{\hloff[url]} (@pxref{Turning hyperlinks on/off for a group}).


@node Citation hyperlinks
@subsection Citation hyperlinks:  cite, bib

@cindex citations, hyperlinks
@cindex hyperlinks, citations
@cindex group `cite'
@cindex linkgroup `cite'
@findex cite @r{(hyperlinks)}
The `cite' linkgroup includes only the @code{\cite} command
(@pxref{Citations}).  @code{\cite} turns each of the references in the
list into a link pointing to the respective bibliography entry
produced by the @code{\bibliography} command.

@cindex bibliography, hyperlinks
@cindex hyperlinks, bibliography
@cindex group `bib'
@cindex destgroup `bib'
@findex bibliography @r{(hyperlinks)}
The `bib' destgroup includes the macros related to the
@code{\bibliography} command (@pxref{Citations}).  @code{\bibliography}
inputs a @file{.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.


@node List hyperlinks
@subsection List hyperlinks:  li

@cindex lists, hyperlinks
@cindex hyperlinks, lists
@findex li @r{(hyperlinks)}
@cindex group `li'
@cindex destgroup `li'
The `li' destgroup consists of the @code{\li} command (@pxref{Lists}),
which defines a destination if you supply the optional argument
(cross-reference label).  This label is also used as the hyperlink
label.


@node Cross-reference hyperlinks
@subsection Cross-reference hyperlinks:  definexref, ref

@findex definexref @r{(hyperlinks)}
@cindex cross-references, hyperlinks
@cindex hyperlinks, cross-references
@cindex group `definexref'
@cindex destgroup `definexref'
The `definexref' destgroup is for the @code{\definexref} command
(@pxref{Defining generic references}).  @code{\definexref} defines a
destination using the cross-reference label (the first argument) as the
hyperlink label.

@cindex group `ref'
@cindex linkgroup `ref'
The `ref' linkgroup includes @code{\refn} and @code{\xrefn} (they are
synonyms), @code{\ref}, and @code{\refs} (@pxref{Using generic
references}).

@findex refn @r{(hyperlinks)}
@findex xrefn @r{(hyperlinks)}
@code{\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
@findex reftie
@code{\reftie} to the reference and become part of the link.

@findex ref @r{(hyperlinks)}
@code{\ref} works similarly to @code{\refn}.  It takes an optional
argument, which is treated the same way as the optional argument to
@code{\refn}.  In addition, @code{\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
@findex reftie
@code{\reftie} to the preceding word.  The optional argument is
separated from the class word by
@findex refspace
@code{\refspace}.

@findex refs @r{(hyperlinks)}
Unlike @code{\ref}, @code{\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.


@node Page reference hyperlinks
@subsection Page reference hyperlinks:  xrdef, xref

@findex xrdef @r{(hyperlinks)}
@cindex page reference hyperlink
@cindex hyperlinks, page references
@cindex group `xrdef'
@cindex destgroup `xrdef'
The `xrdef' destgroup is for @code{\xrdef} (@pxref{Page references}).
@code{\xrdef} defines a destination using cross-reference label as the
hyperlink label.

@findex xref @r{(hyperlinks)}
@findex refspace
@findex xrefpageword
@cindex group `xref'
@cindex linkgroup `xref'
The `xref' linkgroup includes the @code{\xref} command (@pxref{Page
references}).  @code{\xref} turns its optional argument (followed by
@code{\refspace}), @code{\xrefpageword} and the cross-reference (page
number) into a link, using the cross-reference label as the hyperlink
label.


@node Equation reference hyperlinks
@subsection Equation reference hyperlinks:  eq

@findex eqdef @r{(hyperlinks)}
@findex eqdefn @r{(hyperlinks)}
@findex eqsubdef @r{(hyperlinks)}
@findex eqsubdefn @r{(hyperlinks)}
@cindex equations, hyperlinks
@cindex hyperlinks, equations
@cindex group `eq'
@cindex destgroup `eq'
All commands that define equation labels are part of the `eq' destgroup.
These are @code{\eqdef}, @code{\eqdefn}, @code{\eqsubdef} and
@code{\eqsubdefn} (@pxref{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.

@findex phantomeqlabel
@findex phantomeqnumber
The command @code{\phantomeqlabel} is called to generate hyperlink
labels for the empty-labeled equations.  By default, it produces the
labels in the format @samp{PHEQ@var{number}}, where @var{number} comes
from the count register @code{\phantomeqnumber}; this count register is
incremented at every empty-labeled equation definition.

@findex eqref
@findex eqrefn
@findex reftie
@cindex group `eq'
@cindex linkgroup `eq'
The commands @code{\eqref} and @code{\eqrefn} (@pxref{Equation
references}) form the `eq' linkgroup.  These commands take an optional
argument, which, when present, is tied with @code{\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.


@node Index hyperlinks
@subsection Index hyperlinks:  idx

@findex idx @r{(hyperlinks)}
@findex idxname @r{(hyperlinks)}
@findex idxmarked @r{(hyperlinks)}
@findex idxsubmarked @r{(hyperlinks)}
@cindex index hyperlink
@cindex hyperlinks, index
@cindex group `idx'
@cindex linkgroup `idx'
@cindex destgroup `idx'
All indexing commands (@code{\idx}, @code{\idxname}, @code{\idxmarked},
@code{\idxsubmarked} and their silent equivalents, @pxref{Indexing
commands}) form the `idx' destgroup.  The `idx' linkgroup consists of
the macros which are used to typeset the index when you say
@findex readindexfile @r{(hyperlinks)}
@code{\readindexfile@{@var{index-letter}@}} (@pxref{Typesetting an
index}).

@pindex makeindex
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
@pindex .idx @r{files}
@file{.idx} file of the following general form:

@example
\indexentry@{@var{entry}|@var{pagemarkup}@}@{@var{pageno}@}
@end example

@noindent where @var{entry} is the index entry (converted into the
internal format that MakeIndex understands), @var{cs} is the markup
command you specified with the @code{pagemarkup=@var{cs}} optional
argument to the indexing commands (@pxref{Modifying index entries}),
and @var{pageno} is the page number on which the term appeared.  When
processing the @file{.idx} file, MakeIndex makes the page number an
argument to the page markup command (``encapsulates'' the page
number), so the page number in the
@pindex .ind @r{files}
@file{.ind} file appears as @code{\@var{cs}@{@var{pageno}@}}.  Eplain
internally replaces the @var{cs} command name with its own command,
which, in addition to calling the original @code{\@var{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.

@menu
* Exact destinations for index terms::
* Page destinations for index terms::
* Choosing destination placement::
* Index page list and page range parsers::
* Hyperlinks in see and see also entries::
@end menu


@node Exact destinations for index terms
@subsubsection 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 @file{.idx} file as part of
the @code{\indexentry} command.  The @code{\indexentry} line that Eplain
writes to the @file{.idx} file becomes

@example
\indexentry@{@var{entry}|hlidx@{@var{label}@}@{@var{cs}@}@}@{@var{pageno@}}
@end example

@findex hlidx
@noindent where @code{\hlidx} is the command that is defined by Eplain
to take three arguments:  a hyperlink label (@var{label}), a name of
page number encapsulator (@var{cs}) and a page number (@var{pageno}).
In the @file{.ind} file that MakeIndex will generate, the page number
will now appear as

@example
\hlidx@{@var{label}@}@{@var{cs}@}@{@var{pageno}@}
@end example

@noindent The result of this command is
@code{\@var{cs}@{@var{pageno}@}}, wrapped up into a link pointing to
@var{label} destination.

The hyperlink labels for the index terms are generated by the
@findex hlidxlabel
@code{\hlidxlabel} command, by default in the format
@samp{IDX@var{number}}, where @var{number} is the value of the count
register
@findex hlidxlabelnumber
@code{\hlidxlabelnumber}.  This count register is incremented at each
index term.

@cindex exact index hyperlinks
@cindex index, exact hyperlinks
@cindex hyperlinks, index, exact
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 @emph{all} index entries as distinct, because
each one contains a (unique) hyperlink label.  This disadvantage can be
partially overcome by the script
@pindex idxuniq
@cindex filtering index entries with hyperlinks
@cindex hyperlinks, filtering index entries
@file{idxuniq} distributed with Eplain in the @file{util} directory.
This script filters out @code{\indexentry} lines differing only in the
hyperlink label but identical otherwise.  You should process the
@file{.idx} with this script before passing it on to MakeIndex.  For
example:

@example
prompt$ ./idxuniq file.idx | makeindex > file.ind
@end example

@noindent 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; @file{idxuniq} will not filter out the second entry).


@node Page destinations for index terms
@subsubsection 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 @emph{page} on which the term appeared.  On top of each
page containing an index term, Eplain defines a destination with label
produced by
@findex hlidxpagelabel
@code{\hlidxpagelabel}.  The @code{\hlidxpagelabel} command takes a
single argument (page number @var{number}) and by default produces the
label in the format @samp{IDXPG@var{number}}.

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

@example
\indexentry@{@var{entry}|hlidxpage@{@var{cs}@}@}@{@var{pageno@}}
@end example

@findex hlidxpage
@noindent where @code{\hlidxpage} is the command that is defined by Eplain
to take two arguments:  a name of page number encapsulator (@var{cs})
and a page number (@var{pageno}).  In the @file{.ind} file that
MakeIndex will generate, the page number will appear as

@example
\hlidxpage@{@var{cs}@}@{@var{pageno}@}
@end example

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.

@cindex index, parsing page numbers
@cindex page range, parsing
@cindex page list, parsing
@cindex parsing page numbers
Another disadvantage is that this approach depends on the page range and
page list separators which MakeIndex was configured to output.
@code{\hlidxpage} must be able to parse the first page number in a page
range like @samp{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 @code{\hlidxpage} can be passed, e.g.,
@samp{1, 2} for the @var{pageno}.  In this last case, @code{\hlidxpage}
splits the two page numbers, applies @code{\@var{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 (@code{\@var{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 (@samp{, }) and
two dashes (@samp{--}), respectively.  If you customize MakeIndex to use
different delimiters, you must not forget to let Eplain know about them
with the commands

@example
\setidxpagelistdelimiter@{@var{list-delim}@}
\setidxpagerangedelimiter@{@var{page-delim}@}
@end example

@noindent (@pxref{Page list and page range parsers}).


@node Choosing destination placement
@subsubsection Choosing destination placement

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

For example:

@example
\enablehyperlinks[idxexact]
@end example

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


@node Index page list and page range parsers
@subsubsection Index page list and page range parsers

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


@node Hyperlinks in see and see also entries
@subsubsection Hyperlinks in see and see also entries

@cindex hyperlinks, see and see also index entries
@cindex index, hyperlinks in see and see also entries
@cindex see also index entries and hyperlinks
@cindex see, and index entries, hyperlinks
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
@findex indexsee
@code{\indexsee} and
@findex indexseealso
@code{\indexseealso} to corresponding index entries.  But if desired,
this can be implemented with @code{\hldest} and @code{\hlstart}
(@pxref{Explicit hyperlinks}); for example:

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


@node Footnote hyperlinks
@subsection Footnote hyperlinks:  foot, footback

@cindex footnotes, hyperlinks
@cindex hyperlinks, footnotes
@cindex group `foot'
@cindex group `footback'
@cindex linkgroup `foot'
@cindex linkgroup `footback'
@cindex destgroup `foot'
@cindex destgroup `footback'
The `foot' link and destination groups include the
@findex numberedfootnote @r{(hyperlinks)}
@code{\numberedfootnote} and
@findex footnote @r{(hyperlinks)}
@code{\footnote} macros (@pxref{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
@findex hlfootlabel
@code{\hlfootlabel} and
@findex hlfootbacklabel
@code{\hlfootbacklabel}.  The default formats for the labels are
@samp{FOOT@var{number}} and @samp{FOOTB@var{number}}, respectively,
where @var{number} is the value of the count register
@findex hlfootlabelnumber
@code{\hlfootlabelnumber}.  This register is incremented at every
footnote.


@node Contents hyperlinks
@subsection Contents hyperlinks

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


@node Hyperlink drivers
@section 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 @cite{Portable Document Format
Reference Manual Version@tie{}1.3}, March@tie{}11, 1999.

@menu
* Options supported by all drivers::
* Hyperlink drivers pdftex and dvipdfm::
* Hyperlink driver nolinks::
@end menu


@node Options supported by all drivers
@subsection Options supported by all drivers

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


@subsubheading Destination options supported by all drivers

@cindex destination options, common
@cindex options, destination, common
@table @code
@item raise
@findex raise @r{(hyperlink option)}
@cindex raising hyperlink destinations
@cindex hyperlink destination, raising
@cindex destinations, raising
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
@findex normalbaselineskip
@code{\normalbaselineskip} (or some fraction of it, like
@code{1.7\normalbaselineskip}) makes the setting appropriate for
different point sizes, in case your document uses more than one.

The default setting is @code{\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
@code{1.7\normalbaselineskip},
@cindex mathematics displays, hyperlinks
@cindex displayed math and hyperlinks
@cindex large operators and hyperlinks
@cindex hyperlinks, large operators
@cindex destinations, large operators
to accommodate the usual cases of large operators in displayed math.

Example:  @code{\hldestopts[eq]@{raise=2.5\normalbaselineskip@}}
@end table


@subsubheading Link options supported by all drivers
@cindex link options, common
@cindex options, link, common

@table @code
@item colormodel
@itemx color
@findex colormodel @r{(hyperlink option)}
@findex color @r{(hyperlink option)}
@cindex color, hyperlinks
These two options define the color to be used for rendering the link
text.  The colors are used only when a @code{\color} command is defined,
e.g., by loading the @LaTeX{} `color' package (@pxref{Packages known to
work}).  The @code{\color} command is called as
@code{\color[@var{colormodel}]@{@var{color}@}}, where @var{colormodel}
and @var{color} are the definitions of the @code{colormodel} and
@code{color} options, respectively.  However, if @var{colormodel} is
empty, the optional argument to @code{\color} is omitted; and if
@var{color} is empty, the @code{\color} command is omitted altogether.
The default setting is @code{@var{colormodel}=cmyk} and
@code{@var{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
@code{\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 @code{\definecolor} and using the new color name with
an empty @var{colormodel} (see examples below).

Examples:
@example
\hlopts@{colormodel=,color=blue@}% predefined color
\definecolor@{mycolor@}@{rgb@}@{.3,.8,.95@}
\hlopts@{colormodel=,color=mycolor@}% custom color
\hlopts@{colormodel=gray,color=.4@}
@end example
@end table


@node Hyperlink drivers pdftex and dvipdfm
@subsection Hyperlink drivers @code{pdftex} and @code{dvipdfm}

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

@menu
* Destination types for pdftex and dvipdfm::
* Destination options for pdftex and dvipdfm::
* Link types for pdftex and dvipdfm::
* Link options for pdftex and dvipdfm::
@end menu


@node Destination types for pdftex and dvipdfm
@subsubsection Destination types for @code{pdftex} and @code{dvipdfm}

@cindex destination types, @code{pdftex}
@cindex destination types, @code{dvipdfm}
@cindex types, destination, @code{pdftex}
@cindex types, destination, @code{dvipdfm}
@cindex @code{pdftex}, destination types
@cindex @code{dvipdfm}, destination types
@table @code
@item xyz
@findex xyz @r{(destination type)}
``Current position''.  The option
@findex zoom @r{(destination option)}
@code{zoom} specifies magnification to use (zero or empty means leave
magnification unchanged, which is the default).  This is the default
type.

For @code{dvipdfm}:  the options
@findex left @r{(destination option)}
@code{left} and
@findex top @r{(destination option)}
@code{top} specify position coordinates to use (empty options mean
current position coordinate, which is the default).

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

@item fit
@findex fit @r{(destination type)}
Fit the page to the window.

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

@item fith
@findex fith @r{(destination type)}
Fit the width of the page to the window.

For @code{dvipdfm}:  the
@findex top @r{(destination option)}
@code{top} option specifies vertical position (default is empty, meaning
current position).

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

@item fitv
@findex fitv @r{(destination type)}
Fit the height of the page to the window.

For @code{dvipdfm}:  The option
@findex left @r{(destination option)}
@code{left} specifies horizontal position (default is empty, meaning
current position).

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

@item fitb
@findex fitb @r{(destination type)}
Fit the page's bounding box to the window.

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

@item fitbh
@findex fitbh @r{(destination type)}
Fit the width of the page's bounding box to the window.

For @code{dvipdfm}:  the option
@findex top @r{(destination option)}
@code{top} specifies vertical position (default is empty, meaning
current position).

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

@item fitbv
@findex fitbv @r{(destination type)}
Fit the height of the page's bounding box to the window.

For @code{dvipdfm}:  the option
@findex left @r{(destination option)}
@code{left} specifies horizontal position (default is empty, meaning
current position).

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

@item fitr
@findex fitr @r{(destination type)}
For @code{pdftex}:  fit the rectangle specified by the options
@findex width @r{(destination option)}
@code{width},
@findex height @r{(destination option)}
@code{height} and
@findex depth @r{(destination option)}
@code{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 @code{dvipdfm}:  fit the rectangle specified by the options
@findex left @r{(destination option)}
@code{left},
@findex bottom @r{(destination option)}
@code{bottom},
@findex right @r{(destination option)}
@code{right} and
@findex top @r{(destination option)}
@code{top} (in
@cindex PostScript point
PostScript points, 72@tie{}points per inch) in the window.  For
dimensions set to empty, current position coordinate is substituted
(these are the defaults).

Example for @code{pdftex}:

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

Example for @code{dvipdfm}:

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

@item raw
@findex raw @r{(destination type)}
The destination specification (in the form of a pdf@TeX{} command or a
dvipdfm @code{\special}) is taken from the command sequence
@code{\@var{cs}}, where @var{cs} is the value of the
@findex cmd @r{(destination option)}
@code{cmd} option.  In the definition of @code{\@var{cs}}, use
@findex @@hllabel
@code{\@@hllabel} to refer to the hyperlink label.  This option is
intended to be used with destgroups (@pxref{Setting hyperlink types and
options}), as it does not make sense to use it in a direct call to
@findex hldest
@code{\hldest}---you can just call the raw command.

Example for @code{pdftex}:

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

Example for @code{dvipdfm}:

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


@node Destination options for pdftex and dvipdfm
@subsubsection Destination options for @code{pdftex} and @code{dvipdfm}

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


@subsubheading Common destination options

@table @code
@item cmd
@findex cmd @r{(destination option)}
Name of the macro (without the leading @samp{\}) containing a
pdf@TeX{} command or a dvipdfm @code{\special} for the @code{raw}
destination.

For an example of usage, @pxref{Destination types for pdftex and
dvipdfm}, description of the @code{raw} destination.

@item zoom
@findex zoom @r{(destination option)}
@cindex destinations, magnification
@cindex hyperlink destination, magnification
@cindex magnification, hyperlink destination
@cindex zooming, hyperlink destination
Magnification ratio times 1000 (like @TeX{}'s scale factor).
Zero or empty means leave magnification unchanged, which is the
default.

Example:  @code{\hldest@{xyz@}@{zoom=2000@}@{dest123@}}
@end table


@subsubheading @code{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).

@table @code
@item depth
@findex depth @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Depth of the fit rectangle for the @code{fitr} destination.

@item height
@findex height @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Height of the fit rectangle for the @code{fitr} destination.

@item width
@findex width @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Width of the fit rectangle for the @code{fitr} destination.

Example:

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


@subsubheading @code{dvipdfm}-specific destination options

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

@table @code
@item bottom
@findex bottom @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Bottom position coordinate of a box specification for the various
destination types.

@item left
@findex left @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Left position coordinate of a box specification for the various
destination types.

@item right
@findex right @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Right position coordinate of a box specification for the various
destination types.

@item top
@findex top @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Top position coordinate of a box specification for the various
destination types.

Example:

@example
\hldest@{fitr@}@{left=72,bottom=72,right=720,top=360@}@{dest123@}
@end example
@end table


@node Link types for pdftex and dvipdfm
@subsubsection Link types for @code{pdftex} and @code{dvipdfm}

@cindex link types, @code{pdftex}
@cindex link types, @code{dvipdfm}
@cindex types, link, @code{pdftex}
@cindex types, link, @code{dvipdfm}
@cindex @code{pdftex}, link types
@cindex @code{dvipdfm}, link types
Link types are the same for the @code{pdftex} and @code{dvipdfm}
drivers, except that the @code{pdftex} driver provides one additional
link type @code{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 pdf@TeX{} commands.


@subsubheading Common link types

@table @code
@item name
@findex name @r{(hyperlink type)}
@cindex named destination
@cindex destinations, named
@cindex hyperlink destination, named
Go to a ``named destination''.  The label is the destination name.
All destinations created with @code{\hldest} are named destinations.
This is the default type.

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

@item page
@findex page @r{(hyperlink type)}
@cindex page destination
@cindex destinations, page
@cindex hyperlink destination, page
Go to a page.  The label is the page number (counting from@tie{}1).
Page fitting is specified by the
@findex pagefit @r{(hyperlink option)}
@code{pagefit} option.

Example:

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

@item filename
@findex filename @r{(hyperlink type)}
@cindex file, hyperlink to
@cindex destinations, in another file
@cindex hyperlinks, to another file
Go to a named destination in another file.  The label is the
destination name.  The file name is specified by the
@findex file @r{(hyperlink option)}
@code{file} option.  Page fitting is specified by the
@findex pagefit @r{(hyperlink option)}
@code{pagefit} option.  The
@findex newwin @r{(hyperlink option)}
@code{newwin} option specifies whether the destination document is
opened in the same window or in a new window.

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

@item filepage
@findex filepage @r{(hyperlink type)}
@cindex file, hyperlink to
@cindex destinations, in another file
@cindex hyperlinks, to another file
Go to a page in another file.  The label is the page number (counting
from@tie{}1).  The file name is specified by the
@findex file @r{(hyperlink option)}
@code{file} option.  Page fitting is specified by the
@findex pagefit @r{(hyperlink option)}
@code{pagefit} option.  The
@findex newwin @r{(hyperlink option)}
@code{newwin} option specifies whether the destination document is
opened in the same window or in a new window.

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

@item url
@findex url @r{(hyperlink type)}
@cindex URL hyperlink
@cindex destinations, URL
@cindex hyperlinks, URL
Go to a URL.  The label is the URL.

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

@item raw
@findex raw @r{(hyperlink type)}
The link specification (in the form of a pdf@TeX{} command or a dvipdfm
@code{\special} primitive) is taken from the command sequence
@code{\@var{cs}}, where @var{cs} is the value of the
@findex cmd @r{(hyperlink option)}
@code{cmd} option.  This option is intended to be used with linkgroups
(@pxref{Setting hyperlink types and options}), as it does not make sense
to use it in a direct call to
@findex hlstart
@code{\hlstart}---you can just call the raw command.

Example for @code{pdftex}:

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

Example for @code{dvipdfm}:

@example
% 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@}
@end example
@end table

@subsubheading @code{pdftex}-specific link types

@table @code
@item num
@findex num @r{(hyperlink type)}
@cindex numbered destination
@cindex destinations, numbered
@cindex hyperlink destination, numbered
Go to a ``numbered destination''.  The label is the destination
number.

Example:  @code{\hlstart@{num@}@{@}@{123@}Link to 123\hlend}
@end table


@node Link options for pdftex and dvipdfm
@subsubsection Link options for @code{pdftex} and @code{dvipdfm}

@cindex link options, @code{pdftex}
@cindex link options, @code{dvipdfm}
@cindex options, link, @code{pdftex}
@cindex options, link, @code{dvipdfm}
@cindex @code{pdftex}, link options
@cindex @code{dvipdfm}, link options
Link options are mostly the same for the @code{pdftex} and
@code{dvipdfm} drivers.  The @code{pdftex} driver has additional
options to specify link dimensions.


@subsubheading Common link options

@table @code
@item bcolor
@findex bcolor @r{(hyperlink option)}
@cindex hyperlink border color
@cindex border color, hyperlink
@cindex color, hyperlink border
Border color.  An array of three numbers in the range 0 to 1,
representing a color in DeviceRGB@.

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

@item bdash
@findex bdash @r{(hyperlink option)}
@cindex dashed hyperlink border
@cindex hyperlinks, border style
@cindex border style, hyperlink
Array of numbers representing on and off stroke lengths for drawing
dashes.

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

@item bstyle
@findex bstyle @r{(hyperlink option)}
@cindex solid hyperlink border
@cindex dashed hyperlink border
@cindex beveled hyperlink border
@cindex inset hyperlink border
@cindex underline hyperlink border
@cindex hyperlinks, border style
@cindex style, hyperlink border
@cindex border style, hyperlink
Link border style:

@table @code
@item S
The border is drawn as a solid line.

@item D
The border is drawn with a dashed line (the dash pattern is specified
by the
@findex bdash @r{(hyperlink option)}
@code{bdash} option).

@item B
The border is drawn in a beveled style.

@item I
The border is drawn in an inset style.

@item U
The border is drawn as a line on the bottom of the link rectangle.
@end table

The default is @samp{S}.

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

@item bwidth
@findex bwidth @r{(hyperlink option)}
@cindex width, hyperlink border
@cindex hyperlinks, border width
@cindex border width, hyperlink
Border width in
@cindex PostScript point
PostScript points (72@tie{}points per inch).  The default is@tie{}1.

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

@item cmd
@findex cmd @r{(hyperlink option)}
Name of the macro (without the leading @samp{\}) containing a
pdf@TeX{} command or a dvipdfm @code{\special} for the @code{raw} link.

For an example of usage, @pxref{Link types for pdftex and dvipdfm},
description of the @code{raw} link.

@item file
@findex file @r{(hyperlink option)}
File name for the @code{filename} and @code{filepage} link types.

For an example of usage, @pxref{Link types for pdftex and dvipdfm},
description of the @code{filename} and @code{filepage} links.

@item hlight
@findex hlight @r{(hyperlink option)}
@cindex hyperlinks, highlight mode
@cindex highlight modes, hyperlink
Link border highlight modes:

@table @code
@item I
The rectangle specified by the bounding box of the link is inverted.

@item N
No highlighting is done.

@item O
The border of the link is inverted.

@item P
The region underneath the bounding box of the link is drawn inset into
the page.
@end table

The default is @samp{I}.

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

@item newwin
@findex newwin @r{(hyperlink option)}
@cindex hyperlinks, opening in a new window
@cindex new window, opening hyperlink in
For the @code{filename} and @code{filepage} links, specifies whether the destination document is
opened in the same window or in a new window.  The settings are:

@table @code
@item 0
Open in the same window.
@item @r{non-}0
Open in a new window.
@item @r{empty}
Behavior according to the viewer settings.
@end table

The default is empty.

For an example of usage, @pxref{Link types for pdftex and dvipdfm},
description of the @code{filename} and @code{filepage} links.

@item pagefit
@findex pagefit @r{(hyperlink option)}
For the @code{page} and @code{filepage links}, specifies how the page
must be fitted to the window.  @code{pagefit} specification is written
to the PDF file as is, so it must conform to the PDF standard.

For an example of usage, @pxref{Link types for pdftex and dvipdfm},
description of the @code{page} and @code{filepage} links.
@end table


@subsubheading @code{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).

@table @code
@item depth
@findex depth @r{(hyperlink option)}
@cindex hyperlink dimensions
@cindex dimensions, hyperlink
Depth of the link.

@item height
@findex height @r{(hyperlink option)}
@cindex hyperlink dimensions
@cindex dimensions, hyperlink
Height of the link.

@item width
@findex width @r{(hyperlink option)}
@cindex hyperlink dimensions
@cindex dimensions, hyperlink
Width of the link.

Example:

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


@node Hyperlink driver nolinks
@subsection Hyperlink driver @code{nolinks}

@cindex @code{nolinks}, hyperlink driver
@cindex driver @code{nolinks}
@cindex hyperlink driver @code{nolinks}
@cindex omitting hyperlinks
@cindex disabling hyperlinks
@cindex hyperlinks, disabling
@cindex destinations, disabling
@cindex spacing, preserving with hyperlinks
@cindex hyperlinks, preserving spacing
@cindex page-breaking, preserving with hyperlinks
@cindex hyperlinks, preserving page-breaking
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
@findex hloff
@code{\hloff} and
@findex hldestoff
@code{\hldestoff} (@pxref{Turning hyperlinks on/off}).

The purpose of @code{\hldestoff} and @code{\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
@code{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
@code{\special} primitives or low-level hyperlink commands.  Each such
command is placed inside a
@cindex whatsits, made by hyperlinks
@dfn{whatsit} (an internal @TeX{} object), which may introduce
legitimate breakpoints at places where none would exist without the
whatsits.  The macros @code{\hldestoff} and @code{\hloff} disable the
hyperlink macros completely, so that no whatsits are produced.

In contrast, the @code{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
@pindex color.sty
@cindex graphics collection, @LaTeX{}
@cindex @LaTeX{} graphics collection
@LaTeX{} `color' package.)

Another reason for using @code{nolinks} is that in horizontal mode
@code{\hldest} places destinations inside boxes of zero width, height,
and depth.  When you say @code{\hldestoff}, @code{\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 @code{nolinks} driver helps by
defining @code{\hldest} to produce the empty boxes.


@node Setting hyperlink types and options
@section Setting hyperlink types and options

@cindex default hyperlink type
@cindex default hyperlink options
@cindex hyperlinks, default type
@cindex hyperlinks, default options
@cindex destinations, default type
@cindex destinations, default options
You can define default types for links and destinations, which will be
used when you do not specify a type in
@findex hlstart
@code{\hlstart} or
@findex hldest
@code{\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 @code{\hlstart} or @code{\hldest}.

@cindex group, type hyperlink
@cindex group, options hyperlink
@cindex hyperlinks, group type
@cindex hyperlinks, group options
@cindex link, group type
@cindex link, group options
@cindex linkgroup, type
@cindex linkgroup, options
@cindex destinations, group type
@cindex destinations, group options
@cindex destgroup, type
@cindex destgroup, options
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
@code{\begingroup@dots{}\endgroup} block; when the group ends, the
previous settings are restored.

@menu
* Setting default types and options::
* Setting group types::
* Setting group options::
@end menu


@node Setting default types and options
@subsection Setting default types and options

@findex hltype
@findex hldesttype
The default types for links and destinations can be set with the
following commands:

@example
\hltype@{@var{type}@}
\hldesttype@{@var{type}@}
@end example

@noindent where @var{type} is one of the
link/destination types supported by the selected hyperlink driver
(@pxref{Hyperlink drivers}).

@findex hlopts
@findex hldestopts
Default values for the options can be set with the following commands:

@example
\hlopts@{@var{options}@}
\hldestopts@{@var{options}@}
@end example

@noindent where @var{options} is a comma-separated list of option
assignments in the format @samp{@var{option}=@var{value}}.  Again, what options
are allowed depends on the selected hyperlink driver.


@node Setting group types
@subsection Setting group types

@findex hltype
@findex hldesttype
@cindex group, type hyperlink
@cindex hyperlinks, group type
@cindex link, group type
@cindex linkgroup, type
@cindex destinations, group type
@cindex destgroup, type
When called with an optional argument, as in

@example
\hltype[@var{groups}]@{@var{type}@}
\hldesttype[@var{groups}]@{@var{type}@}
@end example

@noindent where @var{groups} is a comma-separated list of groups,
@code{\hltype} and @code{\hldesttype} set the type for each group from
@var{groups} to @var{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 @samp{url} by the
drivers which support this link type).

@cindex group `' (empty)
@cindex default hyperlink type
@cindex default hyperlink options
@cindex hyperlinks, default type
@cindex hyperlinks, default options
@cindex destinations, default type
@cindex destinations, default options
There are two special ``groups'' which can be used inside the
@var{groups} list.  An empty group sets the default type.  This allows
to set the default type and group types in one command, for example:

@example
\hltype[eq,]@{@var{type}@}
@end example

@noindent sets the link type for the `eq' linkgroup and the
default link type to @var{type}.

@cindex group `*'
@cindex groups, specifying all
@cindex all groups, specifying
Another special group is a star (@samp{*}) group, which signifies all
defined groups.  For example, the command

@example
\hldesttype[*,]@{@var{type}@}
@end example

@noindent sets the destination type to @var{type} for each group,
as well as the default destination type.


@node Setting group options
@subsection Setting group options

@cindex group, options hyperlink
@cindex hyperlinks, group options
@cindex link, group options
@cindex linkgroup, options
@cindex destinations, group options
@cindex destgroup, 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.

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

@example
\hlopts[@var{groups}]@{@var{options}@}
\hldestopts[@var{groups}]@{@var{options}@}
\hlopts![@var{groups}]@{@var{options}@}
\hldestopts![@var{groups}]@{@var{options}@}
@end example

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

The ``overriding'' nature of the @samp{!} 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 @samp{!}.

@findex raise @r{(hyperlink option)}
@cindex mathematics displays, hyperlinks
@cindex displayed math and hyperlinks
@cindex large operators and hyperlinks
@cindex hyperlinks, large operators
@cindex destinations, large operators
@cindex raising hyperlink destinations
For example, with displayed mathematical formulas, you often need to
adjust the @samp{raise} option for the
@cindex group `eq'
@cindex linkgroup `eq'
`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 @code{\hldestopts} without the
@samp{!}, for example:

@example
$$\hldestopts[eq]@{raise=2.5\normalbaselineskip@}
@dots{}
$$
@end example

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

@cindex option list, group
@cindex group option list
@cindex hyperlinks, group option list
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:

@example
raise=1.7\normalbaselineskip
@end example

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


@node Turning hyperlinks on/off
@section Turning hyperlinks on/off

@cindex omitting hyperlinks
@cindex disabling hyperlinks
@cindex hyperlinks, disabling
@cindex destinations, disabling
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 @code{\begingroup@dots{}\endgroup} block; when the group ends, the
previous settings are restored.

@menu
* Turning low-level commands on/off::
* Turning hyperlinks on/off for a group::
@end menu


@node Turning low-level commands on/off
@subsection Turning low-level commands on/off

@findex hldeston
@findex hldestoff
@findex hlon
@findex hloff
The low-level commands @code{\hlstart}, @code{\hlend} and
@code{\hldest} can be turned on/off with the following commands:

@example
\hldeston
\hldestoff
\hlon
\hloff
@end example

@noindent @xref{Hyperlink driver nolinks}, for the implications of using
these commands to disable hyperlinks for the entire document.


@node Turning hyperlinks on/off for a group
@subsection Turning hyperlinks on/off for a group

@cindex group, disabling hyperlinks
@cindex hyperlink group, disabling hyperlinks
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:

@example
\hldeston[@var{groups}]
\hldestoff[@var{groups}]
\hlon[@var{groups}]
\hloff[@var{groups}]
@end example

@noindent where @var{groups} is the list of linkgroups/destgroups.  This
list can contain two special groups.  The empty group switches the
low-level commands (@pxref{Turning low-level commands on/off}), and the
star (@samp{*}) 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:

@example
\hloff
\hloff[eq]
\hlon
@end example

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