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

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

[Drew Adams]

Enhancement request.

Inspired from a post on emacs-devel in thread "Apologia for bzr",
2014-01-03, which said,

  I bet you can dip into any number of Info nodes where the terms
  "buffer" and "window" are used without definition.

That would be a non-issue if such terms were linked (automatically) to
their glossary entries.  This feature should be optional, and even easy
to toggle on/off.  The links should be highlighted differently, so users
can easily tell that they are glossary links.

Info manuals such as the Emacs manual are strong in actually providing
an extensive glossary of terms.  But it is true that we do not leverage
that feature by (a) showing, in the main text, which terms are glossary
terms and (b) provide direct links to their definitions.

We do provide a (probably little-known, little-used) command,
`search-emacs-glossary', that at least takes you to node `Glossary'.
But that is only rudimentary help, considering that so much information
is already organized to provide users term definitions.  What's missing
is better access to those, and more visibility for them.



In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2014-01-01 on ODIEONE
Bzr revision: 115827 eggert@cs.ucla.edu-20140101192741-bi5hb4xb4kdi2zpw
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 'CFLAGS=-O0 -g3' LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> Enhancement request.
>
> Inspired from a post on emacs-devel in thread "Apologia for bzr",
> 2014-01-03, which said,
>
>   I bet you can dip into any number of Info nodes where the terms
>   "buffer" and "window" are used without definition.
>
> That would be a non-issue if such terms were linked (automatically) to
> their glossary entries.  This feature should be optional, and even easy
> to toggle on/off.  The links should be highlighted differently, so users
> can easily tell that they are glossary links.
>
> Info manuals such as the Emacs manual are strong in actually providing
> an extensive glossary of terms.  But it is true that we do not leverage
> that feature by (a) showing, in the main text, which terms are glossary
> terms and (b) provide direct links to their definitions.
>
> We do provide a (probably little-known, little-used) command,
> `search-emacs-glossary', that at least takes you to node `Glossary'.
> But that is only rudimentary help, considering that so much information
> is already organized to provide users term definitions.  What's missing
> is better access to those, and more visibility for them.

I think this is a very interesting feature request, but it
unfortunately has received no reply.  I personally would love to see
this functionality, since I'm one of the users who almost always
forgets to check the glossary.

One can imagine hyperlinks working well.  Maybe it would work even
better with some kind of popup (an overlay or a new window?) that
automatically shows the glossary entry side by side with the current
info node.

Let's hope there is someone interested enough to take a stab at
this.  (Perhaps Drew would like to volunteer?)

Best regards,
Stefan Kangas

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 15 Jan 2020 20:47:09 +0100
> Cc: 16333@debbugs.gnu.org
> 
> Drew Adams <drew.adams@oracle.com> writes:
> 
> > Enhancement request.
> >
> > Inspired from a post on emacs-devel in thread "Apologia for bzr",
> > 2014-01-03, which said,
> >
> >   I bet you can dip into any number of Info nodes where the terms
> >   "buffer" and "window" are used without definition.
> >
> > That would be a non-issue if such terms were linked (automatically) to
> > their glossary entries.  This feature should be optional, and even easy
> > to toggle on/off.  The links should be highlighted differently, so users
> > can easily tell that they are glossary links.
> >
> 
> I think this is a very interesting feature request, but it
> unfortunately has received no reply.  I personally would love to see
> this functionality, since I'm one of the users who almost always
> forgets to check the glossary.

Our convention is to have index entries to all definitions.  For
example, type "i buffers RET", and you land where we define what is a
buffer.

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

[Drew Adams]

> 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.

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

[Drew Adams]

> Our convention is to have index entries to all definitions.  For
> example, type "i buffers RET", and you land where we define what is a
> buffer.

