diff options
Diffstat (limited to 'Master/texmf-dist/doc/eplain/base/hlink.texi')
-rw-r--r-- | Master/texmf-dist/doc/eplain/base/hlink.texi | 1860 |
1 files changed, 1860 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/eplain/base/hlink.texi b/Master/texmf-dist/doc/eplain/base/hlink.texi new file mode 100644 index 00000000000..083bfa99fac --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/hlink.texi @@ -0,0 +1,1860 @@ +@c This is part of the Eplain manual. Public domain. + +@node Hyperlinks +@chapter Hyperlinks + +@cindex links, hypertext +@cindex hypertext links +This chapter describes the support which Eplain provides for hypertext +links (@dfn{hyperlinks} for short). Hyperlinks can be created +implicitly by the cross-reference, indexing and other macros in +Eplain. Macros for constructing explicit hyperlinks are also +provided. + +@menu +* Introduction to hyperlinks:: +* Explicit hyperlinks:: +* Implicit hyperlinks:: +* Hyperlink drivers:: +* Setting hyperlink types and options:: +* Turning hyperlinks on/off:: +@end menu + + +@node Introduction to hyperlinks +@section Introduction to hyperlinks + +@cindex hyperlink drivers +@cindex drivers, hyperlink +The original @TeX{} engine has no built-in support for hyperlinks. +Many of the present-day file formats with hyperlinking capabilities +did not even exist at the time @TeX{} was written. However, @TeX{}'s +@findex special +@code{\special} primitive can be used to instruct @TeX{} to write +special directives into its @file{.dvi} output file. These directives +are not interpreted by @TeX{} in any way; they are intended for programs +which process the @file{.dvi} files produced by @TeX{}, be it printing +or converting to other formats, such as +@pindex .ps @r{files} +@pindex .pdf @r{files} +@file{.ps} or @file{.pdf}. + +Another approach is to extend the original @TeX{} engine with the +ability to generate one of the hyperlinking formats; @TeX{}'s set of +primitives can be extended to include hyperlink commands. This is the +approach used by the pdf@TeX{} engine, which is capable of producing +@file{.pdf} files directly from the @TeX{} source, skipping the +@file{.dvi} generation and processing step. + +It turns out that the sets of commands for different formats are mostly +not interchangeable, as each of the file formats has its own quirks and +capabilities. And this is where Eplain @dfn{hyperlink drivers} come +into play. + +In order for Eplain to generate proper commands, Eplain has to know +two things: which engine or @file{.dvi} processor you are using, and +the set of commands it understands. + +The knowledge about the commands that the various processors +understand is programmed into Eplain's hyperlink drivers. Eplain +provides two drivers, @code{pdftex} and @code{dvipdfm}, named after +the programs which process the hyperlink commands, +@pindex pdftex +pdf@TeX{} and +@pindex dvipdfm +dvipdfm. Therefore, Eplain can only produce hyperlink commands for one +of these two programs---except that the extended @code{dvipdfmx} program +can be used as well as the original @code{dvipdfm}, since they are +compatible. + +To tell Eplain which @file{.dvi} processor or extended @TeX{} engine you +are using, use the command +@findex enablehyperlinks +@code{\enablehyperlinks}. + +For example: + +@example +\enablehyperlinks +@end example + +@noindent instructs Eplain to attempt to automatically detect which +driver to use, as follows: if it detects pdf@TeX{} in PDF mode, it +loads the @code{pdftex} driver. If it does not detect pdf@TeX{} in +PDF mode, the @code{dvipdfm} driver is loaded. The detection is based +on the +@findex ifpdf +@code{\ifpdf} switch (@pxref{Checking for PDF output}). + +If necessary, you can explicitly specify the driver name: + +@example +\enablehyperlinks[pdftex] +@end example + +@noindent will start producing hyperlinks under the assumption that +you are using pdf@TeX{}. + +Eplain does not produce any hyperlinks until you explicitly enable +them with @code{\enablehyperlinks}. For one thing, this keeps Eplain +backward-compatible with previous releases without hyperlink support. +For another, you may be using a program other than pdf@TeX{} or +@code{dvipdfm}, which does not understand their hyperlink commands. + +@subheading Concepts and Terminology + +In general, hyperlinks work as follows. You mark some place in your +document as a hyperlink destination, associating a @dfn{hyperlink +label} with that destination. Next, somewhere within your document, +you create a hyperlink, using a label to identify the destination you +want this link to point to. A hyperlink is a region in the document +(which can take many forms, for example, text or a picture); when a +user clicks on that region, they will be taken to a place in the +document marked by the corresponding destination. The following two +sections (@ref{Explicit hyperlinks}, and @ref{Implicit hyperlinks}) +describe the macros you can use to define destinations and create +links pointing to those destinations. + +In the rest of this chapter, we will often need to refer to links and +destinations jointly, in which case we will use the term +@dfn{hyperlinks}. We will use the terms @dfn{links} and +@dfn{destinations} in cases when we need to refer specifically to +links or destinations. + +@cindex link type +@cindex destination type +@cindex type, link and destination +Hyperlink drivers provide several kinds of links and destinations. We +will refer to them as @dfn{link types} and @dfn{destination types}. + +For example, one of the destination types that the @code{pdftex} +driver provides is the @samp{xyz} type; when the user follows a link +pointing to an @samp{xyz} destination, the exact location marked by +that destination is displayed. Another destination type provided by +the @code{pdftex} driver is the @samp{fit} type; when the user follows +a link pointing to a @samp{fit} destination, the page containing that +destination is zoomed to fit into the window in which the document is +displayed. + +Similarly, drivers support various link types. For example, with the +@code{pdftex} driver, the usual link type used to refer to +destinations in the current document is called @samp{name}. You can +also create a link pointing to another local document (by using the +@samp{filename} link type) or to a URL (by using the @samp{url} link +type). + +@cindex link options +@cindex destination options +@cindex options, link and destination +In addition, each hyperlink driver supports a number of destination and +link @dfn{options}. By setting these options you can customize +hyperlink parameters (e.g., the thickness of the border drawn around a +hyperlink) or pass information to hyperlinks (for example, file name of +a document, for a link pointing to a destination in another document). + +@xref{Hyperlink drivers}, for the description of hyperlink types and +options supported by the drivers. @xref{Setting hyperlink types and +options}, for the information on how to set hyperlink options. + + +@node Explicit hyperlinks +@section Explicit hyperlinks + +@cindex explicit hyperlinks +@cindex hyperlinks, explicit +@findex hldest +Explicit hyperlinks are created by you, in the source of your +document. The simplest command is @code{\hldest}, which marks the +current position in your document as a destination: + +@example +\hldest@{@var{type}@}@{@var{options}@}@{@var{label}@} +@end example + +@noindent Here @var{type} is one of the destination types supported by +the hyperlink driver (@pxref{Hyperlink drivers}), @var{options} is a +comma-separated list of option assignments, and @var{label} is the +hyperlink label to associate with this destination. This label will +identify the destination when creating links pointing to this +destination. For example, with the @code{pdftex} driver, the command + +@example +\hldest@{xyz@}@{zoom=2000@}@{index@} +@end example + +@noindent creates a destination of type @samp{xyz} (``the current +position''), sets the magnification ratio for this destination to be +200%, and associates the label @code{index} with the destination. + +@findex hlstart +@findex hlend +Another command, @code{\hlstart}, paired with @code{\hlend}, turns all +intervening material into a link: + +@example +\hlstart@{@var{type}@}@{@var{options}@}@{@var{label}@} @dots{} \hlend +@end example + +@noindent Here @var{type}, @var{options} and @var{label} have the same +meaning as for @code{\hldest}. Continuing the previous example, + +@example +\hlstart@{name@}@{bstyle=U,bwidth=2@}@{index@} Index\hlend +@end example + +@noindent typesets the word `Index' as a link with underline border of +width@tie{}2@tie{}PostScript points, pointing to the named destination +@code{index} defined in the previous example. (The other options, like +highlight mode and border color, are determined by the defaults, +@pxref{Setting default types and options}). + +Both @code{\hldest} and @code{\hlstart} ignore following spaces. + +Both @code{\hldest} and @code{\hlstart} expand the first token of +@var{options} once, so you can save a list of options in a macro and +pass it for the @var{options}. For example: + +@example +\def\linkopts@{bstyle=U,bwidth=2@} +\hlstart@{name@}@{\linkopts@}@{index@}Index\hlend +@end example + +@noindent is functionally equivalent to the previous example. + + +@node Implicit hyperlinks +@section Implicit hyperlinks + +@cindex implicit hyperlinks +@cindex hyperlinks, implicit +@dfn{Implicit hyperlinks} are hyperlinks created implicitly by various +Eplain macros, such as the macros for citations, cross-references, +indexing, etc. + +@cindex link group +@cindex linkgroup +@cindex group, link +@cindex destination group +@cindex destgroup +@cindex group, destination +All such macros are divided into @dfn{link groups} and +@dfn{destination groups} (or @dfn{linkgroups} and @dfn{destgroups} for +short) so that parameters can be set individually for each group. For +example, all equation macros which define a destination are assigned +to the `eq' destgroup; equation macros which create a link are +assigned to the `eq' linkgroup. By setting parameters for the `eq' +linkgroup (destgroup), you can uniformly customize all links +(destinations) related to equation references, without interfering +with settings for the other groups. + +@xref{Setting hyperlink types and options}, for information on how to +set parameters for a group. + +Here is the list of the linkgroups: + +@display +cite, ref, xref, eq, idx, foot, footback, url. +@end display + +And here are the destgroups: + +@display +bib, li, definexref, xrdef, eq, idx, foot, footback. +@end display + +The following subsections describe each of the linkgroups and destgroups +and the hyperlink support provided. + +@menu +* URL hyperlinks:: url +* Citation hyperlinks:: cite, bib +* List hyperlinks:: li +* Cross-reference hyperlinks:: definexref, ref +* Page reference hyperlinks:: xrdef, xref +* Equation reference hyperlinks:: eq +* Index hyperlinks:: idx +* Footnote hyperlinks:: foot, footback +* Contents hyperlinks:: +@end menu + + +@node URL hyperlinks +@subsection URL hyperlinks: url + +@cindex URL hyperlink +@cindex hyperlinks, URL +@cindex group `url' +@cindex linkgroup `url' +The `url' linkgroup covers the +@findex url @r{(hyperlinks)} +@code{\url} command from the @LaTeX{} package +@pindex url.sty +@file{url} (@pxref{Packages known to work}), as well as any new +@code{\url}-like commands you define. The type for this linkgroup is +set to @samp{url} by the drivers which support this link type. +@samp{url} links use the parameter to the @code{\url} command as the URL +to point to. + +You may be using the @code{\url} command to typeset something other than +a URL, e.g., a path, for which you do not want a link to be created; in +that case, you can disable the `url' linkgroup with the command +@code{\hloff[url]} (@pxref{Turning hyperlinks on/off for a group}). + + +@node Citation hyperlinks +@subsection Citation hyperlinks: cite, bib + +@cindex citations, hyperlinks +@cindex hyperlinks, citations +@cindex group `cite' +@cindex linkgroup `cite' +@findex cite @r{(hyperlinks)} +The `cite' linkgroup includes only the @code{\cite} command +(@pxref{Citations}). @code{\cite} turns each of the references in the +list into a link pointing to the respective bibliography entry +produced by the @code{\bibliography} command. + +@cindex bibliography, hyperlinks +@cindex hyperlinks, bibliography +@cindex group `bib' +@cindex destgroup `bib' +@findex bibliography @r{(hyperlinks)} +The `bib' destgroup includes the macros related to the +@code{\bibliography} command (@pxref{Citations}). @code{\bibliography} +inputs a @file{.bbl} file, which contains a list of bibliography +entries. For each of the entries, a destination is defined. + +Both commands use the citation label as the hyperlink label. + + +@node List hyperlinks +@subsection List hyperlinks: li + +@cindex lists, hyperlinks +@cindex hyperlinks, lists +@findex li @r{(hyperlinks)} +@cindex group `li' +@cindex destgroup `li' +The `li' destgroup consists of the @code{\li} command (@pxref{Lists}), +which defines a destination if you supply the optional argument +(cross-reference label). This label is also used as the hyperlink +label. + + +@node Cross-reference hyperlinks +@subsection Cross-reference hyperlinks: definexref, ref + +@findex definexref @r{(hyperlinks)} +@cindex cross-references, hyperlinks +@cindex hyperlinks, cross-references +@cindex group `definexref' +@cindex destgroup `definexref' +The `definexref' destgroup is for the @code{\definexref} command +(@pxref{Defining generic references}). @code{\definexref} defines a +destination using the cross-reference label (the first argument) as the +hyperlink label. + +@cindex group `ref' +@cindex linkgroup `ref' +The `ref' linkgroup includes @code{\refn} and @code{\xrefn} (they are +synonyms), @code{\ref}, and @code{\refs} (@pxref{Using generic +references}). + +@findex refn @r{(hyperlinks)} +@findex xrefn @r{(hyperlinks)} +@code{\refn} turns the cross-reference it produces into a link, using +the cross-reference label as the hyperlink label. If an optional +argument is present, it is tied by +@findex reftie +@code{\reftie} to the reference and become part of the link. + +@findex ref @r{(hyperlinks)} +@code{\ref} works similarly to @code{\refn}. It takes an optional +argument, which is treated the same way as the optional argument to +@code{\refn}. In addition, @code{\ref} can produce a ``class word''. +Both the optional argument and the class word become part of the link, +when present. The cross-reference is tied by +@findex reftie +@code{\reftie} to the preceding word. The optional argument is +separated from the class word by +@findex refspace +@code{\refspace}. + +@findex refs @r{(hyperlinks)} +Unlike @code{\ref}, @code{\refs} does not take an optional argument and +does not make the class word part of the link, which is appropriate for +its intended use. + + +@node Page reference hyperlinks +@subsection Page reference hyperlinks: xrdef, xref + +@findex xrdef @r{(hyperlinks)} +@cindex page reference hyperlink +@cindex hyperlinks, page references +@cindex group `xrdef' +@cindex destgroup `xrdef' +The `xrdef' destgroup is for @code{\xrdef} (@pxref{Page references}). +@code{\xrdef} defines a destination using cross-reference label as the +hyperlink label. + +@findex xref @r{(hyperlinks)} +@findex refspace +@findex xrefpageword +@cindex group `xref' +@cindex linkgroup `xref' +The `xref' linkgroup includes the @code{\xref} command (@pxref{Page +references}). @code{\xref} turns its optional argument (followed by +@code{\refspace}), @code{\xrefpageword} and the cross-reference (page +number) into a link, using the cross-reference label as the hyperlink +label. + + +@node Equation reference hyperlinks +@subsection Equation reference hyperlinks: eq + +@findex eqdef @r{(hyperlinks)} +@findex eqdefn @r{(hyperlinks)} +@findex eqsubdef @r{(hyperlinks)} +@findex eqsubdefn @r{(hyperlinks)} +@cindex equations, hyperlinks +@cindex hyperlinks, equations +@cindex group `eq' +@cindex destgroup `eq' +All commands that define equation labels are part of the `eq' destgroup. +These are @code{\eqdef}, @code{\eqdefn}, @code{\eqsubdef} and +@code{\eqsubdefn} (@pxref{Equation references}). All these commands use +the equation label as the hyperlink label. However, if the equation +label is empty, they make up a (hopefully) unique hyperlink label for +the destination. This label will be used for the link when you refer to +this empty-labeled equation with one of the equation reference macros. + +@findex phantomeqlabel +@findex phantomeqnumber +The command @code{\phantomeqlabel} is called to generate hyperlink +labels for the empty-labeled equations. By default, it produces the +labels in the format @samp{PHEQ@var{number}}, where @var{number} comes +from the count register @code{\phantomeqnumber}; this count register is +incremented at every empty-labeled equation definition. + +@findex eqref +@findex eqrefn +@findex reftie +@cindex group `eq' +@cindex linkgroup `eq' +The commands @code{\eqref} and @code{\eqrefn} (@pxref{Equation +references}) form the `eq' linkgroup. These commands take an optional +argument, which, when present, is tied with @code{\reftie} to the +equation reference and becomes part of the link. The equation label is +used for the hyperlink label; if the label is empty, the link is for the +label generated for the last empty-labeled equation. + + +@node Index hyperlinks +@subsection Index hyperlinks: idx + +@findex idx @r{(hyperlinks)} +@findex idxname @r{(hyperlinks)} +@findex idxmarked @r{(hyperlinks)} +@findex idxsubmarked @r{(hyperlinks)} +@cindex index hyperlink +@cindex hyperlinks, index +@cindex group `idx' +@cindex linkgroup `idx' +@cindex destgroup `idx' +All indexing commands (@code{\idx}, @code{\idxname}, @code{\idxmarked}, +@code{\idxsubmarked} and their silent equivalents, @pxref{Indexing +commands}) form the `idx' destgroup. The `idx' linkgroup consists of +the macros which are used to typeset the index when you say +@findex readindexfile @r{(hyperlinks)} +@code{\readindexfile@{@var{index-letter}@}} (@pxref{Typesetting an +index}). + +@pindex makeindex +To create the links in index entries, Eplain uses MakeIndex's +``encapsulation'' feature. When you use an indexing macro to mark an +index term, Eplain writes out a line to the +@pindex .idx @r{files} +@file{.idx} file of the following general form: + +@example +\indexentry@{@var{entry}|@var{pagemarkup}@}@{@var{pageno}@} +@end example + +@noindent where @var{entry} is the index entry (converted into the +internal format that MakeIndex understands), @var{cs} is the markup +command you specified with the @code{pagemarkup=@var{cs}} optional +argument to the indexing commands (@pxref{Modifying index entries}), +and @var{pageno} is the page number on which the term appeared. When +processing the @file{.idx} file, MakeIndex makes the page number an +argument to the page markup command (``encapsulates'' the page +number), so the page number in the +@pindex .ind @r{files} +@file{.ind} file appears as @code{\@var{cs}@{@var{pageno}@}}. Eplain +internally replaces the @var{cs} command name with its own command, +which, in addition to calling the original @code{\@var{cs}} +encapsulator, turns the page number into a link. + +Eplain provides two approaches to linking page numbers in the index to +locations of index terms in the text. + +@menu +* Exact destinations for index terms:: +* Page destinations for index terms:: +* Choosing destination placement:: +* Index page list and page range parsers:: +* Hyperlinks in see and see also entries:: +@end menu + + +@node Exact destinations for index terms +@subsubsection Exact destinations for index terms + +In this approach, each command that marks an index term defines a unique +destination and passes its label on to the @file{.idx} file as part of +the @code{\indexentry} command. The @code{\indexentry} line that Eplain +writes to the @file{.idx} file becomes + +@example +\indexentry@{@var{entry}|hlidx@{@var{label}@}@{@var{cs}@}@}@{@var{pageno@}} +@end example + +@findex hlidx +@noindent where @code{\hlidx} is the command that is defined by Eplain +to take three arguments: a hyperlink label (@var{label}), a name of +page number encapsulator (@var{cs}) and a page number (@var{pageno}). +In the @file{.ind} file that MakeIndex will generate, the page number +will now appear as + +@example +\hlidx@{@var{label}@}@{@var{cs}@}@{@var{pageno}@} +@end example + +@noindent The result of this command is +@code{\@var{cs}@{@var{pageno}@}}, wrapped up into a link pointing to +@var{label} destination. + +The hyperlink labels for the index terms are generated by the +@findex hlidxlabel +@code{\hlidxlabel} command, by default in the format +@samp{IDX@var{number}}, where @var{number} is the value of the count +register +@findex hlidxlabelnumber +@code{\hlidxlabelnumber}. This count register is incremented at each +index term. + +@cindex exact index hyperlinks +@cindex index, exact hyperlinks +@cindex hyperlinks, index, exact +The advantage of this approach, as compared to the second approach +described below, is that links in the index point to exact locations of +the indexed terms on the page. The disadvantage of this approach is +that MakeIndex will regard @emph{all} index entries as distinct, because +each one contains a (unique) hyperlink label. This disadvantage can be +partially overcome by the script +@pindex idxuniq +@cindex filtering index entries with hyperlinks +@cindex hyperlinks, filtering index entries +@file{idxuniq} distributed with Eplain in the @file{util} directory. +This script filters out @code{\indexentry} lines differing only in the +hyperlink label but identical otherwise. You should process the +@file{.idx} with this script before passing it on to MakeIndex. For +example: + +@example +prompt$ ./idxuniq file.idx | makeindex > file.ind +@end example + +@noindent Still, this solution is not ideal, as the page-range formation +ability of MakeIndex will not work, and there will be problems of +apparently identical index entries clashing (e.g., when a range-end +entry appears on the same page as another entry with the same +definition; @file{idxuniq} will not filter out the second entry). + + +@node Page destinations for index terms +@subsubsection Page destinations for index terms + +In the second approach, Eplain does not write out any destination labels +for the index terms. Instead, Eplain writes out a wrapper for page +number encapsulator which can parse the page number and generate a link +pointing to the @emph{page} on which the term appeared. On top of each +page containing an index term, Eplain defines a destination with label +produced by +@findex hlidxpagelabel +@code{\hlidxpagelabel}. The @code{\hlidxpagelabel} command takes a +single argument (page number @var{number}) and by default produces the +label in the format @samp{IDXPG@var{number}}. + +With this approach, the @code{\indexentry} line which Eplain writes to +the @code{.idx} file looks like this: + +@example +\indexentry@{@var{entry}|hlidxpage@{@var{cs}@}@}@{@var{pageno@}} +@end example + +@findex hlidxpage +@noindent where @code{\hlidxpage} is the command that is defined by Eplain +to take two arguments: a name of page number encapsulator (@var{cs}) +and a page number (@var{pageno}). In the @file{.ind} file that +MakeIndex will generate, the page number will appear as + +@example +\hlidxpage@{@var{cs}@}@{@var{pageno}@} +@end example + +The advantage of this approach is that all features of MakeIndex are +intact. The drawback is that links in the index do not point to exact +locations of indexed terms on a page, but to the top of a page on +which the term appears. + +@cindex index, parsing page numbers +@cindex page range, parsing +@cindex page list, parsing +@cindex parsing page numbers +Another disadvantage is that this approach depends on the page range and +page list separators which MakeIndex was configured to output. +@code{\hlidxpage} must be able to parse the first page number in a page +range like @samp{1--4}. In addition, page list parsing is needed +because MakeIndex combines two consecutive page numbers in one call to +the page number encapsulator, so @code{\hlidxpage} can be passed, e.g., +@samp{1, 2} for the @var{pageno}. In this last case, @code{\hlidxpage} +splits the two page numbers, applies @code{\@var{cs}} to each of them, +and makes each of the page numbers a link to the appropriate page. Note +that this will alter typesetting slightly, because now the page list +separator (a comma followed by a space, by default) is not typeset using +the page number encapsulator (@code{\@var{cs}}). + +Eplain's defaults for the page list and page number delimiters are the +same as those in MakeIndex, a comma followed by a space (@samp{, }) and +two dashes (@samp{--}), respectively. If you customize MakeIndex to use +different delimiters, you must not forget to let Eplain know about them +with the commands + +@example +\setidxpagelistdelimiter@{@var{list-delim}@} +\setidxpagerangedelimiter@{@var{page-delim}@} +@end example + +@noindent (@pxref{Page list and page range parsers}). + + +@node Choosing destination placement +@subsubsection Choosing destination placement + +@cindex index, placement of destinations +@cindex index, destination placement +@cindex index, selecting destination placement +@cindex index, choosing destination placement +@cindex hyperlinks, index destination placement +The approach that Eplain should use for the index terms can be +selected in the +@findex enablehyperlinks +@code{\enablehyperlinks} command. The optional argument it accepts is +a comma-separated list of options. The +@findex idxexact +@code{idxexact} option selects the first approach, +@findex idxpage +@code{idxpage} the second, and +@findex idxnone +@code{idxnone} disables hyperlink support for the index terms +altogether, in case you want to stop Eplain from writing its link +wrappers into the @file{.idx} file. The default is @code{idxpage}. + +For example: + +@example +\enablehyperlinks[idxexact] +@end example + +@noindent selects the first approach (``exact index links''). + + +@node Index page list and page range parsers +@subsubsection Index page list and page range parsers + +The macros that Eplain uses to parse page lists and page ranges, +@code{\idxparselist} and @code{\idxparserange}, can sometimes be useful +when defining page number encapsulators. @xref{Page list and page range +parsers}, for the description of these commands and an example of their +usage. + + +@node Hyperlinks in see and see also entries +@subsubsection Hyperlinks in see and see also entries + +@cindex hyperlinks, see and see also index entries +@cindex index, hyperlinks in see and see also entries +@cindex see also index entries and hyperlinks +@cindex see, and index entries, hyperlinks +There is no automatic support for hyperlinks with ``see'' and ``see +also'' index entries, as there is not enough information to trace the +parameters of +@findex indexsee +@code{\indexsee} and +@findex indexseealso +@code{\indexseealso} to corresponding index entries. But if desired, +this can be implemented with @code{\hldest} and @code{\hlstart} +(@pxref{Explicit hyperlinks}); for example: + +@example +\sidx@{semantic theory of truth@@% + \leavevmode\hldest@{@}@{@}@{idx:theo truth@}semantic theory of truth@} +@dots{} +\sidx[seealso]@{truth@}[definition of]% + @{\hlstart@{@}@{@}@{idx:theo truth@}semantic theory of truth\hlend@} +@end example + + +@node Footnote hyperlinks +@subsection Footnote hyperlinks: foot, footback + +@cindex footnotes, hyperlinks +@cindex hyperlinks, footnotes +@cindex group `foot' +@cindex group `footback' +@cindex linkgroup `foot' +@cindex linkgroup `footback' +@cindex destgroup `foot' +@cindex destgroup `footback' +The `foot' link and destination groups include the +@findex numberedfootnote @r{(hyperlinks)} +@code{\numberedfootnote} and +@findex footnote @r{(hyperlinks)} +@code{\footnote} macros (@pxref{Footnotes}). The `footback' groups +include the same macros, but control parameters for links and +destinations created inside the footnote to point back to the footnote +mark within the text body. + +The macros use hyperlink labels generated by +@findex hlfootlabel +@code{\hlfootlabel} and +@findex hlfootbacklabel +@code{\hlfootbacklabel}. The default formats for the labels are +@samp{FOOT@var{number}} and @samp{FOOTB@var{number}}, respectively, +where @var{number} is the value of the count register +@findex hlfootlabelnumber +@code{\hlfootlabelnumber}. This register is incremented at every +footnote. + + +@node Contents hyperlinks +@subsection Contents hyperlinks + +@cindex table of contents, hyperlinks +@cindex contents, hyperlinks +@cindex hyperlinks, table of contents +There is currently no special support for hyperlinks in the table of +contents (@pxref{Contents}), but implementing them with the +@code{\hldest} and @code{\hlstart @dots{} \hlend} commands +(@pxref{Explicit hyperlinks}) should be possible. + + +@node Hyperlink drivers +@section Hyperlink drivers + +This section describes the hyperlink drivers: the types of hyperlinks +they support, and the options they accept. During the first reading, +you may only want to skim through this section. + +Some of the descriptions below come from @cite{Portable Document Format +Reference Manual Version@tie{}1.3}, March@tie{}11, 1999. + +@menu +* Options supported by all drivers:: +* Hyperlink drivers pdftex and dvipdfm:: +* Hyperlink driver nolinks:: +@end menu + + +@node Options supported by all drivers +@subsection Options supported by all drivers + +@cindex hyperlink options, common +This subsection describes the destination and link options which are +supported by all hyperlink drivers. + + +@subsubheading Destination options supported by all drivers + +@cindex destination options, common +@cindex options, destination, common +@table @code +@item raise +@findex raise @r{(hyperlink option)} +@cindex raising hyperlink destinations +@cindex hyperlink destination, raising +@cindex destinations, raising +Specifies how much to raise destinations above the baseline. When set +to zero or empty, destinations are placed at the baseline. + +It is usually convenient to set this option to some variable parameter, +so that the height to which destinations are raised is automatically +adjusted according to the current context. For example, setting it to +@findex normalbaselineskip +@code{\normalbaselineskip} (or some fraction of it, like +@code{1.7\normalbaselineskip}) makes the setting appropriate for +different point sizes, in case your document uses more than one. + +The default setting is @code{\normalbaselineskip}. Initially, the +destgroups do not define this option, so they fall back on the default, +except for the `eq' destgroup, for which this option is set to +@code{1.7\normalbaselineskip}, +@cindex mathematics displays, hyperlinks +@cindex displayed math and hyperlinks +@cindex large operators and hyperlinks +@cindex hyperlinks, large operators +@cindex destinations, large operators +to accommodate the usual cases of large operators in displayed math. + +Example: @code{\hldestopts[eq]@{raise=2.5\normalbaselineskip@}} +@end table + + +@subsubheading Link options supported by all drivers +@cindex link options, common +@cindex options, link, common + +@table @code +@item colormodel +@itemx color +@findex colormodel @r{(hyperlink option)} +@findex color @r{(hyperlink option)} +@cindex color, hyperlinks +These two options define the color to be used for rendering the link +text. The colors are used only when a @code{\color} command is defined, +e.g., by loading the @LaTeX{} `color' package (@pxref{Packages known to +work}). The @code{\color} command is called as +@code{\color[@var{colormodel}]@{@var{color}@}}, where @var{colormodel} +and @var{color} are the definitions of the @code{colormodel} and +@code{color} options, respectively. However, if @var{colormodel} is +empty, the optional argument to @code{\color} is omitted; and if +@var{color} is empty, the @code{\color} command is omitted altogether. +The default setting is @code{@var{colormodel}=cmyk} and +@code{@var{color}=0.28,1,1,0.35}. + +When specifying colors with several components delimited by commas +(e.g., RGB and CMYK colors in the @LaTeX{} `color' package), it is not +possible to specify the components directly in the option list of +@code{\hlopts}, because comma is the option list delimiter. With the +`color' package, it is possible to specify such colors by defining a +custom color with @code{\definecolor} and using the new color name with +an empty @var{colormodel} (see examples below). + +Examples: +@example +\hlopts@{colormodel=,color=blue@}% predefined color +\definecolor@{mycolor@}@{rgb@}@{.3,.8,.95@} +\hlopts@{colormodel=,color=mycolor@}% custom color +\hlopts@{colormodel=gray,color=.4@} +@end example +@end table + + +@node Hyperlink drivers pdftex and dvipdfm +@subsection Hyperlink drivers @code{pdftex} and @code{dvipdfm} + +@cindex @code{pdftex}, hyperlink driver +@cindex @code{dvipdfm}, hyperlink driver +@cindex driver @code{pdftex} +@cindex driver @code{dvipdfm} +@cindex hyperlink driver @code{pdftex} +@cindex hyperlink driver @code{dvipdfm} +This subsection describes link and destination types and options +supported by the @code{pdftex} and @code{dvipdfm} drivers. Many of the +hyperlink types and options are common to both drivers, so we describe +them together. + +@menu +* Destination types for pdftex and dvipdfm:: +* Destination options for pdftex and dvipdfm:: +* Link types for pdftex and dvipdfm:: +* Link options for pdftex and dvipdfm:: +@end menu + + +@node Destination types for pdftex and dvipdfm +@subsubsection Destination types for @code{pdftex} and @code{dvipdfm} + +@cindex destination types, @code{pdftex} +@cindex destination types, @code{dvipdfm} +@cindex types, destination, @code{pdftex} +@cindex types, destination, @code{dvipdfm} +@cindex @code{pdftex}, destination types +@cindex @code{dvipdfm}, destination types +@table @code +@item xyz +@findex xyz @r{(destination type)} +``Current position''. The option +@findex zoom @r{(destination option)} +@code{zoom} specifies magnification to use (zero or empty means leave +magnification unchanged, which is the default). This is the default +type. + +For @code{dvipdfm}: the options +@findex left @r{(destination option)} +@code{left} and +@findex top @r{(destination option)} +@code{top} specify position coordinates to use (empty options mean +current position coordinate, which is the default). + +Example: @code{\hldest@{xyz@}@{zoom=2000@}@{dest123@}} + +@item fit +@findex fit @r{(destination type)} +Fit the page to the window. + +Example: @code{\hldest@{fit@}@{@}@{dest123@}} + +@item fith +@findex fith @r{(destination type)} +Fit the width of the page to the window. + +For @code{dvipdfm}: the +@findex top @r{(destination option)} +@code{top} option specifies vertical position (default is empty, meaning +current position). + +Example: @code{\hldest@{fith@}@{@}@{dest123@}} + +@item fitv +@findex fitv @r{(destination type)} +Fit the height of the page to the window. + +For @code{dvipdfm}: The option +@findex left @r{(destination option)} +@code{left} specifies horizontal position (default is empty, meaning +current position). + +Example: @code{\hldest@{fitv@}@{@}@{dest123@}} + +@item fitb +@findex fitb @r{(destination type)} +Fit the page's bounding box to the window. + +Example: @code{\hldest@{fitb@}@{@}@{dest123@}} + +@item fitbh +@findex fitbh @r{(destination type)} +Fit the width of the page's bounding box to the window. + +For @code{dvipdfm}: the option +@findex top @r{(destination option)} +@code{top} specifies vertical position (default is empty, meaning +current position). + +Example: @code{\hldest@{fitbh@}@{@}@{dest123@}} + +@item fitbv +@findex fitbv @r{(destination type)} +Fit the height of the page's bounding box to the window. + +For @code{dvipdfm}: the option +@findex left @r{(destination option)} +@code{left} specifies horizontal position (default is empty, meaning +current position). + +Example: @code{\hldest@{fitbv@}@{@}@{dest123@}} + +@item fitr +@findex fitr @r{(destination type)} +For @code{pdftex}: fit the rectangle specified by the options +@findex width @r{(destination option)} +@code{width}, +@findex height @r{(destination option)} +@code{height} and +@findex depth @r{(destination option)} +@code{depth} (as a @TeX{} rule specification) in the window. For +dimensions set to empty, the corresponding value of the parent box is +used (these are the defaults). + +For @code{dvipdfm}: fit the rectangle specified by the options +@findex left @r{(destination option)} +@code{left}, +@findex bottom @r{(destination option)} +@code{bottom}, +@findex right @r{(destination option)} +@code{right} and +@findex top @r{(destination option)} +@code{top} (in +@cindex PostScript point +PostScript points, 72@tie{}points per inch) in the window. For +dimensions set to empty, current position coordinate is substituted +(these are the defaults). + +Example for @code{pdftex}: + +@example +\hldest@{fitr@}@{width=\hsize,height=.5\vsize,depth=0pt@}@{dest123@} +@end example + +Example for @code{dvipdfm}: + +@example +\hldest@{fitr@}@{left=72,bottom=72,right=720,top=360@}@{dest123@} +@end example + +@item raw +@findex raw @r{(destination type)} +The destination specification (in the form of a pdf@TeX{} command or a +dvipdfm @code{\special}) is taken from the command sequence +@code{\@var{cs}}, where @var{cs} is the value of the +@findex cmd @r{(destination option)} +@code{cmd} option. In the definition of @code{\@var{cs}}, use +@findex @@hllabel +@code{\@@hllabel} to refer to the hyperlink label. This option is +intended to be used with destgroups (@pxref{Setting hyperlink types and +options}), as it does not make sense to use it in a direct call to +@findex hldest +@code{\hldest}---you can just call the raw command. + +Example for @code{pdftex}: + +@example +\makeatletter +\def\mydest@{\pdfdest name@{\@@hllabel@} xyz@} +\hldesttype@{raw@} +\hldestopts@{cmd=mydest@} +\resetatcatcode +@end example + +Example for @code{dvipdfm}: + +@example +\makeatletter +\def\mydest@{\special@{pdf: dest (\@@hllabel) + [@@thispage /XYZ @@xpos @@ypos 0]@}@} +\hldesttype@{raw@} +\hldestopts@{cmd=mydest@} +\resetatcatcode +@end example +@end table + + +@node Destination options for pdftex and dvipdfm +@subsubsection Destination options for @code{pdftex} and @code{dvipdfm} + +@cindex destination options, @code{pdftex} +@cindex destination options, @code{dvipdfm} +@cindex options, destination, @code{pdftex} +@cindex options, destination, @code{dvipdfm} +@cindex @code{pdftex}, destination options +@cindex @code{dvipdfm}, destination options +With respect to the destination options, the @code{pdftex} and +@code{dvipdfm} differ in the way the fit rectangle is specified +(relative coordinates for @code{pdftex}, absolute coordinates for +@code{dvipdfm}). + + +@subsubheading Common destination options + +@table @code +@item cmd +@findex cmd @r{(destination option)} +Name of the macro (without the leading @samp{\}) containing a +pdf@TeX{} command or a dvipdfm @code{\special} for the @code{raw} +destination. + +For an example of usage, @pxref{Destination types for pdftex and +dvipdfm}, description of the @code{raw} destination. + +@item zoom +@findex zoom @r{(destination option)} +@cindex destinations, magnification +@cindex hyperlink destination, magnification +@cindex magnification, hyperlink destination +@cindex zooming, hyperlink destination +Magnification ratio times 1000 (like @TeX{}'s scale factor). +Zero or empty means leave magnification unchanged, which is the +default. + +Example: @code{\hldest@{xyz@}@{zoom=2000@}@{dest123@}} +@end table + + +@subsubheading @code{pdftex}-specific destination options + +The dimension options below must be specified as a @TeX{} rule +specification. When set to empty, the corresponding value +of the parent box is used (this is the default for all dimension +options). + +@table @code +@item depth +@findex depth @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Depth of the fit rectangle for the @code{fitr} destination. + +@item height +@findex height @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Height of the fit rectangle for the @code{fitr} destination. + +@item width +@findex width @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Width of the fit rectangle for the @code{fitr} destination. + +Example: + +@example +\hldest@{fitr@}@{width=\hsize,height=.5\vsize,depth=0pt@}@{dest123@} +@end example +@end table + + +@subsubheading @code{dvipdfm}-specific destination options + +The dimension options below must be specified in +@cindex PostScript point +PostScript points (72@tie{}points per inch), as a number without the +@samp{bp} unit name. When set to empty, the current position +coordinate is used (this is the default for all dimension options). + +@table @code +@item bottom +@findex bottom @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Bottom position coordinate of a box specification for the various +destination types. + +@item left +@findex left @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Left position coordinate of a box specification for the various +destination types. + +@item right +@findex right @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Right position coordinate of a box specification for the various +destination types. + +@item top +@findex top @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Top position coordinate of a box specification for the various +destination types. + +Example: + +@example +\hldest@{fitr@}@{left=72,bottom=72,right=720,top=360@}@{dest123@} +@end example +@end table + + +@node Link types for pdftex and dvipdfm +@subsubsection Link types for @code{pdftex} and @code{dvipdfm} + +@cindex link types, @code{pdftex} +@cindex link types, @code{dvipdfm} +@cindex types, link, @code{pdftex} +@cindex types, link, @code{dvipdfm} +@cindex @code{pdftex}, link types +@cindex @code{dvipdfm}, link types +Link types are the same for the @code{pdftex} and @code{dvipdfm} +drivers, except that the @code{pdftex} driver provides one additional +link type @code{num} (link to a numbered destination). dvipdfm does not +support numbered destinations, therefore it does not have this link +type. Note that all destinations created by Eplain hyperlink macros are +named destinations; to define a numbered destination, you have to use +low-level pdf@TeX{} commands. + + +@subsubheading Common link types + +@table @code +@item name +@findex name @r{(hyperlink type)} +@cindex named destination +@cindex destinations, named +@cindex hyperlink destination, named +Go to a ``named destination''. The label is the destination name. +All destinations created with @code{\hldest} are named destinations. +This is the default type. + +Example: @code{\hlstart@{name@}@{@}@{dest123@}Link to dest123\hlend} + +@item page +@findex page @r{(hyperlink type)} +@cindex page destination +@cindex destinations, page +@cindex hyperlink destination, page +Go to a page. The label is the page number (counting from@tie{}1). +Page fitting is specified by the +@findex pagefit @r{(hyperlink option)} +@code{pagefit} option. + +Example: + +@example +\hlstart@{page@}@{pagefit=/FitH 600@}@{123@}Link to page~123\hlend +@end example + +@item filename +@findex filename @r{(hyperlink type)} +@cindex file, hyperlink to +@cindex destinations, in another file +@cindex hyperlinks, to another file +Go to a named destination in another file. The label is the +destination name. The file name is specified by the +@findex file @r{(hyperlink option)} +@code{file} option. Page fitting is specified by the +@findex pagefit @r{(hyperlink option)} +@code{pagefit} option. The +@findex newwin @r{(hyperlink option)} +@code{newwin} option specifies whether the destination document is +opened in the same window or in a new window. + +Example: +@example +\hlstart@{filename@}@{file=book.pdf,newwin=1@}@{dest123@} + Link to dest123 in file `book.pdf'\hlend +@end example + +@item filepage +@findex filepage @r{(hyperlink type)} +@cindex file, hyperlink to +@cindex destinations, in another file +@cindex hyperlinks, to another file +Go to a page in another file. The label is the page number (counting +from@tie{}1). The file name is specified by the +@findex file @r{(hyperlink option)} +@code{file} option. Page fitting is specified by the +@findex pagefit @r{(hyperlink option)} +@code{pagefit} option. The +@findex newwin @r{(hyperlink option)} +@code{newwin} option specifies whether the destination document is +opened in the same window or in a new window. + +Example: +@example +\hlstart@{filepage@}@{file=book.pdf,newwin=,% + pagefit=/FitR 50 100 300 500@}@{1@} + Link to page~1 in file `book.pdf'\hlend +@end example + +@item url +@findex url @r{(hyperlink type)} +@cindex URL hyperlink +@cindex destinations, URL +@cindex hyperlinks, URL +Go to a URL. The label is the URL. + +Example: @code{\hlstart@{url@}@{@}@{http://tug.org/eplain/@}Eplain home\hlend} + +@item raw +@findex raw @r{(hyperlink type)} +The link specification (in the form of a pdf@TeX{} command or a dvipdfm +@code{\special} primitive) is taken from the command sequence +@code{\@var{cs}}, where @var{cs} is the value of the +@findex cmd @r{(hyperlink option)} +@code{cmd} option. This option is intended to be used with linkgroups +(@pxref{Setting hyperlink types and options}), as it does not make sense +to use it in a direct call to +@findex hlstart +@code{\hlstart}---you can just call the raw command. + +Example for @code{pdftex}: + +@example +% Redirect all \url links to the first page +\def\mycmd@{\pdfstartlink goto page 1 @{/Fit@}@} +\hltype[url]@{raw@} +\hlopts[url]@{cmd=mycmd@} +@end example + +Example for @code{dvipdfm}: + +@example +% Redirect all \url links to the first page +\def\mycmd@{\special@{pdf: beginann <</Type/Annot /Subtype/Link + /Dest[0 /Fit]>>@}@} +\hltype[url]@{raw@} +\hlopts[url]@{cmd=mycmd@} +@end example +@end table + +@subsubheading @code{pdftex}-specific link types + +@table @code +@item num +@findex num @r{(hyperlink type)} +@cindex numbered destination +@cindex destinations, numbered +@cindex hyperlink destination, numbered +Go to a ``numbered destination''. The label is the destination +number. + +Example: @code{\hlstart@{num@}@{@}@{123@}Link to 123\hlend} +@end table + + +@node Link options for pdftex and dvipdfm +@subsubsection Link options for @code{pdftex} and @code{dvipdfm} + +@cindex link options, @code{pdftex} +@cindex link options, @code{dvipdfm} +@cindex options, link, @code{pdftex} +@cindex options, link, @code{dvipdfm} +@cindex @code{pdftex}, link options +@cindex @code{dvipdfm}, link options +Link options are mostly the same for the @code{pdftex} and +@code{dvipdfm} drivers. The @code{pdftex} driver has additional +options to specify link dimensions. + + +@subsubheading Common link options + +@table @code +@item bcolor +@findex bcolor @r{(hyperlink option)} +@cindex hyperlink border color +@cindex border color, hyperlink +@cindex color, hyperlink border +Border color. An array of three numbers in the range 0 to 1, +representing a color in DeviceRGB@. + +Example: @code{\hlstart@{name@}@{bcolor=.1 .5 1@}@{dest123@}Link\hlend} + +@item bdash +@findex bdash @r{(hyperlink option)} +@cindex dashed hyperlink border +@cindex hyperlinks, border style +@cindex border style, hyperlink +Array of numbers representing on and off stroke lengths for drawing +dashes. + +Example: @code{\hlstart@{name@}@{bstyle=D,bdash=2 4@}@{dest123@}Link\hlend} + +@item bstyle +@findex bstyle @r{(hyperlink option)} +@cindex solid hyperlink border +@cindex dashed hyperlink border +@cindex beveled hyperlink border +@cindex inset hyperlink border +@cindex underline hyperlink border +@cindex hyperlinks, border style +@cindex style, hyperlink border +@cindex border style, hyperlink +Link border style: + +@table @code +@item S +The border is drawn as a solid line. + +@item D +The border is drawn with a dashed line (the dash pattern is specified +by the +@findex bdash @r{(hyperlink option)} +@code{bdash} option). + +@item B +The border is drawn in a beveled style. + +@item I +The border is drawn in an inset style. + +@item U +The border is drawn as a line on the bottom of the link rectangle. +@end table + +The default is @samp{S}. + +Example: @code{\hlstart@{name@}@{bstyle=D,bdash=2 4@}@{dest123@}Link\hlend} + +@item bwidth +@findex bwidth @r{(hyperlink option)} +@cindex width, hyperlink border +@cindex hyperlinks, border width +@cindex border width, hyperlink +Border width in +@cindex PostScript point +PostScript points (72@tie{}points per inch). The default is@tie{}1. + +Example: @code{\hlstart@{name@}@{bwidth=2@}@{dest123@}Link\hlend} + +@item cmd +@findex cmd @r{(hyperlink option)} +Name of the macro (without the leading @samp{\}) containing a +pdf@TeX{} command or a dvipdfm @code{\special} for the @code{raw} link. + +For an example of usage, @pxref{Link types for pdftex and dvipdfm}, +description of the @code{raw} link. + +@item file +@findex file @r{(hyperlink option)} +File name for the @code{filename} and @code{filepage} link types. + +For an example of usage, @pxref{Link types for pdftex and dvipdfm}, +description of the @code{filename} and @code{filepage} links. + +@item hlight +@findex hlight @r{(hyperlink option)} +@cindex hyperlinks, highlight mode +@cindex highlight modes, hyperlink +Link border highlight modes: + +@table @code +@item I +The rectangle specified by the bounding box of the link is inverted. + +@item N +No highlighting is done. + +@item O +The border of the link is inverted. + +@item P +The region underneath the bounding box of the link is drawn inset into +the page. +@end table + +The default is @samp{I}. + +Example: @code{\hlstart@{name@}@{bstyle=S,hlight=O@}@{dest123@}Link\hlend} + +@item newwin +@findex newwin @r{(hyperlink option)} +@cindex hyperlinks, opening in a new window +@cindex new window, opening hyperlink in +For the @code{filename} and @code{filepage} links, specifies whether the destination document is +opened in the same window or in a new window. The settings are: + +@table @code +@item 0 +Open in the same window. +@item @r{non-}0 +Open in a new window. +@item @r{empty} +Behavior according to the viewer settings. +@end table + +The default is empty. + +For an example of usage, @pxref{Link types for pdftex and dvipdfm}, +description of the @code{filename} and @code{filepage} links. + +@item pagefit +@findex pagefit @r{(hyperlink option)} +For the @code{page} and @code{filepage links}, specifies how the page +must be fitted to the window. @code{pagefit} specification is written +to the PDF file as is, so it must conform to the PDF standard. + +For an example of usage, @pxref{Link types for pdftex and dvipdfm}, +description of the @code{page} and @code{filepage} links. +@end table + + +@subsubheading @code{pdftex}-specific link options + +The dimension options below must be specified as a @TeX{} rule +specification. When set to empty, the corresponding value +of the parent box is used (this is the default for all dimension +options). + +@table @code +@item depth +@findex depth @r{(hyperlink option)} +@cindex hyperlink dimensions +@cindex dimensions, hyperlink +Depth of the link. + +@item height +@findex height @r{(hyperlink option)} +@cindex hyperlink dimensions +@cindex dimensions, hyperlink +Height of the link. + +@item width +@findex width @r{(hyperlink option)} +@cindex hyperlink dimensions +@cindex dimensions, hyperlink +Width of the link. + +Example: + +@example +\hlstart@{name@}@{width=5in,height=20pc,depth=0pt@}@{dest123@} + Link\hlend +@end example +@end table + + +@node Hyperlink driver nolinks +@subsection Hyperlink driver @code{nolinks} + +@cindex @code{nolinks}, hyperlink driver +@cindex driver @code{nolinks} +@cindex hyperlink driver @code{nolinks} +@cindex omitting hyperlinks +@cindex disabling hyperlinks +@cindex hyperlinks, disabling +@cindex destinations, disabling +@cindex spacing, preserving with hyperlinks +@cindex hyperlinks, preserving spacing +@cindex page-breaking, preserving with hyperlinks +@cindex hyperlinks, preserving page-breaking +Select this driver to suppress all hyperlinks in your document. + +Selecting this driver is quite different from not selecting any driver +at all, or from selecting some driver and then turning hyperlinks off +for the entire document with +@findex hloff +@code{\hloff} and +@findex hldestoff +@code{\hldestoff} (@pxref{Turning hyperlinks on/off}). + +The purpose of @code{\hldestoff} and @code{\hloff} is to mark (parts) of +your document where hyperlinks should never appear. (Imagine you want +to prevent a cross-referencing macro from generating a link at a certain +spot in your document.) + +If instead you have prepared a document with hyperlinks and just want to +compile a version without them, it is better to select the driver +@code{nolinks}. This ensures that spacing and page-breaking are the +same as what you were getting with hyperlinks enabled. + +The reason for this is that hyperlinks are produced by the +@code{\special} primitives or low-level hyperlink commands. Each such +command is placed inside a +@cindex whatsits, made by hyperlinks +@dfn{whatsit} (an internal @TeX{} object), which may introduce +legitimate breakpoints at places where none would exist without the +whatsits. The macros @code{\hldestoff} and @code{\hloff} disable the +hyperlink macros completely, so that no whatsits are produced. + +In contrast, the @code{nolinks} driver does not completely disable +hyperlink macros. Instead, it defines them to merely write to the log +file (what gets written is unimportant). This also produces +whatsits, thus imitating the whatsits from the hyperlink commands. +(This trick was borrowed from the +@pindex color.sty +@cindex graphics collection, @LaTeX{} +@cindex @LaTeX{} graphics collection +@LaTeX{} `color' package.) + +Another reason for using @code{nolinks} is that in horizontal mode +@code{\hldest} places destinations inside boxes of zero width, height, +and depth. When you say @code{\hldestoff}, @code{\hldest} will omit +both destination definitions and these boxes. The missing boxes can +again cause the typesetting to be inconsistent with that with +destinations enabled. Here again, the @code{nolinks} driver helps by +defining @code{\hldest} to produce the empty boxes. + + +@node Setting hyperlink types and options +@section Setting hyperlink types and options + +@cindex default hyperlink type +@cindex default hyperlink options +@cindex hyperlinks, default type +@cindex hyperlinks, default options +@cindex destinations, default type +@cindex destinations, default options +You can define default types for links and destinations, which will be +used when you do not specify a type in +@findex hlstart +@code{\hlstart} or +@findex hldest +@code{\hldest}. Similarly, you can define default values for the +options; the default value for an option is used when you do not set the +option in the argument to @code{\hlstart} or @code{\hldest}. + +@cindex group, type hyperlink +@cindex group, options hyperlink +@cindex hyperlinks, group type +@cindex hyperlinks, group options +@cindex link, group type +@cindex link, group options +@cindex linkgroup, type +@cindex linkgroup, options +@cindex destinations, group type +@cindex destinations, group options +@cindex destgroup, type +@cindex destgroup, options +The parameters for implicit links and destinations can be customized by +setting the ``group'' types and options. When not set, the defaults are +used. + +All these settings are local to the current (@TeX{}) group, so if +you want to set an option temporarily, you can do so inside a +@code{\begingroup@dots{}\endgroup} block; when the group ends, the +previous settings are restored. + +@menu +* Setting default types and options:: +* Setting group types:: +* Setting group options:: +@end menu + + +@node Setting default types and options +@subsection Setting default types and options + +@findex hltype +@findex hldesttype +The default types for links and destinations can be set with the +following commands: + +@example +\hltype@{@var{type}@} +\hldesttype@{@var{type}@} +@end example + +@noindent where @var{type} is one of the +link/destination types supported by the selected hyperlink driver +(@pxref{Hyperlink drivers}). + +@findex hlopts +@findex hldestopts +Default values for the options can be set with the following commands: + +@example +\hlopts@{@var{options}@} +\hldestopts@{@var{options}@} +@end example + +@noindent where @var{options} is a comma-separated list of option +assignments in the format @samp{@var{option}=@var{value}}. Again, what options +are allowed depends on the selected hyperlink driver. + + +@node Setting group types +@subsection Setting group types + +@findex hltype +@findex hldesttype +@cindex group, type hyperlink +@cindex hyperlinks, group type +@cindex link, group type +@cindex linkgroup, type +@cindex destinations, group type +@cindex destgroup, type +When called with an optional argument, as in + +@example +\hltype[@var{groups}]@{@var{type}@} +\hldesttype[@var{groups}]@{@var{type}@} +@end example + +@noindent where @var{groups} is a comma-separated list of groups, +@code{\hltype} and @code{\hldesttype} set the type for each group from +@var{groups} to @var{type}. The default type is used for all groups +with an empty type (this is the initial setting for all groups, except +that the type for the `url' linkgroup is set to @samp{url} by the +drivers which support this link type). + +@cindex group `' (empty) +@cindex default hyperlink type +@cindex default hyperlink options +@cindex hyperlinks, default type +@cindex hyperlinks, default options +@cindex destinations, default type +@cindex destinations, default options +There are two special ``groups'' which can be used inside the +@var{groups} list. An empty group sets the default type. This allows +to set the default type and group types in one command, for example: + +@example +\hltype[eq,]@{@var{type}@} +@end example + +@noindent sets the link type for the `eq' linkgroup and the +default link type to @var{type}. + +@cindex group `*' +@cindex groups, specifying all +@cindex all groups, specifying +Another special group is a star (@samp{*}) group, which signifies all +defined groups. For example, the command + +@example +\hldesttype[*,]@{@var{type}@} +@end example + +@noindent sets the destination type to @var{type} for each group, +as well as the default destination type. + + +@node Setting group options +@subsection Setting group options + +@cindex group, options hyperlink +@cindex hyperlinks, group options +@cindex link, group options +@cindex linkgroup, options +@cindex destinations, group options +@cindex destgroup, options +Option values for each group are stored as a list of option +assignments. This list does not have to contain every supported +option. Values for options missing from this list are taken from the +default option values. + +@findex hlopts +@findex hldestopts +To manipulate the list of option values for the groups, you use the +@code{\hlopts} and @code{\hldestopts} commands with an optional +argument: + +@example +\hlopts[@var{groups}]@{@var{options}@} +\hldestopts[@var{groups}]@{@var{options}@} +\hlopts![@var{groups}]@{@var{options}@} +\hldestopts![@var{groups}]@{@var{options}@} +@end example + +@noindent where @var{groups} is a comma-separated list of groups and +@var{options} is a comma-separated list of option assignments. The +two special ``groups'', the empty group and the star (@samp{*}) +group, have the same meaning as for @code{\hltype} and +@code{\hldesttype}. +@cindex group, preserving option list +@cindex hyperlink group, preserving option list +@cindex option list, preserving for group +When used without the exclamation mark, @code{\hlopts} and +@code{\hldestopts} preserve the current list of options for the groups, +and only update the options listed in @var{options}. If you add the +exclamation mark, the current list of options for each group in +@var{groups} is discarded and the new list is set to @var{options}. + +The ``overriding'' nature of the @samp{!} is appropriate when you give +a complete specification of the options for a group, e.g., at the +beginning of your document. On the other hand, when you want to +adjust some option(s) and leave others intact, you should use the +macros without the @samp{!}. + +@findex raise @r{(hyperlink option)} +@cindex mathematics displays, hyperlinks +@cindex displayed math and hyperlinks +@cindex large operators and hyperlinks +@cindex hyperlinks, large operators +@cindex destinations, large operators +@cindex raising hyperlink destinations +For example, with displayed mathematical formulas, you often need to +adjust the @samp{raise} option for the +@cindex group `eq' +@cindex linkgroup `eq' +`eq' destgroup, because the formulas often contain large parentheses and +brackets. But when doing so, you want to leave the other settings +unchanged. To achieve this, call @code{\hldestopts} without the +@samp{!}, for example: + +@example +$$\hldestopts[eq]@{raise=2.5\normalbaselineskip@} +@dots{} +$$ +@end example + +@noindent The display commands (@samp{$$}) implicitly put the entire +formula inside a (@TeX{}) group (@code{\begingroup@dots{}\endgroup}), so +you do not need to isolate the setting of the @samp{raise} option---it +will be restored after the closing @samp{$$}. + +@cindex option list, group +@cindex group option list +@cindex hyperlinks, group option list +Initially, Eplain sets the option lists for almost all groups to empty, +so that the groups fall back on the default values for all options. The +one exception to this rule is the `eq' destgroup, whose initial option +list contains one setting: + +@example +raise=1.7\normalbaselineskip +@end example + +@noindent This setting usually accommodates the large operators, which often +appear in displayed math. + + +@node Turning hyperlinks on/off +@section Turning hyperlinks on/off + +@cindex omitting hyperlinks +@cindex disabling hyperlinks +@cindex hyperlinks, disabling +@cindex destinations, disabling +Links and/or destinations can be turned on or off globally by disabling +the low-level commands, or for each group individually. + +All these settings are local to the current (@TeX{}) group, so if you +want to enable or disable links/destinations temporarily, you can do so +inside a @code{\begingroup@dots{}\endgroup} block; when the group ends, the +previous settings are restored. + +@menu +* Turning low-level commands on/off:: +* Turning hyperlinks on/off for a group:: +@end menu + + +@node Turning low-level commands on/off +@subsection Turning low-level commands on/off + +@findex hldeston +@findex hldestoff +@findex hlon +@findex hloff +The low-level commands @code{\hlstart}, @code{\hlend} and +@code{\hldest} can be turned on/off with the following commands: + +@example +\hldeston +\hldestoff +\hlon +\hloff +@end example + +@noindent @xref{Hyperlink driver nolinks}, for the implications of using +these commands to disable hyperlinks for the entire document. + + +@node Turning hyperlinks on/off for a group +@subsection Turning hyperlinks on/off for a group + +@cindex group, disabling hyperlinks +@cindex hyperlink group, disabling hyperlinks +If you want to disable links/destinations produced by certain groups, +you can give a list of the groups as an optional argument to these +commands: + +@example +\hldeston[@var{groups}] +\hldestoff[@var{groups}] +\hlon[@var{groups}] +\hloff[@var{groups}] +@end example + +@noindent where @var{groups} is the list of linkgroups/destgroups. This +list can contain two special groups. The empty group switches the +low-level commands (@pxref{Turning low-level commands on/off}), and the +star (@samp{*}) group operates on all defined groups. + +Note that turning off the low-level commands disables all hyperlinks +globally, including groups which have them enabled. Turning off certain +linkgroups/destgroups records the fact that the macros in the group +should not produce links/destinations. To illustrate the distinction, +assume that all links are on; after the following sequence of commands: + +@example +\hloff +\hloff[eq] +\hlon +@end example + +@noindent all links are on except for the `eq' linkgroup. |