Improve and update documentation of search commands

* doc/emacs/search.texi (Lax Search): Renamed from "Search Case";
all references changed.  Move the description of lax-whitespace
here.  Add description of the new character folding features and
additional customizable options.
(Isearch Yank): Move before "Error in Search".
(Basic Isearch): Improve wording.  Add index entries.  Add short
description of how to abandon search, making this subsection a
complete introduction to search basics.
(Repeat Isearch): Add index entries.  Describe additional
customizable options.  Describe mouse clicks.
(Isearch Yank): Add index entries.  Describe mouse-2 click in echo
area.  Describe more customizable options.
(Error in Isearch): Add index entries.
(Special Isearch): Move actual description of some isearch
commands to other sections, leaving here just the summary of the
commands.  Add command that toggles character folding.  Describe
commands, like "C-h C-h", that were previously omitted for some
reason.
(Not Exiting Isearch): Describe search-exit-option.  Add index
entries.
(Word Search): Describe eww-search-word and eww-search-prefix.
(Symbol Search): Add index entries.
(Regexp Search): Describe regexp-search-ring-max.
(Replacement and Lax Matches): Renamed from "Replacement and
Case"; all references changed.  Describe lax-whitespace matching
in replace commands and related options.  Describe character
folding in replace commands and related options.
(Query Replace): Describe query-replace-from-to-separator and the
new history features.  Add index entries for highlighted text.
Describe query-replace-skip-read-only.  Describe more keys
accepted by query-replace.
(Other Repeating Search): More index entries for Occur.  Describe
list-matching-lines-default-context-lines.
(Search Customizations): New section, documents customizable
options that were not documented until now.
* doc/emacs/glossary.texi (Glossary): Add "Case Folding" and
"Character Folding".

* etc/NEWS: Move search- and replace-related entries to a single
parent section.

* lisp/replace.el (query-replace-show-replacement): Doc fix.
* lisp/isearch.el (search-nonincremental-instead)
(isearch-hide-immediately): Doc fixes.

doc/emacs/abbrevs.texi

@@ -407,7 +407,7 @@ you are expanding.
 in this search; if it is @code{nil}, the word and the expansion must
 match in case.  If the value is @code{case-fold-search} (the default),
 then the variable @code{case-fold-search} controls whether to ignore
-case while searching for expansions (@pxref{Search Case}).
+case while searching for expansions (@pxref{Lax Search}).
 
 @vindex dabbrev-case-replace
   Normally, dynamic abbrev expansion preserves the case pattern
@@ -421,7 +421,7 @@ the dynamic abbrev's case pattern is preserved in most cases; if it is
 @code{nil}, the expansion is always copied verbatim.  If the value is
 @code{case-replace} (the default), then the variable
 @code{case-replace} controls whether to copy the expansion verbatim
-(@pxref{Replacement and Case}).
+(@pxref{Replacement and Lax Matches}).
 
   However, if the expansion contains a complex mixed case pattern, and
 the dynamic abbrev matches this pattern as far as it goes, then the

doc/emacs/emacs.texi

@@ -392,18 +392,20 @@ Searching and Replacement
 * Regexps::                Syntax of regular expressions.
 * Regexp Backslash::       Regular expression constructs starting with `\'.
 * Regexp Example::         A complex regular expression explained.
-* Search Case::            To ignore case while searching, or not.
+* Lax Search::                Search ignores some distinctions between
+                                similar characters, like letter-case.
 * Replace::                Search, and replace some or all matches.
 * Other Repeating Search:: Operating on all matches for some regexp.
+* Search Customizations::  Various search customizations.
 
 Incremental Search
 
 * Basic Isearch::        Basic incremental search commands.
 * Repeat Isearch::       Searching for the same string again.
-* Error in Isearch::     When your string is not found.
-* Special Isearch::      Special input in incremental search.
 * Isearch Yank::         Commands that grab text into the search string
                            or else edit the search string.
+* Error in Isearch::     When your string is not found.
+* Special Isearch::      Special input in incremental search.
 * Not Exiting Isearch::  Prefix argument and scrolling commands.
 * Isearch Minibuffer::   Incremental search of the minibuffer history.
 
@@ -411,7 +413,8 @@ Replacement Commands
 
 * Unconditional Replace::  Replacing all matches for a string.
 * Regexp Replace::         Replacing all matches for a regexp.
-* Replacement and Case::   How replacements preserve case of letters.
+* Replacement and Lax Matches::
+                           Lax searching for text to replace.
 * Query Replace::          How to use querying.
 
 Commands for Fixing Typos

doc/emacs/glossary.texi

@@ -175,11 +175,22 @@ corresponding Control character.  @xref{User Input,C-M-}.
 Case conversion means changing text from upper case to lower case or
 vice versa.  @xref{Case}.
 
+@item Case Folding
+Case folding means ignoring the differences between case variants of
+the same letter: upper-case, lower-case, and title-case.  Emacs
+performs case folding by default in text search.  @xref{Lax Search}.
+
 @item Character
 Characters form the contents of an Emacs buffer.  Also, key sequences
 (q.v.@:) are usually made up of characters (though they may include
 other input events as well).  @xref{User Input}.
 
+@item Character Folding
+Character folding means ignoring differences between similarly looking
+characters, such as between @code{a}, and @code{@:a} and @code{@'a}.
+Emacs performs character folding by default in text search.  @xref{Lax
+Search}.
+
 @item Character Set
 Emacs supports a number of character sets, each of which represents a
 particular alphabet or script.  @xref{International}.

doc/emacs/maintaining.texi

@@ -2285,7 +2285,7 @@ input.  @xref{Query Replace}, for more information on query replace.
   You can control the case-sensitivity of tags search commands by
 customizing the value of the variable @code{tags-case-fold-search}.  The
 default is to use the same setting as the value of
-@code{case-fold-search} (@pxref{Search Case}).
+@code{case-fold-search} (@pxref{Lax Search}).
 
   It is possible to get through all the files in the tags table with a
 single invocation of @kbd{M-x tags-query-replace}.  But often it is

doc/emacs/mini.texi

@@ -642,8 +642,8 @@ expressions.  A numeric prefix argument @var{n} means to fetch the
 @var{n}th matching entry.  These commands are unusual, in that they
 use the minibuffer to read the regular expression argument, even
 though they are invoked from the minibuffer.  An upper-case letter in
-the regular expression makes the search case-sensitive (@pxref{Search
-Case}).
+the regular expression makes the search case-sensitive (@pxref{Lax
+Search}).
 
   You can also search through the history using an incremental search.
 @xref{Isearch Minibuffer}.

etc/NEWS

@@ -135,25 +135,6 @@ frames.
 Works for functions, variables, faces, etc.  It is bound to `C-h o' by
 default.
 
