; Improve documentation of lazy-highlight in search and replace commands

* lisp/isearch.el (lazy-highlight, lazy-highlight-initial-delay)
(lazy-highlight-buffer, isearch-lazy-highlight, isearch-forward):
* lisp/replace.el (query-replace, query-replace-lazy-highlight)
(query-replace, query-replace-regexp): Doc fixes.

* doc/emacs/search.texi (Search Customizations): Document
'lazy-highlight-buffer' and 'lazy-highlight-buffer-max-at-a-time'.
Use @vtable to avoid the need of indexing each variable
separately.

3 files changed, 48 insertions, 17 deletions

diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 2bd35380780..5f7aa1f1ef5 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -2202,24 +2202,20 @@ variable @code{isearch-lazy-highlight} to @code{nil} disables this
 highlighting.  Here are some other variables that customize the lazy
 highlighting:
 
-@table @code
+@vtable @code
 @item lazy-highlight-initial-delay
-@vindex lazy-highlight-initial-delay
 Time in seconds to wait before highlighting visible matches.
 Applies only if the search string is less than
 @code{lazy-highlight-no-delay-length} characters long.
 
 @item lazy-highlight-no-delay-length
-@vindex lazy-highlight-no-delay-length
 For search strings at least as long as the value of this variable,
 lazy highlighting of matches starts immediately.
 
 @item lazy-highlight-interval
-@vindex lazy-highlight-interval
 Time in seconds between highlighting successive matches.
 
 @item lazy-highlight-max-at-a-time
-@vindex lazy-highlight-max-at-a-time
 The maximum number of matches to highlight before checking for input.
 A large number can take some time to highlight, so if you want to
 continue searching and type @kbd{C-s} or @kbd{C-r} during that time,
@@ -2227,17 +2223,28 @@ Emacs will not respond until it finishes highlighting all those
 matches.  Thus, smaller values make Emacs more responsive.
 
 @item isearch-lazy-count
-@vindex isearch-lazy-count
 Show the current match number and the total number of matches in the
 search prompt.
 
 @item lazy-count-prefix-format
 @itemx lazy-count-suffix-format
-@vindex lazy-count-prefix-format
-@vindex lazy-count-suffix-format
 These two variables determine the format of showing the current and
 the total number of matches for @code{isearch-lazy-count}.
-@end table
+
+@item lazy-highlight-buffer
+If non-@code{nil}, lazy highlighting highlights the matches in the
+entire buffer, not only those visible on display of the current window
+(so, for example, they will also become visible in other windows showing
+the same buffer).
+
+@item lazy-highlight-buffer-max-at-a-time
+Like @code{lazy-highlight-max-at-a-time}, but used for highlighting
+matches not currently visible in the window when
+@code{lazy-highlight-buffer} is non-@code{nil}.  It defaults to 200; set
+to @code{nil} to highlight all the matches in a buffer without checking
+for input.  @strong{Warning:} this could make Emacs not responsive when
+searching large buffers.
+@end vtable
 
 @vindex search-nonincremental-instead
   Normally, entering @key{RET} within incremental search when the
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 785d324cac3..92bd9af6643 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -347,6 +347,9 @@ you can define more of these faces using the same numbering scheme."
 When non-nil, all text currently visible on the screen
 matching the current search string is highlighted lazily
 (see `lazy-highlight-initial-delay' and `lazy-highlight-interval').
+However, if `lazy-highlight-buffer' is non-nil, all text in the
+entire buffer matching the search string is highlighted lazily.
+The highlighting uses the `lazy-highlight' face.
 
 When multiple windows display the current buffer, the
 highlighting is displayed only on the selected window, unless
@@ -385,8 +388,8 @@ If this is nil, extra highlighting can be \"manually\" removed with
 
 (defcustom lazy-highlight-initial-delay 0.25
   "Seconds to wait before beginning to lazily highlight all matches.
-This setting only has effect when the search string is less than
-`lazy-highlight-no-delay-length' characters long."
+This setting only has effect when the search string is shorter than
+`lazy-highlight-no-delay-length' characters."
   :type 'number
   :group 'lazy-highlight)
 
@@ -428,7 +431,9 @@ When non-nil, all text in the buffer matching the current search
 string is highlighted lazily (see `lazy-highlight-initial-delay',
 `lazy-highlight-interval' and `lazy-highlight-buffer-max-at-a-time').
 This is useful when `lazy-highlight-cleanup' is customized to nil
-and doesn't remove full-buffer highlighting after a search."
+and doesn't remove full-buffer highlighting after a search.
+If this is nil (the default), only the text currently visible in
+the window is highlighted, subject to `isearch-lazy-highlight'."
   :type 'boolean
   :group 'lazy-highlight
   :version "27.1")
@@ -443,7 +448,9 @@ and doesn't remove full-buffer highlighting after a search."
     (((class color) (min-colors 8))
      (:background "turquoise3" :distant-foreground "white"))
     (t (:underline t)))
