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

["H. Dieter Wilhelm" <dieter@duenenhof-wilhelm.de>]

Hi Drew

Thank you for your ideas!

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

> 1.
> +  :type '(choice (const :tag "Create links" t)
> +                 (const :tag "Do not link" nil))
>
> is better as just :type 'boolean, and say in the
> doc which Boolean value means which behavior.

The doc string says now:

  "True (`t') means Emacs creates symbol link buttons in Info.
Setting this variable to `nil' inhibits the creation of buttons
on quoted symbols to their help strings.  Please see the function
`info-make-xrefs' for further details."

> 2.
> +;; Toggle on or off the linking to help documents
> +(when info-make-xref-flag
> +  (add-hook 'Info-selection-hook 'info-make-xrefs))

Yes, the above is rather crude.

> Instead of putting it on the hook when loading the
> code, add/remove it in a :set function.  E.g.
> (untested):
>
> :set (lambda (sym defs)
>        (custom-set-default sym defs)
>        (let ((fun  (if info-make-xref-flag
>                        #'add-hook
>                      #'remove-hook)))
>          (funcall fun 'Info-selection-hook
>                       'info-make-xrefs)))

It works nicely and I put this setter in `info-make-xref-flag'. :-)

> 3. Maybe add a toggle command for the option, so users can switch the
> behavior anytime, on the fly.

Like this?

;; TODO: add this toggle in info documentation and NEWS
;; TODO: remove and create buttons in current info buffer
(defun info-toggle-make-xrefs ()
  "Toggle creating Info buttons."
  (interactive)
  (if (memq 'info-make-xrefs Info-selection-hook)
      (remove-hook 'Info-selection-hook 'info-make-xrefs)
    (add-hook 'Info-selection-hook 'info-make-xrefs)
    (message "Create Info link buttons to symbol names.")))
 

> 4. Or instead of having an option, maybe just have
> a minor mode.

That's also a nice idea.  (Maybe for later.)

> 5. Face `info-color' should be named something like
> `info-symbol-help-link'.

You're right, `info-color' is too minimalist and not describing what the
object represents.

(I dropped it completely because I realised an additional face is
redundant since Info distinguishes (slightly) quoted symbols from the
text, anyway.)

> 6. "clicking @kbd{mouse-2} or @kbd{mouse-1} on it"
> can't be right, I think.  At least that doesn't
> express what `mouse-1-follows-link' does/means.

Do you mean that I should just say mouse-2, because
`mouse-1-click-follows-link' regulates it anyhow?  (E.g. I realised that
Emacs changes my documentation string for the tooltips

  'help-echo (purecopy "mouse-2, RET: describe this variable"))

from mouse-2 to mouse-1!)

> 7. Again, I think it's unhelpful to call these
> links "buttons".  Especially since Info docs call
> Info links "links".  That these links show their
> destination in another window isn't a reason to
> call them something different (and with no
> definition of the additional term "button").

To make the confusion complete: Info documentations calls (Info) links
also cross-references. ;-)

(info "(info)Help-Xref")

Thanks again

       Dieter

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany