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