Yes, but that's not the same thing.  There are many completions
of `i buffer TAB', and there's no indication that the `buffers'
one will take you to a definition.  (An index entry like `buffer,
definition' would make that clear.)

In any case, the enhancement request explicitly acknowledged
that Emacs already provides ways to get to glossary items.
The request is to optionally highlight occurrences of the
term, so that you can notice that it's a glossary term and immediately jump to it from any context that uses it.

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

[Drew Adams]

> > 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.)

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

[Drew Adams]

> 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.

Nope.  That was wrong.  Guess I was seeing things.
Had to remove the parens for it to work.  Guess the
text really does need to start exactly with "mouse-2".

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

[Eli Zaretskii]

> Date: Wed, 28 Oct 2020 23:52:32 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 16333@debbugs.gnu.org
> 
> It turns out that the text need not exactly start with
> "mouse-2".

Yes.

> Dunno where that text transformation is implemented
> (in C?) - I didn't find it in the Lisp.

It's in mouse-fixup-help-message.

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

>> > 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.)

Could you prepare a patch?

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

[Drew Adams]

> > It turns out that the text need not exactly start with
> > "mouse-2".
> 
> Yes.
> 
> > Dunno where that text transformation is implemented
> > (in C?) - I didn't find it in the Lisp.
> 
> It's in mouse-fixup-help-message.

Ah, very good.  Thanks.  I grepped and searched a fair
amount, but I missed that.

But I think that shows (what I think I've seen - see
my correction to what I wrote that you replied to)
that the text _does_ need to start with "mouse-2":

  (string-match-p "\\`mouse-2" msg)

BTW, that doc string is not great.  It should mention
`help-echo', I think.  Grep `mouse-fixup-help-message'
finds no uses of it in Lisp.  So it's not clear, but
I'm guessing that it ends up being used indirectly(?)
only(?) by `help-echo'.
___

In any case, could this behavior (if not that function)
please be pointed out in the Elisp manual?  Users
writing help-echo text should be aware of the behavior.
___

Here's a suggestion, to make this less rigid/fragile:
Substitute for "mouse-2" everywhere in the help text,
as follows.

(defun mouse-fixup-help-message (msg)
  "Fix help message MSG for `mouse-1-click-follows-link'."
  (let (mp pos)
    (when (and mouse-1-click-follows-link
               (stringp msg)
               (string-match-p "mouse-2" msg)
               (setq mp  (mouse-pixel-position))
               (consp (setq pos (cdr mp)))
               (car pos) (>= (car pos) 0)
               (cdr pos) (>= (cdr pos) 0)
               (setq pos  (posn-at-x-y (car pos) (cdr pos) (car mp)))
               (windowp (posn-window pos)))
      (with-current-buffer (window-buffer (posn-window pos))
        (when (mouse-on-link-p pos)
          (setq msg  (replace-regexp-in-string
                      "mouse-2"
                      (concat
                       (cond ((eq mouse-1-click-follows-link 'double)
                              "double-")
                             ((and (integerp mouse-1-click-follows-link)
                                   (< mouse-1-click-follows-link 0))
                              "Long ")
                             (t ""))
                       "mouse-1")
                      msg))))))
  msg)
___

Or if you think it's more appropriate for some reason,
then substitute only the first occurrence of "mouse-2".

Of if you think we should let users specify exactly
which occurrences of "mouse-2" to substitute, then
define a formatting escape for that (e.g. "%m"), so
only "mouse-2" occurrences preceded by that escape get
substituted.  E.g., "xxx%mmouse-2" would substitute
the "mouse-2", but "xxxmouse-2" would not.

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

[Drew Adams]

> > Actually, I've done this now.  I added it to info+.el.
> > (It could of course be added to vanilla Emacs also.)
> 
> Could you prepare a patch?

I won't prepare a patch till you've tried the
enhancement and decided that you want it.

Been bit too many times by wasting time preparing
patches that don't get applied because the feature
isn't wanted.  If you want this I can provide it,
but decide first that you want it, please.

And I'd really prefer to include other fontifying
Info+ allows, fontifying options and commands, and
the `Toggle/Cycle' submenu of Info for them.

It's simple to take a look: load info+.el in
`emacs -Q' and move around.  For most fontifying
enhancements, try a manual such as Elisp, which
has lots of Lisp artifacts (backquoted sexps, etc.).

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

[Drew Adams]

> Here's a suggestion, to make this less rigid/fragile:
> Substitute for "mouse-2" everywhere in the help text,
> as follows.
> 
> (defun mouse-fixup-help-message (msg)
>   "Fix help message MSG for `mouse-1-click-follows-link'."
>   (let (mp pos)
>     (when (and mouse-1-click-follows-link
>                (stringp msg)
>                (string-match-p "mouse-2" msg)
>                (setq mp  (mouse-pixel-position))
>                (consp (setq pos (cdr mp)))
>                (car pos) (>= (car pos) 0)
>                (cdr pos) (>= (cdr pos) 0)
>                (setq pos  (posn-at-x-y (car pos) (cdr pos) (car mp)))
>                (windowp (posn-window pos)))
>       (with-current-buffer (window-buffer (posn-window pos))
>         (when (mouse-on-link-p pos)
>           (setq msg  (replace-regexp-in-string
>                       "mouse-2"
>                       (concat
>                        (cond ((eq mouse-1-click-follows-link 'double)
>                               "double-")
>                              ((and (integerp mouse-1-click-follows-link)
>                                    (< mouse-1-click-follows-link 0))
>                               "Long ")
>                              (t ""))
>                        "mouse-1")
>                       msg))))))
>   msg)
> ___
> 
> Or if you think it's more appropriate for some reason,
> then substitute only the first occurrence of "mouse-2".
> 
> Of if you think we should let users specify exactly
> which occurrences of "mouse-2" to substitute, then
> define a formatting escape for that (e.g. "%m"), so
> only "mouse-2" occurrences preceded by that escape get
> substituted.  E.g., "xxx%mmouse-2" would substitute
> the "mouse-2", but "xxxmouse-2" would not.


Actually, the following is much better.  It lets code
use different patterns in different contexts, by binding
the variable.

Should I submit this as a separate bug report, or can it
be considered in the context of this one?

(defvar mouse-fixup-help-replace-regexp
  '("\\(?:\\|[[:space:]]\\)\\(mouse-2\\)" . 1)
  "Regexp to match \"mouse-2\" in MSG.
The value is a cons (REGEXP . N).  Function `mouse-fixup-help-message'
replaces the match of subexpression N, of the text that matches
REGEXP, with \"mouse-1\".")

(defun mouse-fixup-help-message (msg)
  "Fix help message MSG for `mouse-1-click-follows-link'."
  (let (mp pos)
    (when (and mouse-1-click-follows-link
               (stringp msg)
               (string-match-p "mouse-2" msg)
               (setq mp  (mouse-pixel-position))
               (consp (setq pos (cdr mp)))
               (car pos) (>= (car pos) 0)
               (cdr pos) (>= (cdr pos) 0)
               (setq pos  (posn-at-x-y (car pos) (cdr pos) (car mp)))
               (windowp (posn-window pos)))
      (with-current-buffer (window-buffer (posn-window pos))
        (when (mouse-on-link-p pos)
          (setq msg  (replace-regexp-in-string
                      (car mouse-fixup-help-replace-regexp)
                      (concat
                       (cond ((eq mouse-1-click-follows-link 'double)
                              "double-")
                             ((and (integerp mouse-1-click-follows-link)
                                   (< mouse-1-click-follows-link 0))
                              "Long ")
                             (t ""))
                       "mouse-1")
                      msg nil nil (cdr mouse-fixup-help-replace-regexp)))))))
  msg)

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

[Eli Zaretskii]

> Date: Fri, 30 Oct 2020 14:14:54 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: stefan@marxist.se, 16333@debbugs.gnu.org
> 
> > Here's a suggestion, to make this less rigid/fragile:
> > Substitute for "mouse-2" everywhere in the help text,
> > as follows.
> > 
> > (defun mouse-fixup-help-message (msg)
> >   "Fix help message MSG for `mouse-1-click-follows-link'."
> >   (let (mp pos)
> >     (when (and mouse-1-click-follows-link
> >                (stringp msg)
> >                (string-match-p "mouse-2" msg)
> >                (setq mp  (mouse-pixel-position))
> >                (consp (setq pos (cdr mp)))
> >                (car pos) (>= (car pos) 0)
> >                (cdr pos) (>= (cdr pos) 0)
> >                (setq pos  (posn-at-x-y (car pos) (cdr pos) (car mp)))
> >                (windowp (posn-window pos)))
> >       (with-current-buffer (window-buffer (posn-window pos))
> >         (when (mouse-on-link-p pos)
> >           (setq msg  (replace-regexp-in-string
> >                       "mouse-2"
> >                       (concat
> >                        (cond ((eq mouse-1-click-follows-link 'double)
> >                               "double-")
> >                              ((and (integerp mouse-1-click-follows-link)
> >                                    (< mouse-1-click-follows-link 0))
> >                               "Long ")
> >                              (t ""))
> >                        "mouse-1")
> >                       msg))))))
> >   msg)
> > ___
> > 
> > Or if you think it's more appropriate for some reason,
> > then substitute only the first occurrence of "mouse-2".
> > 
> > Of if you think we should let users specify exactly
> > which occurrences of "mouse-2" to substitute, then
> > define a formatting escape for that (e.g. "%m"), so
> > only "mouse-2" occurrences preceded by that escape get
> > substituted.  E.g., "xxx%mmouse-2" would substitute
> > the "mouse-2", but "xxxmouse-2" would not.
> 
> 
> Actually, the following is much better.  It lets code
> use different patterns in different contexts, by binding
> the variable.
> 
> Should I submit this as a separate bug report, or can it
> be considered in the context of this one?

Please be sure to grep all our Lisp sources and make sure this change
won't replace stuff in places we don't want.  Please don't push this
before this check is complete, thanks.

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

[Drew Adams]

> > Actually, the following is much better.  It lets code
> > use different patterns in different contexts, by binding
> > the variable.
> >
> > Should I submit this as a separate bug report, or can it
> > be considered in the context of this one?
> 
> Please be sure to grep all our Lisp sources and make sure this change
> won't replace stuff in places we don't want.  Please don't push this
> before this check is complete, thanks.

Not sure if you're writing that to me or someone else.
I won't push anything.  I'm hoping someone else will
apply the change.

I did grep the Lisp sources for "mouse-2", which is
what is used in such help-echoes.  That's how I
found that all instances put it at the beginning of
the text, which led to the (correct) guess that
that's a requirement for the substitution to take
place.

I haven't tried to make the change and check the
effect on each of the Lisp-sources uses of a help-echo
with "mouse-2".  But since they all put "mouse-2" at
the beginning of the text, I don't expect any bother.

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

>> > Actually, I've done this now.  I added it to info+.el.
>> > (It could of course be added to vanilla Emacs also.)
>>
>> Could you prepare a patch?
>
> I won't prepare a patch till you've tried the
> enhancement and decided that you want it.
>
> Been bit too many times by wasting time preparing
> patches that don't get applied because the feature
> isn't wanted.  If you want this I can provide it,
> but decide first that you want it, please.
>
> And I'd really prefer to include other fontifying
> Info+ allows, fontifying options and commands, and
> the `Toggle/Cycle' submenu of Info for them.
>
> It's simple to take a look: load info+.el in
> `emacs -Q' and move around.  For most fontifying
> enhancements, try a manual such as Elisp, which
> has lots of Lisp artifacts (backquoted sexps, etc.).

That's fair enough.  So I've tested this, and I find that this
fontification is too noisy and distracting: it highlights every occasion
of "command", "customization", "variable", "Lisp" etc.  It even
highlights "window" in "window system", which is outright confusing...

Any other opinions here?

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> That's fair enough.  So I've tested this, and I find that this
> fontification is too noisy and distracting: it highlights every occasion
> of "command", "customization", "variable", "Lisp" etc.  It even
> highlights "window" in "window system", which is outright confusing...
>
> Any other opinions here?

Can you post some screenshots?  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Stefan Kangas]

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

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Can you post some screenshots?  :-)

See below.

[-- Attachment #2: bug16333.png --]
[-- Type: image/png, Size: 82132 bytes --]

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> See below.

Thanks.  Yeah, that looks really awkward -- I don't think we want to do
that in info.el.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Stefan Kangas]

tags 16333 wontfix
close 16333
thanks

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> See below.
>
> Thanks.  Yeah, that looks really awkward -- I don't think we want to do
> that in info.el.

Thanks, I'm therefore closing this bug report.