From 435eb82e7b7e8926a3675bac74713e7c6081f7db Mon Sep 17 00:00:00 2001 From: =?utf8?q?Cl=C3=A9ment=20Pit-Claudel?= 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 | 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 1938c4c50ba..ac444f6afeb 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 d0e369e0f72..cf6b066b442 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 db583ec530e..56ab79068ad 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); -- 2.39.2