GNU bug report logs - #60587
30.0.50; Info pages are lacking links from symbol names to the symbol's help documentation

Previous Next

Full log

Message #112 received at 60587 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "H. Dieter Wilhelm" <dieter <at> duenenhof-wilhelm.de>
Cc: Eli Zaretskii <eliz <at> gnu.org>,
 "60587 <at> debbugs.gnu.org" <60587 <at> debbugs.gnu.org>,
 "monnier <at> iro.umontreal.ca" <monnier <at> iro.umontreal.ca>
Subject: RE: [External] : bug#60587: Patch for adding links to symbols' help
 documentation
Date: Fri, 27 Jan 2023 23:13:36 +0000

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

Is the defcustom now :type 'boolean?

> > 3. Maybe add a toggle command for the option, so users can switch the
> > behavior anytime, on the fly.
> 
> Like this?...
>
> > 4. Or instead of having an option, maybe just have
> > a minor mode.
> 
> That's also a nice idea.  (Maybe for later.)

See Stefan's reply...

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

I think it's _good_ to have a separate face for this.
That gives users the choice:

* Have the same appearance for both kinds of link.
* Have the two kinds of link (Info, *Help*) look
  different.

When you provide two faces, users can always customize
them to look the same, if they like.  Otherwise, they
don't have that possibility.

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

Whatever Emacs expects.  Yes, I think that's what to
do - but someone may correct me.

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.