Subject: bug#37785: [PATCH] Add a way to disable substitution of command keys in help strings

From: Clément Pit-Claudel <[email-masked]>
Date: Thu, 17 Oct 2019 11:53:45 -0400

On 2019-10-17 10:06, Eli Zaretskii wrote:
>> Cc: [email-masked], [email-masked]
>> From: Clément Pit-Claudel <[email-masked]>
>> 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 <[email-masked]>
>> 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.

>From e7263d6c6a6ee3d509e1da692a1767e23ff0e8eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Pit-Claudel?= <[email-masked]>
Date: Wed, 16 Oct 2019 21:28:47 -0400
Subject: [PATCH] Add a way to disable substitution of command keys in help
 strings

* src/keyboard.c (help_echo_substitute_command_keys): New function
(help_echo_echo, parse_menu_item): Use it.
(syms_of_keyboard): Define Qhelp_echo_inhibit_substitution.

* doc/lispref/text.texi (Special Properties), etc/NEWS: Document
the effect of 'help-echo-inhibit-substitution'.
---
 doc/lispref/text.texi |  8 +++++---
 etc/NEWS              |  5 +++++
 src/keyboard.c        | 23 ++++++++++++++++++++---
 3 files changed, 30 insertions(+), 6 deletions(-)

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
+@code{help-echo-inhibit-substitution} property on its first character;
+see @ref{Keys in Documentation}.  Tooltip mode (@pxref{Tooltips,,,
+emacs, The GNU Emacs Manual}) provides an example.
 @end defvar
 
 @defvar face-filters-always-match
diff --git a/etc/NEWS b/etc/NEWS
index 4b693aaaa1..f8897b7c7b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2752,6 +2752,11 @@ in other packages are now obsolete aliases of 'xor'.
 +++
 ** 'define-globalized-minor-mode' now takes BODY forms.
 
++++
+** New text property 'help-echo-inhibit-substitution'.
+Setting this on the first character of a help string disables
+conversion via 'substitute-command-keys'.
+
 
 * Changes in Emacs 27.1 on Non-Free Operating Systems
 
diff --git a/src/keyboard.c b/src/keyboard.c
index a16d13cc7b..0c0fdc3ce0 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -2019,6 +2019,22 @@ make_ctrl_char (int c)
   return c;
 }
 
+/* Substitute key descriptions and quotes in HELP, unless its first
+   character has a non-nil help-echo-inhibit-substitution property.  */
+
+static Lisp_Object
+help_echo_substitute_command_keys (Lisp_Object help)
+{
+  if (STRINGP (help)
+      && SCHARS (help) > 0
+      && !NILP (Fget_text_property (make_fixnum(0),
+                                    Qhelp_echo_inhibit_substitution,
+                                    help)))
+    return help;
+
+  return Fsubstitute_command_keys(help);
+}
+
 /* Display the help-echo property of the character after the mouse pointer.
    Either show it in the echo area, or call show-help-function to display
    it by other means (maybe in a tooltip).
@@ -2078,7 +2094,7 @@ show_help_echo (Lisp_Object help, Lisp_Object window, Lisp_Object object,
   if (STRINGP (help) || NILP (help))
     {
       if (!NILP (Vshow_help_function))
-	call1 (Vshow_help_function, Fsubstitute_command_keys (help));
+	call1 (Vshow_help_function, help_echo_substitute_command_keys (help));
       help_echo_showing_p = STRINGP (help);
     }
 }
@@ -7652,7 +7668,7 @@ parse_menu_item (Lisp_Object item, int inmenubar)
       if (CONSP (item) && STRINGP (XCAR (item)))
 	{
 	  ASET (item_properties, ITEM_PROPERTY_HELP,
-		Fsubstitute_command_keys (XCAR (item)));
+		help_echo_substitute_command_keys (XCAR (item)));
 	  start = item;
 	  item = XCDR (item);
 	}
@@ -7716,7 +7732,7 @@ parse_menu_item (Lisp_Object item, int inmenubar)
 		{
 		  Lisp_Object help = XCAR (item);
 		  if (STRINGP (help))
-		    help = Fsubstitute_command_keys (help);
+		    help = help_echo_substitute_command_keys (help);
 		  ASET (item_properties, ITEM_PROPERTY_HELP, help);
 		}
 	      else if (EQ (tem, QCfilter))
@@ -11052,6 +11068,7 @@ syms_of_keyboard (void)
   /* Tool-bars.  */
   DEFSYM (QCimage, ":image");
   DEFSYM (Qhelp_echo, "help-echo");
+  DEFSYM (Qhelp_echo_inhibit_substitution, "help-echo-inhibit-substitution");
   DEFSYM (QCrtl, ":rtl");
 
   staticpro (&item_properties);
-- 
2.17.1