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.

1 files changed, 9 insertions, 3 deletions

diff --git a/lisp/isearch.el b/lisp/isearch.el
index 080eb578aa7..0a6b925d03e 100644
--- a/lisp/isearch.el
+++ b/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