Yet another doc improvement for search commands

* doc/emacs/search.texi (Word Search, Symbol Search)
(Regexp Search): Document commands that don't support lax
whitespace matching or character folding.
(Nonincremental Search): Mention the search commands that can be
invoked from the menu bar.

* lisp/isearch.el (isearch-define-mode-toggle-word)
(isearch-define-mode-toggle-symbol)
(isearch-define-mode-toggle-character-fold): Note in the doc
string that turning these on exits the regexp mode.
(isearch-forward-regexp, isearch-forward-word)
(isearch-forward-symbol, isearch-backward-regexp)
(word-search-backward, word-search-forward)
(word-search-backward-lax, word-search-forward-lax): State in the
doc string which commands don't support character folding and/or
lax-whitespace matching.

2 files changed, 37 insertions, 12 deletions

diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 88ec68c43ec..81b4f87462e 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -548,6 +548,9 @@ command for nonincremental search, if the string you specify is empty.
 @key{RET}} does likewise, invoking the nonincremental
 backward-searching command.
 
+  Nonincremental search can also be invoked form the menu bar's
+@samp{Edit->Search} menu.
+
 @findex search-forward
 @findex search-backward
   You can also use two simpler commands, @kbd{M-x search-forward} and
@@ -607,6 +610,9 @@ so that the matching can proceed incrementally as you type.  This
 additional laxity does not apply to the lazy highlight
 (@pxref{Incremental Search}), which always matches whole words.
 
+  The word search commands don't perform character folding and cannot
+support lax whitespace matching (@pxref{Lax Search}).
+
 @kindex M-s M-w
 @findex eww-search-word
 @vindex eww-search-prefix
@@ -663,6 +669,9 @@ search.  In nonincremental symbol searches, the beginning and end of
 the search string are required to match the beginning and end of a
 symbol, respectively.
 
+  The symbol search commands don't perform character folding and
+cannot support lax whitespace matching (@pxref{Lax Search}).
+
 @node Regexp Search
 @section Regular Expression Search
 @cindex regexp search
@@ -709,13 +718,19 @@ regexps saved in the search ring is determined by the value of
 @code{regexp-search-ring-max}, 16 by default.
 
   Unlike ordinary incremental search, incremental regexp search
-do not use lax space matching by default.  To toggle this feature
+does not use lax space matching by default.  To toggle this feature
 use @kbd{M-s @key{SPC}} (@code{isearch-toggle-lax-whitespace}).
 Then any @key{SPC} typed in incremental regexp search will match
 any sequence of one or more whitespace characters.  The variable
 @code{search-whitespace-regexp} specifies the regexp for the lax
 space matching.  @xref{Special Isearch}.
 
+  Also unlike ordinary incremental search, incremental regexp search
+cannot use character folding (@pxref{Lax Search}).  (If you toggle
+character folding during incremental regexp search with @kbd{M-s '},
+the search becomes a non-regexp search and the search pattern you
+typed is interpreted as a literal string.)
+
   In some cases, adding characters to the regexp in an incremental
 regexp search can make the cursor move back and start again.  For
 example, if you have searched for @samp{foo} and you add @samp{\|bar},
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 6cbe612d72e..229121d55b1 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -774,7 +774,8 @@ as a regexp.  See the command `isearch-forward' for more information.
 In incremental searches, a space or spaces normally matches any
 whitespace defined by the variable `search-whitespace-regexp'.
 To search for a literal space and nothing else, enter C-q SPC.
-To toggle whitespace matching, use `isearch-toggle-lax-whitespace'."
+To toggle whitespace matching, use `isearch-toggle-lax-whitespace'.
+This command does not support character folding."
   (interactive "P\np")
   (isearch-mode t (null not-regexp) nil (not no-recursive-edit)))
 
