Improve documentation of 'isearch-group-N' faces

* etc/NEWS:
* doc/emacs/search.texi (Search Customizations): Improve and
clarify the wording of the 'isearch-group-N' faces description.

* lisp/isearch.el (search-highlight-submatches): Doc fix.

3 files changed, 24 insertions, 12 deletions

diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index d25e35635e9..2169a4120be 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -1984,13 +1984,21 @@ the @code{search-highlight-submatches} variable.  If this variable's
 value is @code{nil}, no special highlighting is done, but if the value
 is non-@code{nil}, text that matches @samp{\( @dots{} \)} constructs
 (a.k.a.@: ``subexpressions'') in the regular expression will be
-highlighted with distinct faces, named @code{isearch-group-1}
-and @code{isearch-group-2}.  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.  When there are
-more matches than faces, then faces are recycled from beginning,
-so the @code{isearch-group-1} face is used for the third match again.
-You can define more faces using the same numbering scheme.
+highlighted with distinct faces.  By default, two distinct faces are
+defined, named @code{isearch-group-1} and @code{isearch-group-2}.
+With these two faces, odd-numbered subexpressions will be highlighted
+using the @code{isearch-group-1} face and even-numbered subexpressions
+will be highlighted using the @code{isearch-group-2} face.  For
+instance, when searching for @samp{foo-\([0-9]+\)\([a-z]+\)}, the part
+matched by @samp{[0-9]+} will be highlighted with the
+@code{isearch-group-1} face, and the part matched by @samp{[a-z]+}
+will be highlighted using @code{isearch-group-2}.  If you define
+additional faces using the same numbering scheme, i.e.@:
+@code{isearch-group-3}, @code{isearch-group-4}, @dots{}, then the face
+@code{isearch-group-@var{M}} will be used to highlight the @var{M}'th,
+@code{@var{N}+@var{M}}'th, @code{2@var{N}+@var{M}}'th, @dots{}
+subexpressions, where @var{N} is the total number of faces of the form
+@code{isearch-group-@var{M}}.
 
 @cindex lazy highlighting customizations
 @vindex isearch-lazy-highlight
diff --git a/etc/NEWS b/etc/NEWS
index 9d7b6e31156..63a740cf64c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1108,7 +1108,10 @@ keystrokes.
 *** Interactive regular expression search now uses faces for sub-groups.
 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]+".
-By default, there are two group faces, but you can define more.
+By default, there are two faces for sub-group highlighting, but you
+can define more faces whose names are of the form 'isearch-group-N',
+where N are successive numbers above 2.
+
 This is controlled by the 'search-highlight-submatches' user option.
 This feature is available only on terminals that have enough colors to
 distinguish between sub-expression highlighting.
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 08d4be3ca82..f39de79303d 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -272,10 +272,11 @@ are `word-search-regexp' \(`\\[isearch-toggle-word]'), `isearch-symbol-regexp'
 (defcustom search-highlight-submatches t
   "Whether to highlight regexp subexpressions of the current regexp match.
 The faces used to do the highlights are named `isearch-group-1',
-`isearch-group-2'.  When there are more matches than faces, then faces are
-recycled from beginning, so the `isearch-group-1' face is used for the
-third match again.  If you want to use more distinctive colors, you have to
-define more of these faces using the same numbering scheme."
+`isearch-group-2', etc.  (By default, only these 2 are defined.)
+When there are more matches than faces, then faces are reused from the
+beginning, in a cyclical manner, so the `isearch-group-1' face is
+isreused for the third match.  If you want to use more distinctive colors,
+you can define more of these faces using the same numbering scheme."
   :type 'boolean
   :version "28.1")