@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 <>@}@} \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.