GNU bug report logs - #8951
24.0.50; [PATCH] enhancement request: buttonize key names

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 8951 in the body.
You can then email your comments to 8951 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; [PATCH] enhancement request: buttonize key names
Date: Tue, 28 Jun 2011 09:38:03 -0700

[Message part 1 (text/plain, inline)]

Sent to emacs-devel <at> gnu.org 2011/06/27:
http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg01081.html
 
Submitting as enhancement request.  Patch attached.
 
Here is another patch for Emacs help functions.  It handles
`describe-mode', `describe-function', and `describe-variable',
and the same feature it provides can be applied to other help
commands where appropriate.
 
What is the feature?  Let users click a key description (i.e., a
key name, such as `C-f') in a buffer such as *Help* to see the
associated help.  This applies to key descriptions derived from
\[...] doc patterns (only).
 
`substitute-command-keys' converts a doc string that uses
patterns such as `\[COMMAND]' to COMMAND's key description.
For example, it might convert `\[mouse-yank-secondary]' to
`<M-mouse-2>'.  It interprets COMMAND's bindings relative to a
given KEYMAP if that `\[...]' pattern is preceded by a
`\<KEYMAP>' pattern.
 
Once this conversion is done, however, the COMMAND and its KEYMAP
are lost, missing from the resulting doc string.  More
importantly, this information is lost to the code that uses the
conversion result - the code for `describe-variable' etc.
 
(Yes, the original string might be available to the calling code,
but that code would need to parse it to figure out the
correspondence between COMMAND and resulting key description.
IOW, it would need to do much of what `substitute-command-keys'
already does.)
 
The user sees only the description `<M-mouse-2>' in buffer *Help*
where the substituted doc string is used.  What if s?he wants to
know more about what that key does in the documented context?
S?he can hit `C-h k' and then try the key, but that will work
only if the current mode has the same binding (e.g., with KEYMAP
active for COMMAND).
 
The aim of the feature provided by the attached patch is to
replace such simple key descriptions, which were derived from
rich info (COMMAND and KEYMAP) about a documented context, with
help buttons that use that info to link to descriptions of the
commands associated with the keys.
 
The feature has the effect of giving `substitute-command-keys' an
optional arg that, when non-nil, makes that function not only
substitute the key description for the command but also buttonize
the key-description part of the result string.
 
The effect is that if the result string is inserted in a buffer
(e.g. *Help*) then the user can click or hit `RET' on the key
description (e.g. `<M-mouse-2>') to get help on the associated
command (e.g. `mouse-yank-secondary').
 
Actually, I did not patch the `substitute-command-keys' C code to
give it an extra arg for this.  Instead, I wrote a Lisp version:
`help-substitute-command-keys'.  (For the part that handles
\{...}, this function just calls `substitute-command-keys'.)  If
someone wants to patch the C code instead, go for it.
 
Similarly, I wrote Lisp wrappers for `documentation' and
`documentation-property' that accept the same optional arg and
pass it to `help-substitute-command-keys'.
 
Then, in the body of commands `describe-variable' etc., I changed
`(documentation X)' to `(help-documentation nil t)' to get the
buttonized help string.
 
Give it a try.  If you decide to go for the idea then you might
prefer to just add the optional arg to `substitute-command-keys'
rather than creating a separate function.  (I didn't have that
choice as a Lisp user.)
 
However, even in that case you might decide to opt for a Lisp
version (why not?) - IOW, move `substitute-command-keys' to Lisp.
 
You can do that by renaming `substitute-command-keys' to
<something>, removing most of the <something> code, and renaming
`help-substitute-command-keys' to `substitute-command-keys'.  A
small amount of the <something> C code is still needed to handle
the \{..} case (no buttons).
 
If you want to try it without applying the patches, you can just
download this library and load it:
http://www.emacswiki.org/emacs/download/help-fns%2b.el.  (In that
case you will also see the automatic Info links discussed in
thread "adding manual cross-ref links to *Help*":
http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html)
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-06-27 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/build/include'
 

[help-2011-06-27.patch (application/octet-stream, attachment)]

[help-fns-2011-06-27.patch (application/octet-stream, attachment)]

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8951 <at> debbugs.gnu.org
Subject: Re: bug#8951: 24.0.50;
	[PATCH] enhancement request: buttonize key names
Date: Mon, 04 Jul 2011 16:28:33 -0400

> What is the feature?  Let users click a key description (i.e., a
> key name, such as `C-f') in a buffer such as *Help* to see the
> associated help.  This applies to key descriptions derived from
> \[...] doc patterns (only).

That looks like a good idea.  Have you tried to plug it directly into
substitute-command-keys instead?  Are there places where such buttons
become annoying?

Basically, the thing I don't like about your patch is the resulting
redundancy between help-substitute-command-keys and
substitute-command-keys, which could be removed by getting rid of the
C version and only using the new Elisp version.


        Stefan

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 8951 <at> debbugs.gnu.org
Subject: RE: bug#8951: 24.0.50;
	[PATCH] enhancement request: buttonize key names
Date: Mon, 4 Jul 2011 14:08:19 -0700

> > Let users click a key description (i.e., a key name, such as
> > `C-f') in a buffer such as *Help* to see the associated help.
> > This applies to key descriptions derived from \[...] doc
> > patterns (only).
> 
> That looks like a good idea.  Have you tried to plug it directly into
> substitute-command-keys instead?  Are there places where such buttons
> become annoying?
> 
> Basically, the thing I don't like about your patch is the resulting
> redundancy between help-substitute-command-keys and
> substitute-command-keys, which could be removed by getting rid of the
> C version and only using the new Elisp version.

See the emacs-devel thread, where I addressed both of these things.
http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg01081.html

I wrote Lisp, but if someone wants to instead patch the C code for
`substitute-command-keys' then go for it.

The Lisp version I wrote still invokes the original C code for the \\{...} case.
I did not try to rewrite that in Lisp.

IMO, the best solution would be to:

1. Keep the Lisp code I wrote (or similar), renaming it to
`substitute-command-keys'.

2. Simplify the original C code to handle just the \\{...} case, rename that
function, and use it in #1 to handle the \\{...} parts (just as now, but under
its new, {}-specific name).

Alternatively, you can write #2 in Lisp, if you like.


Wrt your question of whether "there are places where such buttons become
annoying": I would say that it does not matter whether there are currently any
such places.  There is no reason not to treat the buttonizing as optional.

`substitute-command-keys' produces a string from a string - typically doc.  But
the use of the output string need not be for a *Help* buffer (or similar context
where buttons are appropriate).  There is no reason to always buttonize these
parts of the output string.  Making buttonizing optional provides flexibility,
at no cost.  Nothing would be gained by making it mandatory.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8951 <at> debbugs.gnu.org
Subject: Re: bug#8951: 24.0.50;
	[PATCH] enhancement request: buttonize key names
Date: Wed, 06 Jul 2011 14:49:11 -0400

>> Basically, the thing I don't like about your patch is the resulting
>> redundancy between help-substitute-command-keys and
>> substitute-command-keys, which could be removed by getting rid of the
>> C version and only using the new Elisp version.

> See the emacs-devel thread, where I addressed both of these things.
> http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg01081.html

I don't think that quite addresses it.  But, I guess it does indirectly:
you apparently haven't found problematic cases that require
distinguishing help-substitute-command-keys from
substitute-command-keys.  Instead you just personally prefer to keep the
option whether to buttonize or not.

> I wrote Lisp, but if someone wants to instead patch the C code for
> `substitute-command-keys' then go for it.

No, I'm not interested in making this C code more complicated.  I want
to go the other way around.

> The Lisp version I wrote still invokes the original C code for the
> \\{...} case.  I did not try to rewrite that in Lisp.

I see.  It should be pretty easy to do, easy exporting the needed
underlying C function to Elisp, or rewriting it in Elisp (there's no
good reason to have describe-buffer-bindings written in C, really).

> 1. Keep the Lisp code I wrote (or similar), renaming it to
> `substitute-command-keys'.

Sounds good.

> 2. Simplify the original C code to handle just the \\{...} case,
> rename that function, and use it in #1 to handle the \\{...} parts
> (just as now, but under its new, {}-specific name).

Sounds good.

> Alternatively, you can write #2 in Lisp, if you like.

Sounds good as well.

> Wrt your question of whether "there are places where such buttons
> become annoying": I would say that it does not matter whether there
> are currently any such places.  There is no reason not to treat the
> buttonizing as optional.

Of course there's the reason that providing a choice is never free, so
we should only provide the choice if there's a good reason for it.


        Stefan

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 8951 <at> debbugs.gnu.org
Subject: RE: bug#8951: 24.0.50;
	[PATCH] enhancement request: buttonize key names
Date: Wed, 6 Jul 2011 12:55:05 -0700

> >> getting rid of the C version and only using the new Elisp version.
> > See the emacs-devel thread, where I addressed both of these things.
> > http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg01081.html
> 
> I don't think that quite addresses it.  But, I guess it does 
> indirectly: you apparently haven't found problematic cases
> that require distinguishing help-substitute-command-keys from
> substitute-command-keys.  Instead you just personally prefer 
> to keep the option whether to buttonize or not.

Yes, I suggested that `substitute-command-keys' itself be modified to accept the
optional argument.  I did not try to replace `substitute-command-keys' directly
with a version that has the optional arg to buttonize, because (a) I didn't want
to hack the C code and (b) I didn't want to bother writing the \\{...} code in
Lisp.

> > I wrote Lisp, but if someone wants to instead patch the C code for
> > `substitute-command-keys' then go for it.
> 
> No, I'm not interested in making this C code more complicated.  I want
> to go the other way around.

Glad to hear that.  That's my preference too.

> > The Lisp version I wrote still invokes the original C code for the
> > \\{...} case.  I did not try to rewrite that in Lisp.
> 
> I see.  It should be pretty easy to do, easy exporting the needed
> underlying C function to Elisp, or rewriting it in Elisp (there's no
> good reason to have describe-buffer-bindings written in C, really).

Please, go for it.  I agree.

> > 1. Keep the Lisp code I wrote (or similar), renaming it to
> > `substitute-command-keys'.
> 
> Sounds good.
> 
> > 2. Simplify the original C code to handle just the \\{...} case,
> > rename that function, and use it in #1 to handle the \\{...} parts
> > (just as now, but under its new, {}-specific name).
> 
> Sounds good.
> 
> > Alternatively, you can write #2 in Lisp, if you like.
> 
> Sounds good as well.
> 
> > Wrt your question of whether "there are places where such buttons
> > become annoying": I would say that it does not matter whether there
> > are currently any such places.  There is no reason not to treat the
> > buttonizing as optional.
> 
> Of course there's the reason that providing a choice is never free, so
> we should only provide the choice if there's a good reason for it.

I gave this reason to make it optional:

\\[], \\<>, \\{} are about mapping command names to corresponding key
descriptions - nothing more.  That in itself does not say anything about help
buffers and interactivity (clicking, RET).  The function is just a string
transducer.

The common use case for that is of course doc.  And the common use case for the
doc use case is a help buffer.

But a string of doc is more general than a help buffer, both in terms of string
vs buffer and in terms of the need for button text properties (interactivity).
There could be applications of this function to produce a readable string that
do not involve a button-clicking interactive context.

"providing a choice is never free" -

What's the cost?  And what's the cost of always doing the extra lifting of
creating buttons?

Code maintenance will be at least as easy if it is optional, possibly easier
since the additional buttonizing part is well separated.  And not creating
buttons (properties) saves a little time and memory (but that's probably not
very significant).

No, I don't feel strongly about making buttonizing optional.  But I don't see
why you wouldn't do that.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8951 <at> debbugs.gnu.org
Subject: Re: bug#8951: 24.0.50;
	[PATCH] enhancement request: buttonize key names
Date: Fri, 08 Jul 2011 15:07:56 -0400

>> > The Lisp version I wrote still invokes the original C code for the
>> > \\{...} case.  I did not try to rewrite that in Lisp.
>> I see.  It should be pretty easy to do, easy exporting the needed
>> underlying C function to Elisp, or rewriting it in Elisp (there's no
>> good reason to have describe-buffer-bindings written in C, really).
> Please, go for it.  I agree.

Please send an updated patch so we can install it in the `pending' branch.


        Stefan

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 8951 <at> debbugs.gnu.org
Subject: RE: bug#8951: 24.0.50;
	[PATCH] enhancement request: buttonize key names
Date: Fri, 8 Jul 2011 12:20:27 -0700

> >> > The Lisp version I wrote still invokes the original C 
> >> > code for the \\{...} case.  I did not try to rewrite
> >> > that in Lisp.
> >>
> >> I see.  It should be pretty easy to do, easy exporting the needed
> >> underlying C function to Elisp, or rewriting it in Elisp 
> >> (there's no good reason to have describe-buffer-bindings
> >> written in C, really).
> >
> > Please, go for it.  I agree.
> 
> Please send an updated patch so we can install it in the 
> `pending' branch.

Do you mean just redo what I did using the latest source code for the diff?  I
would be glad to do that, if that's all you meant.  Let me know.

For the rest (migration from C, changing C code, etc.), someone else will need
to do it.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 'Stefan Monnier' <monnier <at> iro.umontreal.ca>, 8951 <at> debbugs.gnu.org
Subject: Re: bug#8951: 24.0.50;
 [PATCH] enhancement request: buttonize key names
Date: Thu, 27 Jun 2019 18:35:27 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

>> >> > The Lisp version I wrote still invokes the original C 
>> >> > code for the \\{...} case.  I did not try to rewrite
>> >> > that in Lisp.
>> >>
>> >> I see.  It should be pretty easy to do, easy exporting the needed
>> >> underlying C function to Elisp, or rewriting it in Elisp 
>> >> (there's no good reason to have describe-buffer-bindings
>> >> written in C, really).
>> >
>> > Please, go for it.  I agree.
>> 
>> Please send an updated patch so we can install it in the 
>> `pending' branch.
>
> Do you mean just redo what I did using the latest source code for the diff?  I
> would be glad to do that, if that's all you meant.  Let me know.
>
> For the rest (migration from C, changing C code, etc.), someone else will need
> to do it.

I'm guessing that Stefan asked you to rewrite substitute-command-keys in
Lisp.

It makes sense to do that, I think, and it seems like a nice little
project that somebody should undertake.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: lekktu <at> gmail.com, Eli Zaretskii <eliz <at> gnu.org>, 8951 <at> debbugs.gnu.org,
 17052 <at> debbugs.gnu.org
Subject: Re: bug#17052: substitute-command-keys strips text properties
Date: Sun, 18 Aug 2019 19:08:18 +0200

[In reply to Bug#17052 and cross-posting to Bug#8951.]

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> I had a look at that function now and, er, no.  :-)  Perhaps it should
> be rewritten in Emacs Lisp?  Then it'd be pretty trivial to fix this
> stuff.

The Fsubstitute_command_keys function is indeed a bit hairy, and I
agree that a conversion to Lisp is the most reasonable next step.

I've actually been working a patch to convert it to Lisp for Bug#8951,
but it's not finished yet.  The difficulty is that it has a couple of
helper functions that also needs to be lifted, which makes the job
bigger than just the function Fsubstitute_command_keys.

My goal is to get the Lisp version to produce the same output as the C
version, which currently seems to be a feasible goal.  Once it's in
Lisp it should be easier to make further improvements, fix bugs, etc.

Thanks,
Stefan Kangas

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: lekktu <at> gmail.com, larsi <at> gnus.org, 8951 <at> debbugs.gnu.org,
 17052 <at> debbugs.gnu.org
Subject: Re: bug#17052: substitute-command-keys strips text properties
Date: Sun, 18 Aug 2019 20:19:26 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sun, 18 Aug 2019 19:08:18 +0200
> Cc: Eli Zaretskii <eliz <at> gnu.org>, 17052 <at> debbugs.gnu.org, lekktu <at> gmail.com, 
> 	8951 <at> debbugs.gnu.org
> 
> > I had a look at that function now and, er, no.  :-)  Perhaps it should
> > be rewritten in Emacs Lisp?  Then it'd be pretty trivial to fix this
> > stuff.
> 
> The Fsubstitute_command_keys function is indeed a bit hairy, and I
> agree that a conversion to Lisp is the most reasonable next step.
> 
> I've actually been working a patch to convert it to Lisp for Bug#8951,
> but it's not finished yet.  The difficulty is that it has a couple of
> helper functions that also needs to be lifted, which makes the job
> bigger than just the function Fsubstitute_command_keys.
> 
> My goal is to get the Lisp version to produce the same output as the C
> version, which currently seems to be a feasible goal.  Once it's in
> Lisp it should be easier to make further improvements, fix bugs, etc.

Maybe we should first talk a bit about why Lars you think it would be
"pretty trivial" to keep properties in Lisp, but not in C.  I'm
probably missing something very basic here, because I don't see why
it would be easier in Lisp.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: lekktu <at> gmail.com, Eli Zaretskii <eliz <at> gnu.org>, 8951 <at> debbugs.gnu.org,
 17052 <at> debbugs.gnu.org
Subject: Re: bug#17052: substitute-command-keys strips text properties
Date: Sun, 18 Aug 2019 10:19:48 -0700

Stefan Kangas <stefan <at> marxist.se> writes:

> I've actually been working a patch to convert it to Lisp for Bug#8951,
> but it's not finished yet.  The difficulty is that it has a couple of
> helper functions that also needs to be lifted, which makes the job
> bigger than just the function Fsubstitute_command_keys.
>
> My goal is to get the Lisp version to produce the same output as the C
> version, which currently seems to be a feasible goal.  Once it's in
> Lisp it should be easier to make further improvements, fix bugs, etc.

Sounds great!

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: lekktu <at> gmail.com, Stefan Kangas <stefan <at> marxist.se>, 8951 <at> debbugs.gnu.org,
 17052 <at> debbugs.gnu.org
Subject: Re: bug#17052: substitute-command-keys strips text properties
Date: Sun, 18 Aug 2019 15:43:35 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

> Maybe we should first talk a bit about why Lars you think it would be
> "pretty trivial" to keep properties in Lisp, but not in C.  I'm
> probably missing something very basic here, because I don't see why
> it would be easier in Lisp.

Anything is easier in Lisp, surely.

But if you look at that function in particular, it's written in a very
C-ey fashion, what with copying over characters one by one etc.  It
could be rewritten (in C) to use the proper primitives we have that
preserve text properties (Fsubstring etc), but then you'd just end up
with a more long-winded version that would be Lisp-in-C, so we might as
well just rewrite it in Lisp.

It'll probably be a fraction of the code length.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: lekktu <at> gmail.com, stefan <at> marxist.se, 8951 <at> debbugs.gnu.org,
 17052 <at> debbugs.gnu.org
Subject: Re: bug#17052: substitute-command-keys strips text properties
Date: Mon, 19 Aug 2019 18:27:32 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: Stefan Kangas <stefan <at> marxist.se>,  17052 <at> debbugs.gnu.org,
>   lekktu <at> gmail.com,  8951 <at> debbugs.gnu.org
> Date: Sun, 18 Aug 2019 15:43:35 -0700
> 
> But if you look at that function in particular, it's written in a very
> C-ey fashion, what with copying over characters one by one etc.  It
> could be rewritten (in C) to use the proper primitives we have that
> preserve text properties (Fsubstring etc), but then you'd just end up
> with a more long-winded version that would be Lisp-in-C, so we might as
> well just rewrite it in Lisp.

AFAIU, the problematic parts are not those which copy characters one
by one, the problematic parts are those which _substitute_ one text
with another.  In that case, you need to adjust the text properties or
cons them out of thin air.

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

From: 積丹尼 Dan Jacobson <jidanni <at> jidanni.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 8951 <at> debbugs.gnu.org, rms <at> gnu.org,
 44909 <at> debbugs.gnu.org
Subject: Re: bug#44909: Hyperlinks gone for first story of two-storied
 *Help* buffers
Date: Sun, 29 Nov 2020 04:45:51 +0800

Eli Zaretskii <eliz <at> gnu.org> writes:
> They are not hyperlinks, they are names of commands.

I see. In
https://debbugs.gnu.org/cgi/bugreport.cgi?msg=5;filename=so-bad.png;bug=44909;att=1

The first two
Use M-x so-long-commentary for more information.
Use M-x so-long-customize to configure the behaviour.
should continue not to be hyperlinked.

Unlike the second two
Use M-x so-long-commentary for more information.
Use M-x so-long-customize to configure the behaviour.

Wonder what RMS thinks.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 8951 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#8951: 24.0.50;
 [PATCH] enhancement request: buttonize key names
Date: Fri, 22 Oct 2021 17:46:24 -0700

[Message part 1 (text/plain, inline)]

tags 8951 + patch
thanks

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> What is the feature?  Let users click a key description (i.e., a
>> key name, such as `C-f') in a buffer such as *Help* to see the
>> associated help.  This applies to key descriptions derived from
>> \[...] doc patterns (only).
>
> That looks like a good idea.  Have you tried to plug it directly into
> substitute-command-keys instead?  Are there places where such buttons
> become annoying?

(I have had a patch sitting around for a while, but it failed bootstrap.
It turns out that the fix was a simple `fboundp', heh.)

The attached patch adds a new option `help-mode--add-function-link' that
when non-nil makes `substitute-command-keys' add a link to the
`describe-function' for the bound command when inserting keys.

I have reconsidered my previously held opinion that this should be off
by default.  From using this patch, I have come to the conclusion that
this position is wrong, as this is in fact highly useful in places such
as `M-x ibuffer RET C-h m' and on many other help screen besides.  The
only adverse effect of enabling it, furthermore, is that you might have
to hit TAB a couple of times more on some help screens.  So I think
having it on by default is very much a good thing.

[0001-Add-new-option-help-link-key-to-documentation.patch (text/x-diff, attachment)]

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 8951 <at> debbugs.gnu.org
Subject: Re: bug#8951: 24.0.50; [PATCH] enhancement request: buttonize key
 names
Date: Sun, 24 Oct 2021 15:36:26 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

> The attached patch adds a new option `help-mode--add-function-link' that
> when non-nil makes `substitute-command-keys' add a link to the
> `describe-function' for the bound command when inserting keys.

Looks like a good idea to me.

> I have reconsidered my previously held opinion that this should be off
> by default.  From using this patch, I have come to the conclusion that
> this position is wrong, as this is in fact highly useful in places such
> as `M-x ibuffer RET C-h m' and on many other help screen besides.  The
> only adverse effect of enabling it, furthermore, is that you might have
> to hit TAB a couple of times more on some help screens.  So I think
> having it on by default is very much a good thing.

Yes, me too.  We can try it out, at least, and see how it works in
practice, but it sounds really useful to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 8951 <at> debbugs.gnu.org
Subject: Re: bug#8951: 24.0.50;
 [PATCH] enhancement request: buttonize key names
Date: Sun, 24 Oct 2021 06:54:57 -0700

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Yes, me too.  We can try it out, at least, and see how it works in
> practice, but it sounds really useful to me.

Right, and if it turns out that people hate it, it is trivial to flip
the switch to nil before Emacs 29.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 8951 <at> debbugs.gnu.org
Subject: Re: bug#8951: 24.0.50; [PATCH] enhancement request: buttonize key
 names
Date: Sun, 24 Oct 2021 16:15:51 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

> Right, and if it turns out that people hate it, it is trivial to flip
> the switch to nil before Emacs 29.

Yup.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 8951 <at> debbugs.gnu.org
Subject: Re: bug#8951: 24.0.50;
 [PATCH] enhancement request: buttonize key names
Date: Sun, 24 Oct 2021 07:56:56 -0700

close 8951 29.1
thanks

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> marxist.se> writes:
>
>> Right, and if it turns out that people hate it, it is trivial to flip
>> the switch to nil before Emacs 29.
>
> Yup.

Now pushed to master (commit 68d11cc248).

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Stefan Monnier
 <monnier <at> iro.umontreal.ca>
Cc: "8951 <at> debbugs.gnu.org" <8951 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#8951: 24.0.50; [PATCH] enhancement request:
 buttonize key names
Date: Sun, 24 Oct 2021 21:07:53 +0000

> >> What is the feature?  Let users click a key description (i.e., a
> >> key name, such as `C-f') in a buffer such as *Help* to see the
> >> associated help.  This applies to key descriptions derived from
> >> \[...] doc patterns (only).
> 
> The attached patch adds a new option `help-mode--add-function-link'
> that when non-nil makes `substitute-command-keys' add a link to the
> `describe-function' for the bound command when inserting keys.
> 
> I have reconsidered my previously held opinion that this should be off
> by default.  From using this patch, I have come to the conclusion that
> this position is wrong, as this is in fact highly useful in places such
> as `M-x ibuffer RET C-h m' and on many other help screen besides.  The
> only adverse effect of enabling it, furthermore, is that you might have
> to hit TAB a couple of times more on some help screens.  So I think
> having it on by default is very much a good thing.

Glad you decided this is worthwhile, after all.

You seem to have ignored this, from https://debbugs.gnu.org/cgi/bugreport.cgi?bug=8951#17:

 I gave this reason to make it optional:

 \\[], \\<>, \\{} are about mapping command names to
 corresponding key descriptions - nothing more.  That
 in itself does not say anything about help buffers
 and interactivity (clicking, RET).  The function is
 just a string transducer.

 The common use case for that is of course doc.  And
 the common use case for the doc use case is a help buffer.

 But a string of doc is more general than a help buffer,
 both in terms of string vs buffer and in terms of the
 need for button text properties (interactivity).  There
 could be applications of this function to produce a
 readable string that do not involve a button-clicking
 interactive context.

Instead of making the choice of whether to fontify/link
key descriptions (1) depend only on a user option
(dynamically scoped variable) and (2) hard-coupling it
to use of the result in a *Help* buffer, I argued for
(1) adding an optional arg to `substitute-command-keys'
(to make the choice), and (2) separating creation of the
resulting fontified/ linkified key description from its
use in *Help* output.

I think my approach is preferable.  I suggest it still.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: "8951 <at> debbugs.gnu.org" <8951 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#8951: 24.0.50; [PATCH] enhancement request:
 buttonize key names
Date: Sun, 24 Oct 2021 14:37:14 -0700

Drew Adams <drew.adams <at> oracle.com> writes:

> Instead of making the choice of whether to fontify/link
> key descriptions (1) depend only on a user option
> (dynamically scoped variable) and (2) hard-coupling it
> to use of the result in a *Help* buffer, I argued for
> (1) adding an optional arg to `substitute-command-keys'
> (to make the choice),

I don't see the use-case.  I know of no places where the added linking
is not desirable, if the user has already said that she wants it in the
help buffer.

> and (2) separating creation of the resulting fontified/ linkified key
> description from its use in *Help* output.

I agree with this, but as we have discussed elsewhere this goes further
and deeper than this option.  It would amount to a major rethinking or
rewrite of help.el itself.  I hope that we will do that, eventually.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Stefan Monnier
 <monnier <at> iro.umontreal.ca>
Cc: "8951 <at> debbugs.gnu.org" <8951 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#8951: 24.0.50; [PATCH] enhancement request:
 buttonize key names
Date: Sun, 24 Oct 2021 22:05:46 +0000

> > Instead of making the choice of whether to fontify/link
> > key descriptions (1) depend only on a user option
> > (dynamically scoped variable) and (2) hard-coupling it
> > to use of the result in a *Help* buffer, I argued for
> > (1) adding an optional arg to `substitute-command-keys'
> > (to make the choice),
> 
> I don't see the use-case.  I know of no places where the added linking
> is not desirable, if the user has already said that she wants it in the
> help buffer.

I'm suggesting it's not only a question of the help buffer,
and not only a question of a user option.  It's about code
that can optionally fontify/link key descriptions.  That
code can be used for *Help*, but it can be used elsewhere
as well.

`substitute-command-keys' is a general function; it's not
used only for *Help* output.  Why not give it an optional
arg to do this font/linkifying?

> > and (2) separating creation of the resulting fontified/
> > linkified key description from its use in *Help* output.
> 
> I agree with this, but as we have discussed elsewhere this goes further
> and deeper than this option.  It would amount to a major rethinking or
> rewrite of help.el itself.  I hope that we will do that, eventually.

I don't know what you mean there, or what other discussion
you're referring to.  See above; the two are related.

`substitute-command-keys' is such a function: it takes a
string and returns a string.  Give it an optional arg to
have the returned string have the properties needed.

This is what the code I use does.  See the patch at the
outset of this bug thread.  (Of course, as discussed in
this thread it will also be good to move everything to
Lisp.  But the separation I'm talking about is not
dependent on our having done that.)

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: "8951 <at> debbugs.gnu.org" <8951 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#8951: 24.0.50; [PATCH] enhancement request:
 buttonize key names
Date: Sun, 24 Oct 2021 15:24:49 -0700

Drew Adams <drew.adams <at> oracle.com> writes:

> `substitute-command-keys' is a general function; it's not
> used only for *Help* output.  Why not give it an optional
> arg to do this font/linkifying?

I prefer not to, unless we have a use-case for it.  YAGNI.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Stefan Monnier
 <monnier <at> iro.umontreal.ca>
Cc: "8951 <at> debbugs.gnu.org" <8951 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#8951: 24.0.50; [PATCH] enhancement request:
 buttonize key names
Date: Sun, 24 Oct 2021 22:47:23 +0000

> > `substitute-command-keys' is a general function; it's not
> > used only for *Help* output.  Why not give it an optional
> > arg to do this font/linkifying?
> 
> I prefer not to, unless we have a use-case for it.  YAGNI.

Grep even just the vanilla Emacs-Lisp sources for
`substitute-command-keys'.  It's not used only for
*Help*.  And then think about uses by other code,
besides vanilla Emacs.

What's the reason you prefer not to?  I don't
understand.  Maybe you have a good reason, but
I don't think you gave any (?).

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: "8951 <at> debbugs.gnu.org" <8951 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#8951: 24.0.50; [PATCH] enhancement request:
 buttonize key names
Date: Sun, 24 Oct 2021 16:15:41 -0700

Drew Adams <drew.adams <at> oracle.com> writes:

> Grep even just the vanilla Emacs-Lisp sources for
> `substitute-command-keys'.  It's not used only for
> *Help*.  And then think about uses by other code,
> besides vanilla Emacs.

I only see a lot of places where we want whatever the user has
configured, none where we need an optional argument.

> What's the reason you prefer not to?  I don't
> understand.  Maybe you have a good reason, but
> I don't think you gave any (?).

I'm repeating myself here: I'm actually happy to add it, if we have a
use-case.  How about we try this for a start, and once users start using
this in the wild, they'll come back to us and say: hey I really want an
optional parameter here.  Then we think about if that makes sense for
their use-case, maybe it will, maybe it won't.  But at least we know
what we are trying to do.

The alternative is that we add stuff just because "maybe someone will
need it".  That leads to feature creep, bloat, and is just not a good
way to develop software.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Stefan Monnier
 <monnier <at> iro.umontreal.ca>
Cc: "8951 <at> debbugs.gnu.org" <8951 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#8951: 24.0.50; [PATCH] enhancement request:
 buttonize key names
Date: Mon, 25 Oct 2021 01:32:53 +0000

> > Grep even just the vanilla Emacs-Lisp sources for
> > `substitute-command-keys'.  It's not used only for
> > *Help*.  And then think about uses by other code,
> > besides vanilla Emacs.
> 
> I only see a lot of places where we want whatever the user
> has configured, none where we need an optional argument.
>
> > What's the reason you prefer not to?  I don't
> > understand.  Maybe you have a good reason, but
> > I don't think you gave any (?).
> 
> I'm repeating myself here: 

Actually, though you may be repeating, you still
haven't given a reason for your preference.  It's
OK with me if you have no reason - just wanted to
understand, in case I was missing something.

> I'm actually happy to add it, if we have a
> use-case.  How about we try this for a start,
> and once users start using
> this in the wild, they'll come back to us and say: hey I really want an
> optional parameter here.  Then we think about if that makes sense for
> their use-case, maybe it will, maybe it won't.  But at least we know
> what we are trying to do.
> 
> The alternative is that we add stuff just because "maybe someone will
> need it".  That leads to feature creep, bloat, and is just not a good
> way to develop software.

An alternative is to not add a user option for
this just because maybe some user will need it.
You know - feature creep, bloat...

And to give users who write Lisp code the
ability to buttonize or not, wherever they use
`substitute-command-keys'.
___

That's what I did in help-fns+.el.  Never had
anyone request a user option to not have the
links.  Since 2011 - ten years in the wild.

Of course, I'd have had nothing against adding
an option for that, if users came back to me
and said: hey I really want a option for it.

In general, I'm not one who's particularly
opposed to dynamic global variables, or even to
binding them to affect behavior.  But in this
case I thought an arg was sufficient.
___

FWIW, you'll notice that there are several uses
of the original, vanilla `substitute-command-keys'
in help-fns+.el.  I don't recall the details, but
no doubt I thought those occurrences should not
buttonize key descriptions.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: "8951 <at> debbugs.gnu.org" <8951 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#8951: 24.0.50; [PATCH] enhancement request:
 buttonize key names
Date: Sun, 24 Oct 2021 19:37:19 -0700

Drew Adams <drew.adams <at> oracle.com> writes:

> Actually, though you may be repeating, you still
> haven't given a reason for your preference.  It's
> OK with me if you have no reason - just wanted to
> understand, in case I was missing something.

I have given my reason.  You may agree or disagree.

> That's what I did in help-fns+.el.  Never had
> anyone request a user option to not have the
> links.  Since 2011 - ten years in the wild.

Emacs has more users though.  But maybe we also don't need an option.
I have no strong opinion about that.

Previous Next

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