Subject: RE: bug#16333: 24.3.50; Info manuals: link defined terms to their glossary entries

From: Drew Adams <[email-masked]>
Date: Wed, 28 Oct 2020 23:52:32 -0700 (PDT)

> > Let's hope there is someone interested enough to take a
> > stab at this.  (Perhaps Drew would like to volunteer?)
> 
> No, but I too hope someone will do so at some point.

Actually, I've done this now.  I added it to info+.el.
(It could of course be added to vanilla Emacs also.)

>From the Info+ Commentary:

  Glossary words, that is, words that are defined in a manual's
  `Glossary' node, are highlighted and linked to their glossary
  entries, if option `Info-fontify-glossary-words' is non-nil.
  By default, a mouseover on such a link shows a tooltip with
  the word's definition from the glossary.  (Currently only the
  Emacs and Semantic manuals have `Glossary' nodes, as far as I 
  know.)

Only the first occurrence of a given glossary word in
a given node is handled this way; other occurrences
are ignored.

Occurrences of glossary words within Info links (e.g.
menu items, xrefs) are not treated (they're skipped);
there's no treatment of glossary words in an Index
(there could be; that was a choice); and occurrences
within a Glossary itself are treated only when not in
the definition of the same word.

You can toggle this highlighting (and linking) with
command `Info-toggle-fontify-glossary-words'.

Only glossary terms that are single words are handled
by this highlighting/linking/tooltip behavior.  But
there's also a command, `Info-glossary', that prompts
for a glossary term with completion, and all glossary
terms are handled (i.e., not just single-word terms).

https://www.emacswiki.org/emacs/download/info%2b.el

___

BTW, I did have a question, which I finally found the
answer to (I guess), by experimenting.  I think the
Elisp manual needs some info added.

The tooltip help I was using had (1) the glossary
word's definition, followed (after a blank line) by
"mouse-2: go to Glossary entry for this word".

I couldn't figure out why that "mouse-2" text wouldn't
magically change to "mouse-1" with non-nil variable
`mouse-1-click-follows-link'.  Couldn't get it to work.

Finally, on a whim, I switched the order, so the text
started with "mouse-2"... instead of starting with the
glossary definition.  Bingo!

This magic seems to be undocumented.  Everything about
`mouse-1' following links is well documented except
this help-echo magic.  I hope someone will add this
secret to the Elisp manual somewhere: If you've got
things set up so that `mouse-1' will follow links
(e.g., you use `follow-link' etc.) and if your
`help-echo' text starts with the text "mouse-2", then
the resulting help echo will actually start with
"mouse-1", in place of "mouse-2".  That seems to be
the (undocumented) behavior.

It turns out that the text need not exactly start with
"mouse-2".  Because I want the definition to be the
main point of the tooltip, I now put the mouse action
description (which apparently has to come first) in
parens: "(mouse-2...)" - and it still works.

So maybe the magic that transforms "mouse-2" to
"mouse-1" works only if "mouse-2" is within N chars
of the start.  Or maybe it will skip over punctuation
(e.g. "(") but not over letters.  Or maybe it didn't
work in the other order because I have a blank line
between the two.  I didn't play with it enough to
figure out the behavior completely.

Dunno where that text transformation is implemented
(in C?) - I didn't find it in the Lisp.  And I just
happened to guess an answer, based on seeing the
same text used over and over in source code.

Would someone please consider telling users about
this secret sauce in the Elisp manual?  Thx.
___

Another nice-to-have would be beefing up the Glossary
in the Emacs manual.  I'm guessing it hasn't been
updated in a while, and features have been added that
are not reflected there.  I was also surprised to see
that most manuals have no glossary.  The only manuals
I found that have glossaries are Emacs and Semantic.
Aren't there lisp things that deserve glossary entries?
Org things?  (No, I'm not volunteering.)