From 7be18bbfe1f51f2828e868900b83b013faeb6db6 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Wed, 7 Oct 2020 12:12:06 +0300 Subject: [PATCH] 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. --- doc/emacs/search.texi | 22 +++++++++++++++------- etc/NEWS | 5 ++++- lisp/isearch.el | 9 +++++---- 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") -- 2.39.5