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

[Stefan Monnier]

H. Dieter Wilhelm [2023-02-15 23:18:17] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>>> +(define-minor-mode info-links-to-help-mode
>>> +  "The mode creates buttons on symbols linking to their documentation 
>>> string.
>>> +It shows their documentation in a *Help* buffers (in another
>>> +window) when typing <RET> or clicking `mouse-2' on the buttons.
>>> +These can be followed, as the regular Info manual references,
>>> +with \\[Info-next-reference] and \\[Info-prev-reference].
>>> +
>>> +For details about which symbols are considered and the linking
>>> +process itself please see the function `info-make-links-to-help'."
>>> +  :init-value nil
>>> +  :lighter " Hlp"
>>> +  :group 'info
>>> +  :version "30.1"
>>> +  (if info-links-to-help-mode
>>> +      (progn
>>> +        (if (eq major-mode 'Info-mode)
>>> +            ;; we need this under Info-mode because of the narrowed
>>> +            ;; Info file
>>> +            (add-hook 'Info-selection-hook 'info-make-links-to-help))
>>> +        (info-make-links-to-help))      ;for the current buffer
>>
>> The above `define-minor-mode` still defines a buffer-local minor mode
>
> I thought a minor mode is necessary when 'info-make-links-to-help' is
> supposed to work for arbitrary major modes and buffers besides Info.

I don't understand your remark.  I'm pointing out that the way you use
`define-minor-mode` above makes it buffer-local (if you want it to be
global, which is probably simpler you need to say `:global t`).

>> whereas the above `add-hook` is still global and hence affects all
>> buffers.
> I'm not sure I understand, it affects only Info buffers globally (eq
> major-mode 'Info-mode).

But it affects all Info-mode buffers whereas the
`info-links-to-help-mode` variable will only be set buffer-locally in
the current-buffer.  So you'll have Info-mode buffers where
`info-make-links-to-help` has been added to `Info-selection-hook` even
though its `info-links-to-help-mode` var is nil and you can have others
with the reverse.

> Do you think it is better to use a global minor mode for all Info
> buffers and a separate buffer local mode for other buffers (and major
> modes)?

If I were you, I'd just use a single global minor mode that affects all
Info-mode buffers (and only Info-mode buffers).  It should be rather rare
for a user to want to enable this in some buffers but not all.

We can easily add another global minor mode (using the same underlying
code) for the NEWS files if we want.

>> Better add a call to `info-links-to-help-mode` directly inside
>> `Info-mode`.
> (Please tell me why are you quoting with two grave accents and not with
> apostrophes?)

I try to follow the Markdown convention.

> Do you think setting
>
> (defcustom Info-mode-hook '(turn-on-font-lock info-links-to-help-mode)
>   "Hook run when activating Info Mode."
>   :type 'hook
>   :version "29.1")
>
> is a possible alternative to call it into 'Info-mode'?

I think I was confused because.  IIUC what you're trying to do is to
default this new minor mode to "enabled".  In that case I think your
code is somewhat OK though you should protect the `add-hook` with a test
for the value of the minor-mode to make sure you only run it when the
mode is enabled (which again only makes sense if the mode is global).


        Stefan