master 209dfa1: Improve documentation of a recently-added feature

[Eli Zaretskii]

branch: master
commit 209dfa11a4218311984a9e7a695fab75364f5623
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of a recently-added feature
    
    * lisp/isearch.el (search-highlight-submatches): Improve the doc
    string.
    
    * doc/emacs/search.texi (Search Customizations): Improve the
    documentation of 'search-highlight-submatches'.
    
    * etc/NEWS: Minor change of the entry for
    'search-highlight-submatches'.
---
 doc/emacs/search.texi | 16 ++++++++++------
 etc/NEWS              |  7 ++++---
 lisp/isearch.el       | 14 +++++++-------
 3 files changed, 21 insertions(+), 16 deletions(-)

diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 9716d87..508debd 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -1978,14 +1978,18 @@ using the @code{isearch} face.  This highlighting can 
be disabled by
 setting the variable @code{search-highlight} to @code{nil}.
 
 @vindex search-highlight-submatches
-  When searching for regular expressions (with @kbd{C-u C-s}, for
+  When searching for regular expressions (with @kbd{C-M-s}, for
 instance), subexpressions receive special highlighting depending on
-the @code{search-highlight-submatches} variable.  If this variable is
-zero, no special highlighting is done, but if this is larger than
-zero, subexpressions will be matched with
-@code{isearch-group-}@samp{X} faces.  For instance, when searching for
+the @code{search-highlight-submatches} variable.  If this variable's
+value is zero, no special highlighting is done, but if the value is a
+positive integer @var{n}, the strings matching the first @var{n}
+@samp{\( @dots{} \)} constructs (a.k.a.@: ``subexpressions'') in the
+regular expression will be highlighted with distinct faces, named
+@code{isearch-group-@var{n}}.  For instance, when searching for
 @samp{foo-\([0-9]+\)}, the part matched by @samp{[0-9]+} will be
-highlighted with the @code{isearch-group-1} face.
+highlighted with the @code{isearch-group-1} face if
+@code{search-highlight-submatches} is greater or equal to 1.  The
+default value of @code{search-highlight-submatches} is 5.
 
 @cindex lazy highlighting customizations
 @vindex isearch-lazy-highlight
diff --git a/etc/NEWS b/etc/NEWS
index 2eff558..14d5200 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1036,9 +1036,10 @@ window after starting).  This variable defaults to nil.
 
 +++
 *** Interactive regular expression search now uses faces for sub-groups.
-'C-u C-s foo-\([0-9]+\)' will now use the 'isearch-group-1' face on the
-part of the regexp that matches the sub-expression "[0-9]+".  This is
-controlled by the 'search-highlight-submatches' variable.
+E.g., 'C-M-s foo-\([0-9]+\)' will now use the 'isearch-group-1' face
+on the part of the regexp that matches the sub-expression "[0-9]+".
+This is controlled by the 'search-highlight-submatches' variable,
+whose default value is 5.
 
 ---
 *** New user option 'reveal-auto-hide'.
diff --git a/lisp/isearch.el b/lisp/isearch.el
index cdd1588..0c2cc76 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -270,15 +270,15 @@ are `word-search-regexp' \(`\\[isearch-toggle-word]'), 
`isearch-symbol-regexp'
   :type 'boolean)
 
 (defcustom search-highlight-submatches 5
-  "Highlight regexp subexpressions of the current regexp match.
-An integer means highlight regexp subexpressions up to the
-specified maximal number.
+  "Whether to highlight regexp subexpressions of the current regexp match.
+A positive integer N means highlight regexp subexpressions 1 to N.
 
-When 0, do not highlight regexp subexpressions.
+When 0, do not highlight regexp subexpressions.  A negative value is
+treated as zero.
 
-The faces used to do the highlights are named `isearch-group-1'
-and so on, and if you increase this variable from the default,
-you have to add more of these faces."
+The faces used to do the highlights are named `isearch-group-1',
+`isearch-group-2', and so on, and if you increase this variable from
+the default, you have to add more of these faces."
   :type 'integer
   :version "28.1")