Subject: 31.0.50; Allow suppressing message passed to set-transient-map
From: Stephen Berman <[email-masked]>
To: [email-masked]
Date: Thu, 24 Oct 2024 16:06:22 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

If a caller of set-transient-map passes a suitable format string, this
is displayed as a message on activating the transient map.  An example
is text-scale-adjust, which displays the message "Use +, =, -, 0, C-+,
C-=, C--, C-0 for further adjustment".  So if after typing `C-x C-+' you
immediately type `+ + + - - -', the text size increases three times and
then decreases three times.  But on each key press the message is
redisplayed, which is slighty annoying (it actually looks like it stays
in the echo area but there is a brief flicker on each key press); the
message is helpful the first time, if you're unfamiliar with the
command, but on repeated uses, it becomes visual noise.  So I propose a
user option to suppress the message, as in the attached patch.

One thing I'm not sure about is whether the call to `message' in the
local function `clearfun' of set-transient-map, which is added to
pre-command-hook, should also be conditioned on the proposed user
option; I tested both with and without such conditioning and saw no
difference, so the patch omits it.  But I admit I don't see what the
purpose of clearfun is, so maybe it should be so conditioned.

If the patch (or a corrected version of it) is accepted, I will also
update the elisp manual and NEWS accordingly.

(An alternative to the above proposal is suppressing the message after
displaying it once (or perhaps n times, though that seems extravagant).
Or allowing both alternatives (or all three) as values of the user
option.  I prefer the simpler display-or-suppress proposal, but can
implement an alternative if desired.)

In GNU Emacs 31.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
 3.24.43, cairo version 1.18.2) of 2024-10-21 built on strobelfssd
Repository revision: b3af195213518514f78ac6f66f9598e45befd1ec
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101013
System Description: Linux From Scratch r12.2-17-systemd

Configured using:
 'configure -C 'CFLAGS=-Og -g3' PKG_CONFIG_PATH=/opt/qt6/lib/pkgconfig'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG
LCMS2 LIBSYSTEMD LIBXML2 MODULES NATIVE_COMP NOTIFY INOTIFY PDUMPER PNG
RSVG SECCOMP SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER
WEBP X11 XDBE XIM XINPUT2 XPM GTK3 ZLIB
diff --git a/lisp/subr.el b/lisp/subr.el
index 4771ac1fba2..6716c975318 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -6549,6 +6549,13 @@ set-transient-map-timeout
 (defvar set-transient-map-timer nil
   "Timer for `set-transient-map-timeout'.")

+(defcustom set-transient-map-suppress-message nil
+  "Whether to suppress a message on activating the transient map.
+If non-nil, do not display a message passed to `set-transient-map'."
+  :group 'convenience
+  :type 'boolean
+  :version "31.1")
+
 (defun set-transient-map (map &optional keep-pred on-exit message timeout)
   "Set MAP as a temporary keymap taking precedence over other keymaps.
 Normally, MAP is used only once, to look up the very next key.
@@ -6561,10 +6568,11 @@ set-transient-map
 called, with no arguments, after MAP is deactivated.

 Optional arg MESSAGE, if non-nil, requests display of an informative
-message after activating the transient map.  If MESSAGE is a string,
-it specifies the format string for the message to display, and the %k
-specifier in the string is replaced with the list of keys from the
-transient map.  Any other non-nil value of MESSAGE means to use the
+message after activating the transient map, unless the user option
+`set-transient-map-suppress-message' is also non-nil.  If MESSAGE is a
+string, it specifies the format string for the message to display, and
+the %k specifier in the string is replaced with the list of keys from
+the transient map.  Any other non-nil value of MESSAGE means to use the
 message format string \"Repeat with %k\".  Upon deactivating the map,
 the displayed message will be cleared out.

@@ -6638,7 +6646,8 @@ set-transient-map
     (when timeout
       (when set-transient-map-timer (cancel-timer set-transient-map-timer))
       (setq set-transient-map-timer (run-with-idle-timer timeout nil exitfun)))
-    (when message (message "%s" message))
+    (unless set-transient-map-suppress-message
+      (when message (message "%s" message)))
     exitfun))

 ;;;; Progress reporters.