Subject: 28.0.91; Training wheels for query-replace

From: Augusto Stoffel <[email-masked]>
Date: Sat, 26 Feb 2022 23:15:12 +0100

I've been using query-replace for years but still seem to have trouble
remembering some of the keys.  How about making the help message next to
the prompt “(? for help)” customizable, with an option to include an
extra summary line?

See patch attached (note that it also slightly changes the faces of the
prompt).

>From 80710d38d9335101108661a9685c449be2d56fde Mon Sep 17 00:00:00 2001
From: Augusto Stoffel <[email-masked]>
Date: Sat, 26 Feb 2022 23:08:26 +0100
Subject: [PATCH] Make 'perform-replace' prompt help customizable

* lisp/replace.el (perform-replace-prompt-help): New defcustom, help
string shown next to 'perform-replace' prompt.
(query-replace-map): Reorder entries so that 'substitute-command-keys'
does the right job.
(perform-replace): Use 'perform-replace-prompt-help.
---
 lisp/replace.el | 46 +++++++++++++++++++++++++++++-----------------
 1 file changed, 29 insertions(+), 17 deletions(-)

diff --git a/lisp/replace.el b/lisp/replace.el
index 06be597855..c9300a22e4 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -148,6 +148,18 @@ query-replace-lazy-highlight
   :group 'matching
   :version "22.1")
 
+(defcustom perform-replace-prompt-help "\\<query-replace-map>(\\[help] for help)"
+  "Help string to show next to the `perform-replace' prompt."
+  :type '(choice (const :tag "Just advertise help"
+                        "\\<query-replace-map>(\\[help] for help)")
+                 (const :tag "One-line summary"
+                        "\\<query-replace-map>(\\[help] for help)
+Replace \\[act] once, \\[act-and-exit] and exit, \\[automatic] all; \
+skip to \\[skip] next, \\[backup] previous; \
+\\[undo-all] undo all."))
+  :group 'matching
+  :version "29.1")
+
 (defface query-replace
   '((t (:inherit isearch)))
   "Face for highlighting query replacement matches."
@@ -2451,12 +2463,12 @@ query-replace-map
     (define-key map "\d" 'skip)
     (define-key map [delete] 'skip)
     (define-key map [backspace] 'skip)
-    (define-key map "y" 'act)
-    (define-key map "n" 'skip)
     (define-key map "Y" 'act)
+    (define-key map "y" 'act)
     (define-key map "N" 'skip)
-    (define-key map "e" 'edit-replacement)
+    (define-key map "n" 'skip)
     (define-key map "E" 'edit-replacement)
+    (define-key map "e" 'edit-replacement)
     (define-key map "," 'act-and-show)
     (define-key map "q" 'exit)
     (define-key map "\r" 'exit)
@@ -2840,20 +2852,20 @@ perform-replace
          (match-again t)
 
          (message
-          (if query-flag
-              (apply #'propertize
-                     (concat "Query replacing "
-                             (if backward "backward " "")
-                             (if delimited-flag
-                                 (or (and (symbolp delimited-flag)
-                                          (get delimited-flag
-                                               'isearch-message-prefix))
-                                     "word ") "")
-                             (if regexp-flag "regexp " "")
-                             "%s with %s: "
-                             (substitute-command-keys
-                              "(\\<query-replace-map>\\[help] for help) "))
-                     minibuffer-prompt-properties))))
+          (when query-flag
+            (concat
+             (apply #'propertize
+                    (concat "Query replacing "
+                            (if backward "backward " "")
+                            (if delimited-flag
+                                (or (and (symbolp delimited-flag)
+                                         (get delimited-flag
+                                              'isearch-message-prefix))
+                                    "word ") "")
+                            (if regexp-flag "regexp " "")
+                            "%s with %s: ")
+                    minibuffer-prompt-properties)
+             (substitute-command-keys perform-replace-prompt-help)))))
 
     ;; Unless a single contiguous chunk is selected, operate on multiple chunks.
     (when region-noncontiguous-p
-- 
2.35.1