# [tex-eplain] Improvement for hyperlink option handling

geolsoft at mail.ru geolsoft at mail.ru
Fri Sep 2 18:02:23 CEST 2005

On Fri, Sep 02, 2005 at 03:38:41PM +0200, Karl Berry wrote:
> What are the types?  href, mailto?

Destination types are (for pdftex, for dvipdfm they are similar):

XYZ     Current position'.  Option |zoom| specifies magnification.
Fit     Fit the page to the window.
FitH    Fit the width of the page to the window.
FitV    Fit the height of the page to the window.
FitR    Fit the rectangle specified by options |width|, |height| and |depth|
in the window.
FitB    Fit the page's bounding box to the window.
FitBH   Fit the width of the page's bounding box to the window.
FitBV   Fit the height of the page's bounding box to the window.

name     Go to a named destination.  All destinations created with |\hldest|
are named destinations'.
num      Go to a numbered destination.  The label is the destination number.
page     Go to a page.   The label is the page number (counting from 1).
Page fitting is specified by |pagefit| option (see note below).
filename Go to a named destination in another file.  File name is specified
by |file| option.  |newwin| option controls whether the destination
document is opened in the same window or in a new window.
Page fitting is specified by |pagefit| option (see note below).
filepage Go to a page in another file.  The label is the page number
(counting from 1).  File name is specified by |file| option.  Page
fitting is specified by |pagefit| option (see note below).
|newwin| option controls whether the destination document is opened
in the same window or in a new window.
uri      Go to a URI.  The label is the URI.
raw      Execute a raw' pdfTeX command.  |cmd| option specifies name of
macro (without the leading \') which expands to the raw command.
There is no sense in using this type directly with |\hlstart| (you
can execute the command yourself); it is intended to be used in
parameters for cross-reference macros.

> Are the options for things other than controlling appearance?
> (Color, boxing, what else?)

There are a few options not related to appearance:

cmd      this is name of macro which expands to raw' PDF
command for raw' types of links/dests
file     file name for links of type filepage'
newwin   controls whether filename' and filepage' links
pop up a new window.

The rest are for appearance.

For destinations, they control how much the dest is raised
above the baseline, exact location of the destination,
zooming, bounding box to fit to when jumping to the dest,
etc.

For links, the appearance options are:

S       The border is drawn as a solid line (default).
D       The border is drawn with a dashed line (the dash pattern is
specified by |bdash| option).
B       The border is drawn in a beveled style.
I       The border is drawn in an inset style.
U       The border is drawn as a line on the bottom of the link rectangle.

|bdash| is an array of numbers representing on and off stroke lengths for
drawing dashes.

I       The rectangle specified by the bounding box of the link is inverted.
N       No highlighting is done.
O       The border of the link is inverted.
P       The region underneath the bounding box of the link is drawn inset
into the page.

|bcolor| (border color) is specified as an array of three numbers in the range
0 to 1, representing a color in DeviceRGB.

|bwidth| (border width) in points (72 points per inch, a PostScript point', or
a big point').  Default is 1.

|zoom| is specified as a magnification ratio times 1000 (like TeX's scale
factor).

|color|
|colormodel| Color and color model to render the link's text with

> So what are the other groups?  xref, bib, footnote, url?

For destinations, the groups are (mostly self-explanatory):

definexref
xrdef
li
eq
bib
foot          \footnote / \numberedfootnote
footback      back-reference from the footnote to the text
idx

xrefn         \refn and \xrefn
xref          \xref
ref           \ref and \refs
eq            \eqref and \eqrefn
cite          \cite
foot          \footnote / \numberedfootnote
footback      back-reference from the footnote to the text
idx
url           \url from url.sty

>     NOTE:  For \hldesttype and \hltype, the !' is accepted but
>            has no effect.
>
> Beucase the default options for the types is empty?  (In the future it
> might not be.)

The type' parameter is just a single name.  Setting it to
empty for the group will make the group use the default type
(and Eplain sets the types for all groups to empty, except
url' group, which is set to uri').  When the user asks to
set the type (default or for a group), we just store it in
the relevant macro, with or without the !'.  The !' does
not make sense for type'.

The same for default options -- each default option is
stored in a separate macro, so we just store the value for
each default option in its own macro, with or without the
!'.

On the other hand, for the groups, opts' is a _list_ of
options in the form opt1=value1,opt2=value2,...'.  This
list does not have to contain every supported option.
Options which are in this list will override the default
values for those options; for options missing from the list,
the default values will be used.  So without the !', the
current list of options for the group is retained; with !',
we start from the clean slate, wiping out anything there was
on the group's list, and using the argument list as the new
list for the group.

This is easy for me, I know how it works; if once again I am
unclear, let me know, I will try to explain it some other
way.

> How about having it "set" the default with the ! and "augment" the
> default without it?

This way, it will be impossible to remove an option from the
list of options for the group.  We cannot set an option to
empty to indicate that the default is to be used -- for some
options, empty values are legitimate.

For example, there is an option top' for dvipdfm, which
indicates the y-coordinate for destinations.  If it is set
to empty, the driver uses @ypos' which dvipdfm will convert
to the current y-coordinate.  So a group may set top=' to
obtain the @ypos', but the (global) default for the top'
may be something entirely different (e.g. the top of the
page).

Another example is the zoom' option for destinations.  When
set to empty, the zoom' specification is omitted altogether
by pdftex driver, causing the zooming not to change.

> Usually people do want to keep the defaults and just change what they
> want to change.  That's the most reliable approach to keeping compatible
> future changes.

So they just never use empty groups', and only set
parameters they need for real' groups.

As a reminder, each of \hldest and \hlstart take OPTIONS
parameter.  Any options in this list override the defaults.
The reason I started all this mess with the groups was that
the cross-reference macros call, so we needed to provide the

To summarize:

There are default type and default values for each
supported option.  \hldest and \hlstart use these defaults
when the type or an option are not given in their
parameters.  The type and any option given in the
parameter to \hldest and \hlstart override the default
type and the default value for that option.

For groups, the user can define the type and a list
containing definitions for some/all of the options.  These
will be passed to \hldest and \hlstart inside the
cross-references, thus overriding the defaults.  Any
option which is missing from the group's list of options,
will not be passed to \hldest / \hlstart, so it will be
taken from the default value for that option.

> Is there a use in controlling links/dests separately?  I can't imagine a
> use for creating dests without links, and even less for creating links
> without dests.  Would it make sense to reduce to just \hlon+off and have
> it control both?

For some of the groups, controlling links/dests separately
does not (usually) make sense.  But, as you can see above,
the lists of groups for links and destinations are not
identical.

What's more, you can imagine a situation when, in some part
of a document, the user wants to prevent \eqref from
creating links, but still wants to create dests, possibly to
link to them from some later part of the document.  There's
no limit to the user's fantasy :)

So this is a question of convenient use in most cases'
vs. providing for all possible uses'.

--
Best regards,
change them to url', now that we have \url from url.sty