GNU bug report logs - #37785
[PATCH] Add a way to disable substitution of command keys in help strings

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 37785 in the body.
You can then email your comments to 37785 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: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
To: bug-gnu-emacs <bug-gnu-emacs <at> gnu.org>
Subject: [PATCH] Add a way to disable substitution of command keys in help
 strings
Date: Wed, 16 Oct 2019 21:41:27 -0400

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

Hi all,

On 2019-10-05 04:13, Eli Zaretskii wrote (on emacs-devel):
> I guess we need to add some feature to control whether help-echo gets
> run through substitute-command-keys, or add an alternative to
> help-echo that works exactly like it, but without substitutions.
> Patches welcome.
[…]
> I'd prefer a property like help-echo-inhibit-substitution that is
> non-nil, to inhibit the call to substitute-command-keys.  A value of
> nil is easy to confuse with no property at all.

Here is a first cut at a patch implementing this feature.  I hope this tracker is the right place to post it.  I'm also not quite sure I got the Changelog format right.

Cheers,
Clément.

[0001-Add-a-way-to-disable-substitution-of-command-keys-in.patch (text/x-patch, attachment)]

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

From: Robert Pluim <rpluim <at> gmail.com>
To: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
Cc: 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Thu, 17 Oct 2019 11:44:50 +0200

>>>>> On Wed, 16 Oct 2019 21:41:27 -0400, Clément Pit-Claudel <cpitclaudel <at> gmail.com> said:

    Clément> Hi all,
    Clément> On 2019-10-05 04:13, Eli Zaretskii wrote (on emacs-devel):
    >> I guess we need to add some feature to control whether help-echo gets
    >> run through substitute-command-keys, or add an alternative to
    >> help-echo that works exactly like it, but without substitutions.
    >> Patches welcome.
    Clément> […]
    >> I'd prefer a property like help-echo-inhibit-substitution that is
    >> non-nil, to inhibit the call to substitute-command-keys.  A value of
    >> nil is easy to confuse with no property at all.

    Clément> Here is a first cut at a patch implementing this feature.  I hope this
    Clément> tracker is the right place to post it.  I'm also not quite sure I got
    Clément> the Changelog format right.

    Clément> Cheers,
    Clément> Clément.

    Clément> From 8092b19d819182c91e6066d24f243dc7d7d8641e Mon Sep 17 00:00:00 2001
    Clément> From: =?UTF-8?q?Cl=C3=A9ment=20Pit-Claudel?= <clement.pitclaudel <at> live.com>
    Clément> Date: Wed, 16 Oct 2019 21:28:47 -0400
    Clément> Subject: [PATCH] Add a way to disable substitution of command keys in help
    Clément>  strings

    Clément> * src/keyboard.c (show_help_substitute_command_keys): New function
    Clément> (show_help_echo, parse_menu_item): Use it
    Clément> (syms_of_keyboard): Define Qshow_help_inhibit_substitution

    Clément> * doc/lispref/text.texi (Special Properties), etc/NEWS: Document
    Clément> the effect of 'show-help-inhibit-substitution'

Full stops at the end of sentences. Also, I think I prefer Eli's name,
mainly because yours combines 'show' with 'inhibit', which I find
jarring, and because Eli's contains 'help-echo', which mirrors the
name of the affected property.

    Clément> ++++
    Clément> +** Adding a non-nil 'show-help-inhibit-substitution' text property on
    Clément> +the first character of a help string disables conversion via
    Clément> +'substitute-command-keys'.
    Clément> +

Should this be in the 'Lisp Changes' section of NEWS? Also, first line
should be a complete sentence, so:

** New text property 'show-help-inhibit-substitution'.
Setting this on the first character of a help string disables
conversion via 'substitute-command-keys'.

    Clément> +/* Substitute key descriptions and quotes in HELP, unless its first
    Clément> +   character has a non-nil show-help-inhibit-substitution property. */

