bug#60587: Patch for adding links to symbols' help documentation

[Drew Adams <drew.adams@oracle.com>]

[-- Attachment #1: Type: text/plain, Size: 4446 bytes --]

> > I think it's _good_ to have a separate face
> > for this.
> 
> I disagree that another face is a Good Thing.
> We have too many of them already.

I respectfully disagree.  I'll give my reasons
here, then call it quits.

Nothing prevents the new face from, by default,
inheriting its appearance from the other one.
(Though I'd much prefer that it not do that by
default.)

And nothing prevents its doc from pointing out
that that's the case.  So customizing the Info
link face gives the new Info *Help* link face
the same appearance (but not vice versa).

By inheriting, there is, in effect, a general
category: link in Info, and you can either have
all links in Info look the same or have the
two kinds look different.

> > That gives users the choice:
> >
> > * Have the same appearance for both kinds of link.
> > * Have the two kinds of link (Info, *Help*) look
> >   different.
> >
> > When you provide two faces, users can always customize
> > them to look the same, if they like.  Otherwise, they
> > don't have that possibility.
> 
> The downside of having a separate face is the need 
> to know about it and customize it separately.

"_Need_ to know about it"?  Why/when does anyone
need to know about it, any more than they need
to know about the Info link face?

Users can check which face is used somewhere,
and show both kinds of links with either
`list-faces-display' or `M-x customize-face'.

(BTW, shouldn't the Info faces for links be
included in group `info-xref-group'?  You
should be able to do `M-x customize-group
info-xref-group' and see `info-xref',
`info-xref-visited' and `info-header-xref'.)

> we should introduce new faces only if they
> really are for a different purpose.  This one
> isn't.

I think it is.  It's not for Info navigating.
It's not for following Info cross-references.
Its purpose is something different.

More importantly than what I think perhaps, is
that if you give users the choice, so they can
see a difference, and if some make the choice
to see it, they will have demonstrated that -
for them - the two do have different purposes.

This isn't really different from the choice we
made to have _three_ faces for following Info
xrefs: `info-xref', `info-xref-visited', and
`info-header-xref'.  Someone chose to have 3,
not 1, face for this.

I don't expect to convince you, and you've
maybe already decided about it.  But I'd like
to state my position and reasons about this.

The question about "too many faces" comes up
periodically.  Just as in taxonomy discussions,
there are those who are more "clumpers" and
those who are more "splitters".  When it comes
to faces, I tend to be more of a splitter.
(When it comes to letting users customize their
editor, Emacs itself is very much a splitter!)
___

Finally, here's an example of another Info
link face, which I added in my code.  It links
glossary words to their definitions in the
Glossary.  Unlike the new *Help* links, this
one is, like the *xref* faces, for navigating
in Info.

And like the new *Help* links, users are able
to hide/show its links on the fly.  Equally
important, only the _first_ occurrence in a
node of a given word is linked.  That too
would be useful for the new *Help* links, as
opposed to linking every occurrence of the
same symbol name (too noisy).

More generally, users can choose how and when
to show glossary links.

In addition to linking them, glossary words
in the text can show their definitions on
mouseover.

(Going to the Glossary lets you follow links
within the Glossary.  But there aren't many
of those, and a user might prefer to just
see definitions on mouseover.)

Choices (option `Info-link-glossary-words'):

1. Never (off).  Not even an invisible link.
2. Only until a link for that word has been
   visited.  But show a tooltip with the
   word's definition on mouseover.
3. Only until visited (no mouseover tooltip).
4. Always.  And show mouseover tooltip.
5. Always.  No mouseover tooltip.
6. Never - an invisible link, but show
   mouseover tooltip.
7. Never - invisible link, and no mouseover
   tooltip.

The default is #2.  Attached are screenshots
showing #2/#3, #5, and #6.

A toggle command toggles the option between
#1 (a nil value) and the last used of the
others (non-nil values).  A cycle command
cycles the option among the possible values.

[-- Attachment #2: throw-emacs-info-gloss-links-face+def.png --]
[-- Type: image/png, Size: 77997 bytes --]

[-- Attachment #3: throw-emacs-info-gloss-face-until+NO-def.png --]
[-- Type: image/png, Size: 66006 bytes --]

[-- Attachment #4: throw-emacs-info-gloss-links-NOface+def.png --]
[-- Type: image/png, Size: 73413 bytes --]