Update documentation for Dired search and replace

* doc/emacs/dired.texi (Operating on Files): Update descriptions
of 'A' and 'Q' now bound to 'dired-do-find-regexp' and
'dired-do-find-regexp-and-replace'.

* etc/NEWS: Mention xref-related changes in Dired.

2 files changed, 31 insertions, 11 deletions

diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index 855e6531a66..201b5554f41 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -778,27 +778,31 @@ Byte compile the specified Emacs Lisp files
 Compilation, elisp, The Emacs Lisp Reference Manual}.
 
 @kindex A @r{(Dired)}
-@findex dired-do-search
+@findex dired-do-find-regexp
 @cindex search multiple files (in Dired)
 @item A @var{regexp} @key{RET}
 Search all the specified files for the regular expression @var{regexp}
-(@code{dired-do-search}).
+(@code{dired-do-find-regexp}).
 
-This command is a variant of @code{tags-search}.  The search stops at
-the first match it finds; use @kbd{M-x tags-loop-continue} to resume
-the search and find the next match.  @xref{Identifier Search}.
+This command is a variant of @code{xref-find-apropos}
+(@pxref{Identifier Search}), it displays the @file{*xref*} buffer,
+where you can navigate between matches and display them as needed
+using the commands described in @ref{Xref Commands}.
 
 @kindex Q @r{(Dired)}
-@findex dired-do-query-replace-regexp
+@findex dired-do-find-regexp-and-replace
 @cindex search and replace in multiple files (in Dired)
 @item Q @var{regexp} @key{RET} @var{to} @key{RET}
 Perform @code{query-replace-regexp} on each of the specified files,
 replacing matches for @var{regexp} with the string
-@var{to} (@code{dired-do-query-replace-regexp}).
-
-This command is a variant of @code{tags-query-replace}.  If you exit the
-query replace loop, you can use @kbd{M-x tags-loop-continue} to resume
-the scan and replace more matches.  @xref{Identifier Search}.
+@var{to} (@code{dired-do-find-regexp-and-replace}).
+
+This command is a variant of @code{xref-query-replace}.  It presents
+an @file{*xref*} buffer that lists all the matches of @var{regexp},
+and you can use the special commands in that buffer (@pxref{Xref
+Commands}).  In particular, if you exit the query replace loop, you
+can use @kbd{r} in that buffer to replace more matches.
+@xref{Identifier Search}.
 @end table
 
 @node Shell Commands in Dired
diff --git a/etc/NEWS b/etc/NEWS
index 786a3918902..a3fd1ed51a2 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1014,6 +1014,10 @@ As a result of this, the following commands are now obsolete:
 replacements yet.
 
 +++
+*** Variants of `tags-search' and `tags-query-replace' in Dired were also
+replaced by xref-style commands, see the "Dired" section below.
+
++++
 *** New variables
 
 `find-tag-marker-ring-length' is now an obsolete alias for
@@ -1153,6 +1157,18 @@ compress many marked files into a single named archive.  The
 compression command is determined from the new
 `dired-compress-files-alist' variable.
 
++++
+*** New user interface for the `A' and `Q' commands.
+These keys, now bound to `dired-do-find-regexp' and
+`dired-do-find-regexp-and-replace', work similarly to
+`xref-find-apropos' and `xref-query-replace': they present the matches
+in the `*xref*' buffer and let you move through the matches.  No need
+to use `tags-loop-continue' to resume the search or replace loop.  The
+previous commands, `dired-do-search' and
+`dired-do-query-replace-regexp', are still available, but not bound to
+keys; rebind `A' and `Q' to invoke them if you want the old behavior
+back.  We intend to obsolete the old commands in a future release.
+
 ** Tabulated List Mode
 
 +++