From 209dfa11a4218311984a9e7a695fab75364f5623 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 20 Sep 2020 17:16:38 +0300 Subject: [PATCH] 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 9716d87504e..508debd13c8 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 2eff558243f..14d52008ac1 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 cdd1588cd12..0c2cc7686aa 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") -- 2.39.5