Two spaces after full stop.

    Clément> +
    Clément> +static Lisp_Object
    Clément> +show_help_substitute_command_keys (Lisp_Object help)
    Clément> +{
    Clément> +  if (STRINGP (help) &&
    Clément> +      SCHARS (help) > 0 &&
    Clément> +      !NILP (Fget_text_property (make_fixnum(0),
    Clément> +                                 Qshow_help_inhibit_substitution,
    Clément> +                                 help)))

Break before operators, not after.

Robert

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

From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Thu, 17 Oct 2019 08:01:58 -0400

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

On 2019-10-17 05:44, Robert Pluim wrote:
>     Clément> * doc/lispref/text.texi (Special Properties), etc/NEWS: Document
>     Clément> the effect of 'show-help-inhibit-substitution'
> 
> Full stops at the end of sentences. Also, I think I prefer Eli's name,
> mainly because yours combines 'show' with 'inhibit', which I find
> jarring, and because Eli's contains 'help-echo', which mirrors the
> name of the affected property.

The property affects more than help-echo strings: it affects anything that is fed to show-help-function.  That's why I changed the name; WDYT?

I've applied all the other comments; thanks a lot!

Clément.

[0001-Add-a-way-to-disable-substitution-of-command-keys-in.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Thu, 17 Oct 2019 16:13:58 +0300

> From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
> Date: Thu, 17 Oct 2019 08:01:58 -0400
> Cc: 37785 <at> debbugs.gnu.org
> 
> > Full stops at the end of sentences. Also, I think I prefer Eli's name,
> > mainly because yours combines 'show' with 'inhibit', which I find
> > jarring, and because Eli's contains 'help-echo', which mirrors the
> > name of the affected property.
> 
> The property affects more than help-echo strings: it affects anything that is fed to show-help-function.  That's why I changed the name; WDYT?

But show-help-function is for showing help-echo, is it not?

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

From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Thu, 17 Oct 2019 09:47:52 -0400

On 2019-10-17 09:13, Eli Zaretskii wrote:
>> From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
>> Date: Thu, 17 Oct 2019 08:01:58 -0400
>> Cc: 37785 <at> debbugs.gnu.org
>>
>>> Full stops at the end of sentences. Also, I think I prefer Eli's name,
>>> mainly because yours combines 'show' with 'inhibit', which I find
>>> jarring, and because Eli's contains 'help-echo', which mirrors the
>>> name of the affected property.
>>
>> The property affects more than help-echo strings: it affects anything that is fed to show-help-function.  That's why I changed the name; WDYT?
> 
> But show-help-function is for showing help-echo, is it not?

That's true, and my explanation wasn't very good.  I'm working off of this commit:

commit 5f5fe275ec54194a9293690ffee3d425026ac14b
Author: Paul Eggert <eggert <at> cs.ucla.edu>
Date:   Sun Aug 2 14:55:15 2015 -0700

    Treat help strings like other doc strings
    
    * doc/lispref/text.texi (Special Properties), etc/NEWS: Document this.
    * lisp/epa.el (epa--select-keys): Remove no-longer-needed calls to
    substitute-command-keys.
    * src/keyboard.c (show_help_echo, parse_menu_item): Call
    substitute-command-keys on the help string before displaying it.

It adds Fsubstitute_command_keys in two places: show_help_echo and parse_menu_item.  The patch I sent makes both of these calls conditional, so calling the variable help-echo-inhibit-substitutions isn't right.

That commit added this NEWS entry:

+** show-help-function's arg is converted via substitute-command-keys
+before being passed to the function.  Help strings, help-echo
+properties, etc. can therefore contain command key escapes and
+quotation marks.

But in fact show-help-function's arg being converted only affect help-echo properties; it's the change to parse_menu_item that does the rest.

I can either:
* Change the name to something like help-string-inhibit-substitutions.
* Restrict the patch to the argument of show-help-function, and rename the variable to help-echo-inhibit-substitutions.

Let me know,
Clément.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Thu, 17 Oct 2019 17:06:49 +0300

> Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
> From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
> Date: Thu, 17 Oct 2019 09:47:52 -0400
> 
> > But show-help-function is for showing help-echo, is it not?
> 
> That's true, and my explanation wasn't very good.  I'm working off of this commit:
> 
> commit 5f5fe275ec54194a9293690ffee3d425026ac14b
> Author: Paul Eggert <eggert <at> cs.ucla.edu>
> Date:   Sun Aug 2 14:55:15 2015 -0700
> 
>     Treat help strings like other doc strings
>     
>     * doc/lispref/text.texi (Special Properties), etc/NEWS: Document this.
>     * lisp/epa.el (epa--select-keys): Remove no-longer-needed calls to
>     substitute-command-keys.
>     * src/keyboard.c (show_help_echo, parse_menu_item): Call
>     substitute-command-keys on the help string before displaying it.
> 
> It adds Fsubstitute_command_keys in two places: show_help_echo and parse_menu_item.  The patch I sent makes both of these calls conditional, so calling the variable help-echo-inhibit-substitutions isn't right.

Why isn't it right for parse_menu_item?  That function uses the :help
text, which is help-echo for menu items.

> I can either:
> * Change the name to something like help-string-inhibit-substitutions.
> * Restrict the patch to the argument of show-help-function, and rename the variable to help-echo-inhibit-substitutions.

Let's first agree whether or not parse_menu_item triggers help-echo.
If you think it doesn't please elaborate as to why you think so.

Thanks.

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

From: Robert Pluim <rpluim <at> gmail.com>
To: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Thu, 17 Oct 2019 17:06:28 +0200

>>>>> On Thu, 17 Oct 2019 09:47:52 -0400, Clément Pit-Claudel <cpitclaudel <at> gmail.com> said:
    Clément> * Change the name to something like help-string-inhibit-substitutions.
    Clément> * Restrict the patch to the argument of show-help-function, and rename the variable to help-echo-inhibit-substitutions.

I think Iʼd prefer the former, for the sake of consistency.

Robert

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

From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Thu, 17 Oct 2019 11:53:45 -0400

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

On 2019-10-17 10:06, Eli Zaretskii wrote:
>> Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
>> From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
>> Date: Thu, 17 Oct 2019 09:47:52 -0400
>>
>>> But show-help-function is for showing help-echo, is it not?
>>
>> That's true, and my explanation wasn't very good.  I'm working off of this commit:
>>
>> commit 5f5fe275ec54194a9293690ffee3d425026ac14b
>> Author: Paul Eggert <eggert <at> cs.ucla.edu>
>> Date:   Sun Aug 2 14:55:15 2015 -0700
>>
>>     Treat help strings like other doc strings
>>     
>>     * doc/lispref/text.texi (Special Properties), etc/NEWS: Document this.
>>     * lisp/epa.el (epa--select-keys): Remove no-longer-needed calls to
>>     substitute-command-keys.
>>     * src/keyboard.c (show_help_echo, parse_menu_item): Call
>>     substitute-command-keys on the help string before displaying it.
>>
>> It adds Fsubstitute_command_keys in two places: show_help_echo and parse_menu_item.  The patch I sent makes both of these calls conditional, so calling the variable help-echo-inhibit-substitutions isn't right.
> 
> Why isn't it right for parse_menu_item?  That function uses the :help
> text, which is help-echo for menu items.

Ah, OK, then I just misunderstood :)
I've attached an updated patch.

[0001-Add-a-way-to-disable-substitution-of-command-keys-in.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Thu, 17 Oct 2019 20:18:58 +0300

> Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
> From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
> Date: Thu, 17 Oct 2019 11:53:45 -0400
> 
> I've attached an updated patch.

Thanks, I have a few minor comments.

> * src/keyboard.c (help_echo_substitute_command_keys): New function

Missing period at end of sentence.

> diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
> index d7b04d2934..22a007592b 100644
> --- a/doc/lispref/text.texi
> +++ b/doc/lispref/text.texi
> @@ -3736,9 +3736,11 @@ Special Properties
>  @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
>  Bar}).  The specified function is called with one argument, the help
>  string to display, which is passed through
> -@code{substitute-command-keys} before being given to the function; see
> -@ref{Keys in Documentation}.  Tooltip mode (@pxref{Tooltips,,, emacs,
> -The GNU Emacs Manual}) provides an example.
> +@code{substitute-command-keys} before being given to the function,
> +unless the help string has a non-nil
                                ^^^^^^
