5.2 Explicit hyperlinks

Explicit hyperlinks are created by you, in the source of your document. The simplest command is \hldest, which marks the current position in your document as a destination:

     \hldest{type}{options}{label}

Here type is one of the destination types supported by the hyperlink driver (see Hyperlink drivers), options is a comma-separated list of option assignments, and 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 pdftex driver, the command

     \hldest{xyz}{zoom=2000}{index}

creates a destination of type `xyz' (“the current position”), sets the magnification ratio for this destination to be 200%, and associates the label index with the destination.

Another command, \hlstart, paired with \hlend, turns all intervening material into a link:

     \hlstart{type}{options}{label} ... \hlend

Here type, options and label have the same meaning as for \hldest. Continuing the previous example,

     \hlstart{name}{bstyle=U,bwidth=2}{index} Index\hlend

typesets the word `Index' as a link with underline border of width 2 PostScript points, pointing to the named destination index defined in the previous example. (The other options, like highlight mode and border color, are determined by the defaults, see Setting default types and options).

The label argument of both \hldest and \hlstart can contain special characters (such as `#', `%', `&', `~', etc.) without any escaping. This is especially important for URL links supported by some drivers (see Hyperlink drivers).

Both \hldest and \hlstart ignore following spaces.

Both \hldest and \hlstart expand the first token of options once, so you can save a list of options in a macro and pass it for the options. For example:

     \def\linkopts{bstyle=U,bwidth=2}
     \hlstart{name}{\linkopts}{index}Index\hlend

is functionally equivalent to the previous example.

See Hyperlinks (xhyper.tex), for a demonstration of the usage of explicit hyperlinks.