@@ -783,7 +784,8 @@ To toggle whitespace matching, use `isearch-toggle-lax-whitespace'."
 With a prefix argument, do a regular string search instead.
 Like ordinary incremental search except that your input is treated
 as a sequence of words without regard to how the words are separated.
-See the command `isearch-forward' for more information."
+See the command `isearch-forward' for more information.
+This command does not support character folding or lax space matching."
   (interactive "P\np")
   (isearch-mode t nil nil (not no-recursive-edit) (null not-word)))
 
@@ -792,7 +794,8 @@ See the command `isearch-forward' for more information."
 The prefix argument is currently unused.
 Like ordinary incremental search except that your input is treated
 as a symbol surrounded by symbol boundary constructs \\_< and \\_>.
-See the command `isearch-forward' for more information."
+See the command `isearch-forward' for more information.
+This command does not support character folding or lax space matching."
   (interactive "P\np")
   (isearch-mode t nil nil (not no-recursive-edit) 'isearch-symbol-regexp))
 
@@ -807,7 +810,7 @@ See the command `isearch-forward' for more information."
   "Do incremental search backward for regular expression.
 With a prefix argument, do a regular string search instead.
 Like ordinary incremental search except that your input is treated
-as a regexp.  See the command `isearch-forward' for more information."
+as a regexp.  See the command `isearch-forward-regexp' for more information."
   (interactive "P\np")
   (isearch-mode nil (null not-regexp) nil (not no-recursive-edit)))
 
@@ -1533,9 +1536,12 @@ The command then executes BODY and updates the isearch prompt."
                                               (cdr types))))
                  (get 'search-default-regexp-mode 'custom-type)))))))
 
-(isearch-define-mode-toggle word "w" word-search-regexp)
-(isearch-define-mode-toggle symbol "_" isearch-symbol-regexp)
-(isearch-define-mode-toggle character-fold "'" character-fold-to-regexp)
+(isearch-define-mode-toggle word "w" word-search-regexp "\
+Turning on word search turns off regexp mode.")
+(isearch-define-mode-toggle symbol "_" isearch-symbol-regexp "\
+Turning on symbol search turns off regexp mode.")
+(isearch-define-mode-toggle character-fold "'" character-fold-to-regexp "\
+Turning on character-folding turns off regexp mode.")
 (put 'character-fold-to-regexp 'isearch-message-prefix "char-fold ")
 
 (isearch-define-mode-toggle regexp "r" nil nil
@@ -1618,7 +1624,8 @@ Optional fourth argument is repeat count--search for successive occurrences.
 
 Relies on the function `word-search-regexp' to convert a sequence
 of words in STRING to a regexp used to search words without regard
-to punctuation."
+to punctuation.
+This command does not support character folding or lax space matching."
   (interactive "sWord search backward: ")
   (re-search-backward (word-search-regexp string nil) bound noerror count))
 
@@ -1633,7 +1640,8 @@ Optional fourth argument is repeat count--search for successive occurrences.
 
 Relies on the function `word-search-regexp' to convert a sequence
 of words in STRING to a regexp used to search words without regard
-to punctuation."
+to punctuation.
+This command does not support character folding or lax space matching."
   (interactive "sWord search: ")
   (re-search-forward (word-search-regexp string nil) bound noerror count))
 
@@ -1652,7 +1660,8 @@ Optional fourth argument is repeat count--search for successive occurrences.
 
 Relies on the function `word-search-regexp' to convert a sequence
 of words in STRING to a regexp used to search words without regard
-to punctuation."
+to punctuation.
+This command does not support character folding or lax space matching."
   (interactive "sWord search backward: ")
   (re-search-backward (word-search-regexp string t) bound noerror count))
 
@@ -1671,7 +1680,8 @@ Optional fourth argument is repeat count--search for successive occurrences.
 
 Relies on the function `word-search-regexp' to convert a sequence
 of words in STRING to a regexp used to search words without regard
-to punctuation."
+to punctuation.
+This command does not support character folding or lax space matching."
   (interactive "sWord search: ")
   (re-search-forward (word-search-regexp string t) bound noerror count))