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

From: Drew Adams <[email-masked]>
Date: Thu, 2 Feb 2023 02:30:26 +0000

> Drew Adams <[email-masked]> 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."
> >
> > Is the defcustom now :type 'boolean?
> 
> Please tell me why you insist now on changing the :type from choice to
> boolean?  Above you stated that it "is better than just :type boolean"!?

Misunderstanding.

1. I don't insist on anything.
2. I didn't say "is better than"; I said "is better as".

For #2: Sorry, I should have been less succinct.
I meant that (I think) that a `choice' such as what
you presented is simpler _as_ a `boolean' instead.
IOW, a boolean def is simpler.  I should have said
it that way.

> I experimented in `customize' with :type 'boolean and the "toggle"
> button is fast and easy.  On the other hand with 'choice I think the
> alternatives are clearer documented while changing it's values..

Yes, with `boolean' you can't specify a :tag.
But usually the doc string (which is also shown
in Customize) makes clear what each value does/means.

It was a minor comment.  There's nothing wrong with
using `choice' as you did.  Sorry for the noise.

> >> > 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...
> 
> Alright, I'm going in this direction but I'm not so fast.  😅

There's no hurry.

> >> > 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.
> 
> On the suggestion of Eli, I just stated `mouse' and added a cross
> reference, ahem, link to the mouse manual section.
> 
> Thanks for your interest

Thanks for working on this.
____

FWIW, I disagree with Eli here.  I think saying
which mouse button to use is better than just
saying click the mouse.  And which button to
click is taken care of automatically, if you use
\\[mouse-2], as you pointed out.
____

FWIW2: If `mouse-1-click-follows-link' is nil
then you can click `mouse-1' on a link to set
point there.  That's the advantage of that choice
(and it was what Emacs used to do by default).

If the value is non-nil then a user can click
mouse-1 to follow links, which is an advantage
in being what users are used to in browsers.
(With a non-nil value you have to press and hold
mouse-1 for a bit, to set point there.)

Since `mouse-2' is for yanking normally, and
since contexts where there are links typically
don't also allow yanking, the classic Emacs
approach was (still is) a smart one.

And in an editor I, at least, more often want
to use the mouse to set point, even on links -
more often than I want to yank with the mouse
in contexts that have links.  I prefer the old
default behavior, and I think Emacs should have
stuck with it.