[Emacs-diffs] master 435eb82: Add a way to disable substitution of command keys in help strings

[Clément Pit--Claudel]

branch: master
commit 435eb82e7b7e8926a3675bac74713e7c6081f7db
Author: Clément Pit-Claudel <address@hidden>
Commit: Clément Pit-Claudel <address@hidden>

    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 | 15 +++++++++++++--
 etc/NEWS              |  5 +++++
 src/keyboard.c        | 23 ++++++++++++++++++++---
 3 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 1938c4c..ac444f6 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3407,7 +3407,8 @@ or shorter, higher or lower, wider or narrow, or replaced 
with an image.
 @anchor{Text help-echo}
 If text has a string as its @code{help-echo} property, then when you
 move the mouse onto that text, Emacs displays that string in the echo
-area, or in the tooltip window (@pxref{Tooltips}).
+area, or in the tooltip window (@pxref{Tooltips}), after passing it
+through @code{substitute-command-keys}.
 
 If the value of the @code{help-echo} property is a function, that
 function is called with three arguments, @var{window}, @var{object} and
@@ -3437,6 +3438,14 @@ You can alter the way help text is displayed by setting 
the variable
 
 This feature is used in the mode line and for other active text.
 
+@item help-echo-inhibit-substitution
+@cindex help-echo text, avoid command-key substitution
+@kindex help-echo-inhibit-substitution @r{(text property)}
+If the first character of a @code{help-echo} string has a
+non-@code{nil} @code{help-echo-inhibit-substitution} property, then it
+is displayed as-is by @code{show-help-function}, without being passed
+through @code{substitute-command-keys}.
+
 @item keymap
 @cindex keymap of character
 @kindex keymap @r{(text property)}
@@ -3744,7 +3753,9 @@ a function called to display help strings.  These may be
 Items}, @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
+@code{substitute-command-keys} before being given to the function,
+unless the help string has a non-@code{nil}
+@code{help-echo-inhibit-substitution} property on its first character; see
 @ref{Keys in Documentation}.  See the code of Tooltip mode
 (@pxref{Tooltips,,, emacs, The GNU Emacs Manual}) for an example of a
 mode that uses @code{show-help-function}.
diff --git a/etc/NEWS b/etc/NEWS
index d0e369e..cf6b066 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3036,6 +3036,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
+conversions 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 db583ec..56ab790 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);
     }
 }
@@ -7670,7 +7686,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);
        }
@@ -7734,7 +7750,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))
@@ -11455,6 +11471,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);