-** New user option `search-default-regexp-mode'
-specifies the default mode for I-search.
-
-** `isearch' and `query-replace' now perform character folding in matches.
-This is analogous to case folding, but instead of disregarding case
-variants, it disregards wider classes of distinctions between similar
-characters.  (Case folding is a special case of character folding.)
-This means many characters in the search string will match entire
-groups of characters instead of just themselves.
-
-For instance, the " will match all variants of double quotes (like “
-and ”), and the letter a will match all of its accented cousins, even
-those composed of multiple characters, as well as many other symbols
-like ℀, ℁, ⒜, and ⓐ.
-
-** New function `character-fold-to-regexp' can be used
-by searching commands to produce a regexp matching anything that
-character-folds into STRING.
-
 ** New command `checkdoc-package-keywords' checks if the
 current package keywords are recognized.  Set the new option
 `checkdoc-package-keywords-flag' to non-nil to make
@@ -175,10 +156,6 @@ the `network-security-level' variable.
 
 ** C-h l now also lists the commands that were run.
 
----
-** The new M-s M-w key binding uses eww to search the web for the
-text in the region.
-
 ** M-x suggests shorthands and ignores obsolete commands for completion.
 ** x-select-enable-clipboard is renamed select-enable-clipboard.
 x-select-enable-primary and renamed select-enable-primary.
@@ -532,6 +509,36 @@ element.  The new commands bound to <up> and <down> in the minibuffer:
 
 ** Search and Replace
 
++++
+*** New user option `search-default-regexp-mode'
+specifies the default mode for I-search.
+
++++
+*** `isearch' and `query-replace' can now perform character folding in matches.
+Isearch does that by default, while `query-replace' will do that if
+the new variable `replace-character-fold' is customized to a non-nil
+value.  This is analogous to case folding, but instead of disregarding
+case variants, it disregards wider classes of distinctions between
+similar characters.  (Case folding is a special case of character
+folding.)  This means many characters in the search string will match
+entire groups of characters instead of just themselves.
+
+For instance, the " will match all variants of double quotes (like “
+and ”), and the letter a will match all of its accented cousins, even
+those composed of multiple characters, as well as many other symbols
+like ℀, ℁, ⒜, and ⓐ.
+
++++
+*** New function `character-fold-to-regexp' can be used
+by searching commands to produce a regexp matching anything that
+character-folds into STRING.
+
++++
+*** The new M-s M-w key binding uses eww to search the web for the
+text in the region.  The search engine to use for this is specified by
+the customizable variable `eww-search-prefix'.
+
++++
 *** Query-replace history is enhanced.
 When query-replace reads the FROM string from the minibuffer, typing
 `M-p' will now show previous replacements as "FROM SEP TO", where FROM

lisp/isearch.el

@@ -96,8 +96,12 @@ in Isearch mode is always downcased."
 
 (defcustom search-nonincremental-instead t
   "If non-nil, do a nonincremental search instead of exiting immediately.
-Actually, `isearch-edit-string' is called to let you enter the search
-string, and RET terminates editing and does a nonincremental search."
+This affects the behavior of `isearch-exit' and any key bound to that
+command: if this variable is nil, `isearch-exit' always exits the search;
+if the value is non-nil, and the search string is empty, `isearch-exit'
+starts a nonincremental search instead.  (Actually, `isearch-edit-string'
+is called to let you enter the search string, and RET terminates editing
+and does a nonincremental search.)"
   :type 'boolean)
 
 (defcustom search-whitespace-regexp (purecopy "\\s-+")
@@ -142,9 +146,11 @@ whenever point is in one of them."
 (defcustom isearch-hide-immediately t
   "If non-nil, re-hide an invisible match right away.
 This variable makes a difference when `search-invisible' is set to `open'.
+If non-nil, invisible matches are re-hidden as soon as the match moves
+off the invisible text surrounding the match.
 If nil then do not re-hide opened invisible text when the match moves.
 Whatever the value, all opened invisible text is hidden again after exiting
-the search."
+the search, with the exception of the last successful match, if any."
   :type 'boolean)
 
 (defcustom isearch-resume-in-command-history nil

lisp/replace.el

@@ -111,7 +111,8 @@ strings or patterns."
   :version "22.1")
 
 (defcustom query-replace-show-replacement t
-  "Non-nil means to show what actual replacement text will be."
+  "Non-nil means show substituted replacement text in the minibuffer.
+This variable affects only `query-replace-regexp'."
   :type 'boolean
   :group 'matching
   :version "23.1")