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

From: Eli Zaretskii <[email-masked]>
Date: Sat, 28 Jan 2023 09:51:22 +0200

> From: "H. Dieter Wilhelm" <[email-masked]>
> Cc: Juri Linkov <[email-masked]>,  [email-masked],
>   [email-masked]
> Date: Fri, 27 Jan 2023 23:21:12 +0100
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> >> +  In Info buffers quoted symbol names are made into buttons which show
> >> +the symbols' help documentation when typing @key{RET} or clicking
> >> +@kbd{mouse-2} or @kbd{mouse-1} on it.  For example, the quoted name
> >> +@code{info-other-window} is made into a button which shows the
> >> +function's documentation string in another window, in the
> >> +@file{*Help*} buffer.  Such quoted symbols (variables, functions and
> >> +face names) are highlighted by a distinct face and can be reached, as
> >> +the Info manual references, with @key{TAB} and @kbd{S-Tab}.
> >
> > This is fine, but please try to reword to not use the passive tense so
> > much.
> 
> What do you think about the following formulation, is it already a
> better "mix"?
> 
>   Info makes quoted symbol names into buttons which show the symbols'
> help documentation when typing @key{RET} or clicking @kbd{mouse-2} or
> @kbd{mouse-1} on it.  For example, the quoted name
> @code{info-other-window} is made into a button which shows the
> function's documentation string in another window, in the
> @file{*Help*} buffer.  Info highlights such quoted symbols (variables,
> functions and face names) by a distinct face and these can be reached,
> as regular Info manual references, with @key{TAB} and @kbd{S-Tab}.

Yes, much better, thanks.

> Drew reminded me that it should be better to write solely @kbd{mouse-2}
> and / or possibly explaining `mouse-1-click-follows-link'.  I'm curious
> about your opinion.

I'd just say "click the mouse (@pxref{Mouse References})", since the
cross-referenced node already explains all of these subtleties, and
does it better.