Subject: RE: [External] : bug#60587: Patch for adding links to symbols' help documentation

From: Drew Adams <[email-masked]>
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")