Add minimum instructions to 'query-replace' commands

* lisp/vc/vc-dir.el (vc-dir-query-replace-regexp):
* lisp/textmodes/reftex-global.el (reftex-query-replace-document):
* lisp/progmodes/project.el (project-query-replace-regexp):
* lisp/progmodes/etags.el (tags-query-replace):
* lisp/progmodes/ebrowse.el (ebrowse-tags-query-replace):
* lisp/isearch.el (isearch-query-replace, isearch-occur):
* lisp/emulation/viper-cmd.el (viper-query-replace):
* lisp/dired-aux.el (dired-do-query-replace-regexp)
(dired-do-find-regexp-and-replace):
* lisp/progmodes/xref.el (xref-query-replace-in-results):
* lisp/replace.el (query-replace, query-replace-regexp)
(query-replace-regexp-eval, map-query-replace-regexp): Add minimal
instructions for dealing with matches, with a link to the command
that shows the full instructions.  (Bug#55050)

10 files changed, 80 insertions, 11 deletions

diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index 57155ec26dc..f16568f9190 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -3171,9 +3171,14 @@ To continue searching for next match, use command \\[fileloop-continue]."
 ;;;###autoload
 (defun dired-do-query-replace-regexp (from to &optional delimited)
   "Do `query-replace-regexp' of FROM with TO, on all marked files.
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
+
 Third arg DELIMITED (prefix arg) means replace only word-delimited matches.
-If you exit (\\[keyboard-quit], RET or q), you can resume the query replace
-with the command \\[tags-loop-continue]."
+If you exit the query-replace loop (\\[keyboard-quit], RET or q), you can
+resume the query replace with the command \\[tags-loop-continue]."
   (interactive
    (let ((common
           (query-replace-read-args
@@ -3240,6 +3245,11 @@ REGEXP should use constructs supported by your local `grep' command."
 (defun dired-do-find-regexp-and-replace (from to)
   "Replace matches of FROM with TO, in all marked files.
 
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
+
 If no files are marked, use the file under point.
 
 For any marked directory, matches in all of its files are replaced,
diff --git a/lisp/emulation/viper-cmd.el b/lisp/emulation/viper-cmd.el
index 1f2f3ecfc38..e08d19c6115 100644
--- a/lisp/emulation/viper-cmd.el
+++ b/lisp/emulation/viper-cmd.el
@@ -4168,7 +4168,12 @@ cursor move past the beginning of line."
   "Query replace.
 If a null string is supplied as the string to be replaced,
 the query replace mode will toggle between string replace
-and regexp replace."
+and regexp replace.
+
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time."
   (interactive)
   (let (str)
     (setq str (viper-read-string-with-history
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 34e3b694754..d829744c3a4 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -2324,7 +2324,12 @@ arg means replace backward.  Note that using the prefix arg
 is possible only when `isearch-allow-scroll' is non-nil or
 `isearch-allow-prefix' is non-nil, and it doesn't always provide the
 correct matches for `query-replace', so the preferred way to run word
-replacements from Isearch is `M-s w ... M-%'."
+replacements from Isearch is `M-s w ... M-%'.
+
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time."
   (interactive
    (list current-prefix-arg))
   (barf-if-buffer-read-only)
@@ -2393,7 +2398,12 @@ the search words, ignoring punctuation.  If the last search
 command was a regular expression search, REGEXP is the regular
 expression used in that search.  If the last search command searched
 for a literal string, REGEXP is constructed by quoting all the special
-characters in that string."
+characters in that string.
+
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time."
   (interactive
    (let* ((perform-collect (consp current-prefix-arg))
           (regexp (cond
diff --git a/lisp/progmodes/ebrowse.el b/lisp/progmodes/ebrowse.el
index 047d43a922b..dacb2a5f011 100644
--- a/lisp/progmodes/ebrowse.el
+++ b/lisp/progmodes/ebrowse.el
@@ -3633,7 +3633,12 @@ If regular expression is nil, repeat last search."
 ;;;###autoload
 (defun ebrowse-tags-query-replace (from to)
   "Query replace FROM with TO in all files of a class tree.
-With prefix arg, process files of marked classes only."
+With prefix arg, process files of marked classes only.
+
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time."
   (interactive
    "sTree query replace (regexp): \nsTree query replace %s by: ")
   (setq ebrowse-tags-loop-call
diff --git a/lisp/progmodes/etags.el b/lisp/progmodes/etags.el
index 3826c1888d8..124817ffda4 100644
--- a/lisp/progmodes/etags.el
+++ b/lisp/progmodes/etags.el
@@ -1836,7 +1836,13 @@ Also see the documentation of the `tags-file-name' variable."
 Third arg DELIMITED (prefix arg) means replace only word-delimited matches.
 If you exit (\\[keyboard-quit], RET or q), you can resume the query replace
 with the command \\[fileloop-continue].
-For non-interactive use, superseded by `fileloop-initialize-replace'."
+
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
+
+For non-interactive use, this is superseded by `fileloop-initialize-replace'."
   (declare (advertised-calling-convention (from to &optional delimited) "27.1"))
   (interactive (query-replace-read-args "Tags query replace (regexp)" t t))
   (fileloop-initialize-replace
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index 1000e8c87f4..07093d61474 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -1040,6 +1040,10 @@ command \\[fileloop-continue]."
 (defun project-query-replace-regexp (from to)
   "Query-replace REGEXP in all the files of the project.
 Stops when a match is found and prompts for whether to replace it.
+At that prompt, the user must type a character saying what to do
+with the match.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
 If you exit the `query-replace', you can later continue the
 `query-replace' loop using the command \\[fileloop-continue]."
   (interactive
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 2fd5e192376..c4b439f587c 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -701,7 +701,13 @@ quit the *xref* buffer."
   "Perform interactive replacement of FROM with TO in all displayed xrefs.
 
 This command interactively replaces FROM with TO in the names of the
-references displayed in the current *xref* buffer."
+references displayed in the current *xref* buffer.
+
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
+"
   (interactive
    (let ((fr (read-regexp "Xref query-replace (regexp)" ".*")))
      (list fr
diff --git a/lisp/replace.el b/lisp/replace.el
index b1cfd7e3f42..dd1bdae4c54 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -357,7 +357,9 @@ should a regexp."
 (defun query-replace (from-string to-string &optional delimited start end backward region-noncontiguous-p)
   "Replace some occurrences of FROM-STRING with TO-STRING.
 As each match is found, the user must type a character saying
-what to do with it.  For directions, type \\[help-command] at that time.
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
 
 In Transient Mark mode, if the mark is active, operate on the contents
 of the region.  Otherwise, operate from point to the end of the buffer's
@@ -427,7 +429,9 @@ To customize possible responses, change the bindings in `query-replace-map'."
 (defun query-replace-regexp (regexp to-string &optional delimited start end backward region-noncontiguous-p)
   "Replace some things after point matching REGEXP with TO-STRING.
 As each match is found, the user must type a character saying
-what to do with it.  For directions, type \\[help-command] at that time.
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
 
 In Transient Mark mode, if the mark is active, operate on the contents
 of the region.  Otherwise, operate from point to the end of the buffer's
@@ -524,7 +528,9 @@ Interactive use of this function is deprecated in favor of the
 using `search-forward-regexp' and `replace-match' is preferred.
 
 As each match is found, the user must type a character saying
-what to do with it.  For directions, type \\[help-command] at that time.
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
 
 TO-EXPR is a Lisp expression evaluated to compute each replacement.  It may
 reference `replace-count' to get the number of replacements already made.
@@ -610,6 +616,11 @@ Use \\<minibuffer-local-map>\\[next-history-element] \
 to pull the last incremental search regexp to the minibuffer
 that reads REGEXP.
 
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
+
 A prefix argument N says to use each replacement string N times
 before rotating to the next.
 Fourth and fifth arg START and END specify the region to operate on.
diff --git a/lisp/textmodes/reftex-global.el b/lisp/textmodes/reftex-global.el
index a1aa368f609..c7e34b4b90a 100644
--- a/lisp/textmodes/reftex-global.el
+++ b/lisp/textmodes/reftex-global.el
@@ -88,6 +88,12 @@ No active TAGS table is required."
 (defun reftex-query-replace-document (&optional from to delimited)
   "Do `query-replace-regexp' of FROM with TO over the entire document.
 Third arg DELIMITED (prefix arg) means replace only word-delimited matches.
+
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
+
 If you exit (\\[keyboard-quit], RET or q), you can resume the query replace
 with the command \\[tags-loop-continue].
 No active TAGS table is required."
diff --git a/lisp/vc/vc-dir.el b/lisp/vc/vc-dir.el
index b7315cfed54..18f5b07a7f4 100644
--- a/lisp/vc/vc-dir.el
+++ b/lisp/vc/vc-dir.el
@@ -933,6 +933,12 @@ To continue searching for next match, use command \\[tags-loop-continue]."
   "Do `query-replace-regexp' of FROM with TO, on all marked files.
 If a directory is marked, then use the files displayed for that directory.
 Third arg DELIMITED (prefix arg) means replace only word-delimited matches.
+
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time.
+
 If you exit (\\[keyboard-quit], RET or q), you can resume the query replace
 with the command \\[tags-loop-continue]."
   ;; FIXME: this is almost a copy of `dired-do-query-replace-regexp'.  This