From 79e58003aa91ea1273f2588c3891a6ad9c5d282e Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Tue, 3 May 2016 19:14:31 +0300
Subject: Improve documentation of Dired's 'A' and 'Q' commands

* lisp/dired-aux.el (dired-do-find-regexp)
(dired-do-find-regexp-and-replace): Mention
'grep-find-ignored-files' and 'vc-directory-exclusion-list', and
also the fact that REGEXP should be palatable by Grep.  (Bug#23426)
* lisp/dired.el: Update the corresponding autoload forms.

* doc/emacs/dired.texi (Operating on Files): Mention
'grep-find-ignored-files' and 'vc-directory-exclusion-list'.
(Bug#23429)
---
 doc/emacs/dired.texi | 14 ++++++++++++++
 lisp/dired-aux.el    | 13 +++++++++++--
 lisp/dired.el        | 11 ++++++++++-
 3 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index 089b1091618..aa717dfad54 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -795,6 +795,14 @@ This command is a variant of @code{xref-find-references}
 where you can navigate between matches and display them as needed
 using the commands described in @ref{Xref Commands}.
 
+@vindex grep-find-ignored-files @r{(Dired)}
+@vindex vc-directory-exclusion-list @r{(Dired)}
+If any of the marked files are directories, then this command searches
+all of the files in those directories, and any of their
+subdirectories, recursively, except files whose names match
+@code{grep-find-ignored-files} and subdirectories whose names match
+@code{vc-directory-exclusion-list}.
+
 @kindex Q @r{(Dired)}
 @findex dired-do-find-regexp-and-replace
 @cindex search and replace in multiple files (in Dired)
@@ -809,6 +817,12 @@ 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}.
+
+Like with @code{dired-do-find-regexp}, if any of the marked files are
+directories, this command performs replacements in all of the files in
+those directories, and in any of their subdirectories, recursively,
+except for files whose names match @code{grep-find-ignored-files} and
+subdirectories whose names match @code{vc-directory-exclusion-list}.
 @end table
 
 @node Shell Commands in Dired
diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index cef4a96b763..5ee3c118cb1 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -2720,7 +2720,12 @@ with the command \\[tags-loop-continue]."
 ;;;###autoload
 (defun dired-do-find-regexp (regexp)
   "Find all matches for REGEXP in all marked files.
-For any marked directory, all of its files are searched recursively."
+For any marked directory, all of its files are searched recursively.
+However, files matching `grep-find-ignored-files' and subdirectories
+matching `vc-directory-exclusion-list' are skipped in the marked
+directories.
+
+REGEXP should use constructs supported by your local `grep' command."
   (interactive "sSearch marked files (regexp): ")
   (require 'grep)
   (defvar grep-find-ignored-files)
@@ -2743,7 +2748,11 @@ For any marked directory, all of its files are searched recursively."
 (defun dired-do-find-regexp-and-replace (from to)
   "Replace matches of FROM with TO, in all marked files.
 For any marked directory, matches in all of its files are replaced,
-recursively."
+recursively.  However, files matching `grep-find-ignored-files'
+and subdirectories matching `vc-directory-exclusion-list' are skipped
+in the marked directories.
+
+REGEXP should use constructs supported by your local `grep' command."
   (interactive
    (let ((common
           (query-replace-read-args
diff --git a/lisp/dired.el b/lisp/dired.el
index 41525a45595..2cc3c88dbc0 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -4425,13 +4425,22 @@ with the command \\[tags-loop-continue].
 (autoload 'dired-do-find-regexp "dired-aux" "\
 Find all matches for REGEXP in all marked files.
 For any marked directory, all of its files are searched recursively.
+However, files matching `grep-find-ignored-files' and subdirectories
+matching `vc-directory-exclusion-list' are skipped in the marked
+directories.
+
+REGEXP should use constructs supported by your local `grep' command.
 
 \(fn REGEXP)" t nil)
 
 (autoload 'dired-do-find-regexp-and-replace "dired-aux" "\
 Replace matches of FROM with TO, in all marked files.
 For any marked directory, matches in all of its files are replaced,
-recursively.
+recursively.  However, files matching `grep-find-ignored-files'
+and subdirectories matching `vc-directory-exclusion-list' are skipped
+in the marked directories.
+
+REGEXP should use constructs supported by your local `grep' command.
 
 \(fn FROM TO)" t nil)
 
-- 
cgit v1.2.3