RE: hyperlinks in variable's value - links to libraries

[Drew Adams]

     > I'm certainly not lobbying to just revert it. I would like to see:
     >
     > 1. It reverted, so *Help* buffers can once again link users
     >    to related source code and object (e.g. variable) descriptions.
     >
     > 2. *Libraries* also be linked, in addition to functions and
     >    variables - see the code I sent, as an example. This is
     >    especially useful for `C-h v features'.

    It still doesn't know what its looking at.  It would link the
    first match which would in many cases would still be to the
    function.  Also the variable features is a list of features,
    not libraries e.g text-properties, overlay
    base64 are provided in bindings.el

Yes, of course. However, in practice, it works quite well. The problem of
multiple names of different types is pretty well handled by ordering
(priority) - see the code I sent. The problem of multiple features with
different names is not a problem in practice either, because those features
simply don't end up with links. Only features that are the names of
libraries are linked (to those libraries). That's 99+% of the features, BTW.

I've used this for quite a while, and I have yet to notice any problem.
Generally, you don't find a mix of other (e.g. variable, function) names
with library names. I'd encourage people to just try it, to see whether or
not it is worth it. By "worth it", I mean worth adding an option - not
forcing people to have links to libraries.

     > 3. An option be added, so users can skip adding *Help* links
     > to save time, if they like.
     >
     > 4. In addition to #3, a button in *Help* to show links. If
     > the option in #3 were turned off, then the buffer would be
     > displayed without the time-consuming object links (variables,
     > libraries, etc.), but you could still click a `Show Links'
     > button to add the links. IOW, add the links only upon demand.

    Another option!  Another button!

Yes.

    The idea is to make it easier, not harder

Precisely.

    to navigate the links.

Huh? If there are no links, then, it's hardly easier to navigate them (or
perhaps it is, vacuously ;-)).

Screaming that another option or button complicates things is a fine general
argument but a silly argument in any specific context. Just what is made
easier by the addition of the links, an option, and a toggle button? Just
what is made more difficult by their addition? It's a judgement call, of
course. It's worth discussing (weighing), IMO.

     > 5. After links have been shown once, the button would change to `Hide
     > Links', to enhance readibility (reduce visual clutter). Once
     > the links have been calculated (`Show Links'), the link info would be
kept
     > - it would not be lost via `Hide Links' - so redisplay via `Show
Links'
     > would be fast.

    Kept where?  The help buffer is generally regenerated through the [back]
    button.

I think you're confusing caching a *Help* buffer for navigation forward and
backward (something I did not propose - but I wouldn't be against it) with
what I did propose: retaining the link information in the buffer as
displayed - that is, for the same *Help* screen text - across toggling of
the `Show/Hide Links' button. There are several ways that could be done. The
idea is simply to keep the links and faces there, but disable them (links)
and hide them (faces). Navigating to a different *Help* screen (different
text) would result in regeneration.

The cost for adding links is in calculating the link destinations and
creating the text properties or overlays. Once that's done, the links could
remain, but their appearance and enabling could be "neutralized", at no
added cost.

     ...
     >     Many variables like mode-line-format or after-load-list
     >     have a lot of underlining, some of which isn't that helpful
     >     (a user is hardly likely to want click on concat or
     >     user-init-file) and it makes it harder to see what you're
     >     looking at.
     >
     > Visual clutter is not a reason to not link things; it is a
     > reason to get rid of visual clutter.
     >
     > The solution to visual overload from underlining when a
     > buffer is mainly links (i.e. link-dense) is to not have the
     > face show that a link is present, but rely on mouseover to
     > show that. If a buffer is truly link-dense, then
     > users discover right away that things are linked, because
     > the mouse is always over a link. But see below - *Help* is
     > not a good candidate for this approach.

    Sounds too complicated to me.  Also confusing to the user who
    won't understand why the visual cues are changing.

It's common on Web pages. If your mouse is always over one link or another
(e.g. in an image map or a dense table listing), and the mouseover indicates
it is a link, you don't need the text to be underlined without mouseover.

It may sound complicated to you, but thousands of ordinary folk seem to have
no problem with it everyday. It may be complicated to describe, but not to
use.

     > If I didn't know what `concat' and `user-init-file' are, I
     > might well want to click them to find out. Users are various,
     > with different backgrounds, different needs, interacting in
     > different contexts.

    Its a tangent from finding out about after-load-list.

Sorry, I don't follow you at all - I have no idea what you're talking about.

     >     I think its best not to lead users anywhere than up the
     >     garden path.
     >
     > Meaning?

    I don't agree with you.

     > Example?

    What you are suggesting.

Leading someone down the garden path means leading them astray - deceiving
them. How does what I suggest lead users astray? Please state your argument
more clearly; I'm not following you.

     >     The doc strings on the other hand can be more carefully
     >     crafted to DTRT.
     >
     > What's the connection? I want to see the list of features
     > when I use `C-h v features'. How does rewriting the doc string
     > affect the current discussion?

    If a link is inappropriate, quotes aren't used in the doc
    string.

Are you perhaps saying that it is easier to just identify the terms to be
linked as those that are quoted, rather than trying to also link some terms
that are not quoted? That's certainly true. I don't know how well the trial
of linking variable etc. names worked - I haven't seen problems with it, but
I imagine there could be some. Maybe we need to experiment with it more.

    Preceding the symbol name with the keyword `variable', 'function' etc
    ensures that the correct link is made.

"Ensures"? No. It can help - but you can also get some anomalies with that
approach. Trying to insert links automatically in natural-language text is
bound to have some hiccups, no matter how it is done - I suppose we agree on
that. I haven't seen problems in practice, but I'm sure there would be some.
The question is whether such problems would outweigh the benefit. And see
below, on stopwords.

IIUC, you are mainly discussing ways to implement linking - how to identify
the proper text to which to apply a link. I am mainly discussing the value
of linking to libraries from their names. Different ways to identify the
proper names could be examined.

If nothing else, even if it were done as a one-off exception, I would like
to see the features that are also library names be linked to their libraries
when I do `C-h v features'. The value would be the same as having a link on
the library name in a function or variable description.

     >      >     Although it can be slow, it is very useful:
     >      >     looking at `features'
     >      >     should be an entry point to accessing the features listed.
     >
     >     The links are still available on mouse-2 as help-follow,
     >     they're just not underlined or highlighted.
     >
     > That would be appropriate if all *Help* buffers were
     > link-dense, so that random mouseover would show users that
     > most things are linked. It's not appropriate for *Help* however,
     > because most *Help* buffers are not link-dense.

    If the doc strings were marked up for links in the
    indiscriminate way that
    variable values are , every `if' and `or' would be linked.

So, have a simple stopwords list. This is by no means an unsurmountable
problem. A surprisingly small stoplist filters out most insignificant
English words when indexing; the stopwords list for a programming language
would be much tinier yet.

Plus, I assume that we wouldn't choose to link from more than one occurrence
of the same word in the same *Help* buffer. That is, even without a
stoplist, only the first `if' and `or' would be linked.

And, again, I don't really care that much about linking symbol names other
than libraries. Just as you can click the word `abbrev' in "Defined in
abbrev" at the end of *Help* for `C-h v abbrev-mode', so I like being able
to click a library name in the value displayed by `C-h v features'. There is
no "every `if' and `or' would be linked" in that case.