[tex-eplain] Improvement for hyperlink option handling

[geolsoft at mail.ru]

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.

Hyperlink types:

   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:

 |bstyle| (link border style):
   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.

 |hlight| (link border highlight modes):
   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

For links, the groups are:

  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 user did not have access to \hldest and \hlstart that
the cross-reference macros call, so we needed to provide the
means for adjusting their parameters.

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,
Oleg Katsitadze

P.S.  I've noticed that I had used `uri' type for URL links
(this is what PDF spec calls them).  Maybe it is better to
change them to `url', now that we have \url from url.sty