-  "Face for lazy highlighting of matches other than the current one."
+  "Face for lazy highlighting of matches other than the current one.
+Used in Isearch when `isearch-lazy-highlight' is non-nil,
+and in `query-replace' when `query-replace-lazy-highlight' is non-nil."
   :group 'lazy-highlight
   :group 'basic-faces)
 
@@ -1006,6 +1013,9 @@ Each element is an `isearch--state' struct where the slots are
 With a prefix argument, do an incremental regular expression search instead.
 \\<isearch-mode-map>
 As you type characters, they add to the search string and are found.
+Current match for the search string is highlighted using the `isearch' face,
+and if `isearch-lazy-highlight' is non-nil, the other matches are
+highlighted using the `lazy-highlight' face.
 The following non-printing keys are bound in `isearch-mode-map'.
 
 Type \\[isearch-delete-char] to cancel last input item from end of search string.
diff --git a/lisp/replace.el b/lisp/replace.el
index 933249d824c..48e158de531 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -133,9 +133,11 @@ you can define more of these faces using the same numbering scheme."
 
 (defcustom query-replace-lazy-highlight t
   "Controls the lazy-highlighting during query replacements.
-When non-nil, all text in the buffer matching the current match
-is highlighted lazily using isearch lazy highlighting (see
-`lazy-highlight-initial-delay' and `lazy-highlight-interval')."
+When non-nil, all text matching the current match that is
+currently visible in the window is highlighted lazily using
+isearch lazy highlighting (see `lazy-highlight-initial-delay'
+and `lazy-highlight-interval').  Uses the `lazy-highlight' face
+to highlight matching text."
   :type 'boolean
   :group 'lazy-highlight
   :group 'matching
@@ -143,7 +145,9 @@ is highlighted lazily using isearch lazy highlighting (see
 
 (defface query-replace
   '((t (:inherit isearch)))
-  "Face for highlighting query replacement matches."
+  "Face for highlighting query replacement matches.
+Used in `query-replace' and `query-replace-regexp'
+when `query-replace-highlight' is non-nil"
   :group 'matching
   :version "22.1")
 
@@ -427,6 +431,11 @@ 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
 accessible portion.
 
+The current match of FROM-STRING is highlighted using
+the `query-replace' face.  Other matches of FROM-STRING are highlighted
+using the `lazy-highlight' face if `query-replace-lazy-highlight' is
+non-nil.
+
 In interactive use, the prefix arg (non-nil DELIMITED in
 non-interactive use), means replace only matches surrounded by
 word boundaries.  A negative prefix arg means replace backward.
@@ -508,6 +517,11 @@ accessible portion.
 When invoked interactively, matching a newline with `\\n' will not work;
 use \\`C-q C-j' instead.  To match a tab character (`\\t'), just press \\`TAB'.
 
+The current match of REGEXP is highlighted using
+the `query-replace' face.  Other matches of REGEXP are highlighted
+using the `lazy-highlight' face if `query-replace-lazy-highlight' is
+non-nil.
+
 Use \\<minibuffer-local-map>\\[next-history-element] \
 to pull the last incremental search regexp to the minibuffer
 that reads REGEXP, or invoke replacements from