summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/eplain/base/hlink.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/eplain/base/hlink.texi')
-rw-r--r--Master/texmf-dist/doc/eplain/base/hlink.texi1860
1 files changed, 1860 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/eplain/base/hlink.texi b/Master/texmf-dist/doc/eplain/base/hlink.texi
new file mode 100644
index 00000000000..083bfa99fac
--- /dev/null
+++ b/Master/texmf-dist/doc/eplain/base/hlink.texi
@@ -0,0 +1,1860 @@
+@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.