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'.

diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 9716d87504e4c906a67d3f9d2e6f0659e185f130..508debd13c81094b2edf1cf00ae3ad68c73e0f82 100644 (file)
--- 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 2eff558243f3be9b202f76ee70f16eaf9a3a889f..14d52008ac1564180edecd8d05a0b780bf7dd703 100644 (file)
--- 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 cdd1588cd128cd95c97d5fe96eeec7937d06c7ea..0c2cc7686aa22763707cbbdd32e41f98b612b72b 100644 (file)
--- 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")