[tex-eplain] Improvement for hyperlink option handling

[geolsoft at mail.ru]

I have a suggestion to improve handling of options for
hyperlinks.  Currently, these options are set by defining
certain macros.  The names of those macros had become very
long and unreadable (like \hldestdefinexrefraise), so I've
tried to devise a better way to set the options.

Another thing is that currently it is not possible to
selectively turn hyperlinks on/off for, e.g., equation
references -- hyperlinks can only be switch `globally'.

So this is what I came up with.  The code is almost ready,
but I wanted first to submit this description to the list,
in case somebody comes up with new ideas.



Hyperlinks and destinations are categorized into `explicit'
and `implicit'.  Explicit links/dests are those created by
the user with the low-level commands \hlstart...\hlend and
\hldest.  Implicit links/dests are those created implicitly
by, e.g., cross-reference macros.

Implicit links/dests are divided into `hyperlink/destination
groups', so that parameters can be set individually for each
group.  For example, all equation macros which define a
destination are assigned to the `eq' destination group;
equation macros which create a link are assigned to the `eq'
hyperlink group.  Some groups consist of only one macro, for
instance, the `definexref' group.

Parameters can be set for explicit links/dests (these are
called `default' parameters) and for any group individually.
Parameters which are not set for the group are taken from
the default parameters (hence the name).

There are (currently) two kinds of parameters:  `type' (type
of link/dest) and `opts' (options for link/dest).

Parameters can be set by one of the four commands:

  \hldesttype       set type for destinations
  \hldestopts       set options for destinations
  \hltype           set type for links
  \hlopts           set options for links

The syntax for the four macros is exactly the same, so let
us use \hlopts as an example:

  \hlopts[GROUPS]{VALUE}
  \hlopts![GROUPS]{VALUE}

GROUPS is a comma-separated list of predefined link groups,
VALUE is a comma-separated list of options to set for each
of the group in GROUPS.  Two `groups' have special meaning:
the empty group will set the default options, the star (*)
group will make the setting affect all groups (except the
empty group).  \hlopts can be followed by `!', in which case
current list of options for each group will be cleared and
set to VALUE (without the `!', VALUE will augment/update the
current list of options for each group).  For example:

  \hlopts[*]{...}   Update options for all groups but _not_
                    the default options.
  \hlopts[*,]{...}  Update options for all groups _and_ the
                    default options.
  \hlopts[eq,]{...} Update options for the `eq' group and
                    the default options.
  \hlopts{...}      Update the default options.
  \hlopts![eq]{...} Clear the current list of options for
                    the `eq' group and set it to `...'.

An example of the `...' above:

  bstyle=S,bwidth=2

means `solid border of width 2'.

NOTE:  For \hldesttype and \hltype, the `!' is accepted but
       has no effect.  The same is true for \hlopts and
       \hldestopts when they are used to set the default
       options.  The reason is that in these cases there
       is nothing to `clear'.

       For \hldesttype and \hltype, VALUE is not a list but
       a single type name.

       There is currently no way to query the parameters
       short of accessing the `hidden' macros where we save
       them.



Another four macros will turn links/dests on/off:

  \hldeston
  \hldestoff
  \hlon
  \hloff

All of them take an optional argument which should be a list
of hyperlink/destination groups.  The two special groups
(the empty group and the star group) have meaning similar to
that in the case of the parameter macros.  For example:

  \hloff            Turn off hyperlinks for low-level
                    macros.
  \hloff[*]         Turn off hyperlinks for all groups but
                    _not_ the low-level macros.
  \hloff[eq,]       Turn off hyperlinks for equations _and_
                    low-level macros.
  \hloff            Turn off hyperlinks for low-level
                    macros.

NOTE:  Turning off low-level macros will prevent any groups
       from producing links/dests, effectively disabling
       _all_ links/dests.  Turning off links/dests for a
       certain group records the fact that the group should
       not produce links/dests.  To illustrate the
       distinction, assume that all hyperlinks are on; after
       the following sequence of commands:

         \hloff
         \hloff[eq]
         \hlon

       all hyperlinks will be on except for the `eq' group.



I hope this is actually more user-friendly than the simple
define-a-macro scheme.

-- 
Best regards,
Oleg Katsitadze