In the Info manuals, we give "nil" the @code markup: non-@code{nil}.

Please also add here an index entry, so that readers could find this
information quickly.  Suggestion:

 @cindex help-echo text, avoid command-key substitution

Also, please add the description of this face to the list in "Special
Properties".

> +** New text property 'help-echo-inhibit-substitution'.
> +Setting this on the first character of a help string disables
> +conversion via 'substitute-command-keys'.
   ^^^^^^^^^^
I'd use "conversions" here, in plural.

> +  return Fsubstitute_command_keys(help);
                                    ^
Our convention is to leave one blank between a function's name and the
opening parenthesis.

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

From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Sat, 19 Oct 2019 16:35:30 -0400

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

On 2019-10-17 13:18, Eli Zaretskii wrote:
>> Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
>> From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
>> Date: Thu, 17 Oct 2019 11:53:45 -0400
>>
>> I've attached an updated patch.
> 
> Thanks, I have a few minor comments.

Wonderful, thanks a lot!  Here's an updated patch.

[0001-Add-a-way-to-disable-substitution-of-command-keys-in.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Sun, 20 Oct 2019 15:08:09 +0300

> Cc: rpluim <at> gmail.com, 37785 <at> debbugs.gnu.org
> From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
> Date: Sat, 19 Oct 2019 16:35:30 -0400
> 
> Wonderful, thanks a lot!  Here's an updated patch.

LGTM.  Please feel free to install, after fixing this one nit:

> +      && !NILP (Fget_text_property (make_fixnum(0),
                                                  ^
Blank missing before the opening parenthesis.

Thanks.

Message #40 received at 37785-done <at> debbugs.gnu.org (full text, mbox):

From: Clément Pit-Claudel <cpitclaudel <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 37785-done <at> debbugs.gnu.org, rpluim <at> gmail.com
Subject: Re: bug#37785: [PATCH] Add a way to disable substitution of command
 keys in help strings
Date: Sun, 20 Oct 2019 21:53:49 -0400

On 2019-10-20 08:08, Eli Zaretskii wrote:
> LGTM.  Please feel free to install, after fixing this one nit:

Done! Thanks again for your help :)

Previous Next

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