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

From: Eli Zaretskii <[email-masked]>
Date: Sat, 21 Jan 2023 10:21:22 +0200

> From: "H. Dieter Wilhelm" <[email-masked]>
> Cc: [email-masked],  [email-masked]
> Date: Fri, 20 Jan 2023 22:09:03 +0100
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> > I think a good place is to mention this feature in the "Misc Help"
> > section.
> 
> Could you please check if below formulation is better fitting?

Yes, but it "needs some work", see below.

> Unfortunately I also need to investigate the code anew.  Yesterday I
> realised a regression starting with Emacs-29!  `Tab' and `S-Tab' aren't
> working any longer for Info references.  (E.g. the `Tab' keybinding is
> switched from `Info-next-reference' to `forward-button'..)

So I guess you will be submitting a new patch soon?

> --- a/doc/emacs/help.texi
> +++ b/doc/emacs/help.texi
> @@ -653,6 +653,15 @@ Misc Help
>  K @var{key}}, described above, enter Info and go straight to the
>  documentation of @var{function} or @var{key}.
>  
> +  The commands @kbd{C-h f} and @kbd{C-h v}, also described above
> +(@xref{Name Help}), in an Info buffer can be replaced by @kbd{Ret} or
> +@kbd{mouse-1} on quoted symbol names.  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
> +references, with @kbd{Tab} and @kbd{S-Tab}.

I think the first sentence should be rewritten as describing a
separate feature, not "the same as" something else.  Just say that
symbols are converted into buttons that lead to their doc strings.

Also, the option which controls this should be mentioned and indexed.

> +** Info
> +
> ++++
> +*** Info-mode provides buttons on symbols showing their documentation string.
> +Quoted `symbols', like names of variables, functions or face names,
> +are made into buttons which can display the respective documentation
> +strings.  These strings are presented in *Help* buffers in another
> +window.  Such buttons are working independently of the regular Info
> +cross references and can be disabled with setting
> +`info-make-xref-flag' to nil.

This is OK.

Thanks.