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, 0 insertions, 1860 deletions
diff --git a/Master/texmf-dist/doc/eplain/base/hlink.texi b/Master/texmf-dist/doc/eplain/base/hlink.texi
deleted file mode 100644
index 083bfa99fac..00000000000
--- a/Master/texmf-dist/doc/eplain/base/hlink.texi
+++ /dev/null
@@ -1,1860 +0,0 @@
-@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.