Update Search chapter in Emacs manual.

* doc/emacs/search.texi (Repeat Isearch, Error in Isearch): Add kindex entries.
(Isearch Yank): Document isearch-yank-pop.
(Isearch Scroll): Refer to C-l instead of unbound `recenter'.
(Other Repeating Search): Document Occur Edit mode.

4 files changed, 109 insertions, 88 deletions

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index df559785c2b..7b1b7df7704 100644
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -191,7 +191,7 @@ programs.texi
 regs.texi         cyd
 rmail.texi        
 screen.texi       cyd
-search.texi       
+search.texi       cyd
 sending.texi      
 text.texi         
 trouble.texi      
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 6e93e7a259e..63afcd228ad 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,11 @@
+2011-10-19  Chong Yidong  <cyd@gnu.org>
+
+        * search.texi (Repeat Isearch, Error in Isearch): Add kindex
+        entries.
+        (Isearch Yank): Document isearch-yank-pop.
+        (Isearch Scroll): Refer to C-l instead of unbound `recenter'.
+        (Other Repeating Search): Document Occur Edit mode.
+
 2011-10-18  Chong Yidong  <cyd@gnu.org>
 
         * display.texi (Fringes): Move overflow-newline-into-fringe here,
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 7290de1caab..8e77de0bbb4 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -166,23 +166,27 @@ going past the original starting point of the search, it changes to
 you have already seen.
 
 @cindex search ring
+@kindex M-n @r{(Incremental search)}
+@kindex M-p @r{(Incremental search)}
   To reuse earlier search strings, use the @dfn{search ring}.  The
 commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a
 search string to reuse.  These commands leave the selected search ring
-element in the minibuffer, where you can edit it.  To edit the current
-search string in the minibuffer without replacing it with items from
-the search ring, type @kbd{M-e}.  Type @kbd{C-s} or @kbd{C-r} to
-terminate editing the string and search for it.
+element in the minibuffer, where you can edit it.
+
+@kindex M-e @r{(Incremental search)}
+  To edit the current search string in the minibuffer without
+replacing it with items from the search ring, type @kbd{M-e}.  Type
+@kbd{C-s} or @kbd{C-r} to finish editing the string and search for it.
 
 @node Error in Isearch
 @subsection Errors in Incremental Search
 
   If your string is not found at all, the echo area says @samp{Failing
-I-Search}.  The cursor is after the place where Emacs found as much of
-your string as it could.  Thus, if you search for @samp{FOOT}, and
-there is no @samp{FOOT}, you might see the cursor after the @samp{FOO}
-in @samp{FOOL}.  In the echo area, the part of the search string that
-failed to match is highlighted using the customizable face
+I-Search}, and the cursor moves past the place where Emacs found as
+much of your string as it could.  Thus, if you search for @samp{FOOT},
+and there is no @samp{FOOT}, you might see the cursor after the
+@samp{FOO} in @samp{FOOL}.  In the echo area, the part of the search
+string that failed to match is highlighted using the face
 @code{isearch-fail}.
 
   At this point, there are several things you can do.  If your string
@@ -195,6 +199,7 @@ search string the characters that could not be found (the @samp{T} in
 entirely, returning point to where it was when the search started.
 
 @cindex quitting (in search)
+@kindex C-g @r{(Incremental search)}
   The quit command, @kbd{C-g}, does special things during searches;
 just what it does depends on the status of the search.  If the search
 has found what you specified and is waiting for input, @kbd{C-g}
@@ -270,62 +275,70 @@ keybindings.  These keybindings are part of the keymap
 @node Isearch Yank
 @subsection Isearch Yanking
 
+@kindex C-y @r{(Incremental search)}
+@kindex M-y @r{(Incremental search)}
+@findex isearch-yank-kill
+@findex isearch-yank-pop
   Within incremental search, @kbd{C-y} (@code{isearch-yank-kill})
-copies text from the kill ring into the search string.  It uses the
-same text that @kbd{C-y}, outside of incremental search, would
-normally yank into the buffer.  @kbd{Mouse-2} in the echo area does
-the same.  @xref{Yanking}.
-
-  @kbd{C-w} (@code{isearch-yank-word-or-char}) grabs the next
-character or word at point, and adds it to the search string.  This is
-convenient for searching for another occurrence of the text at point.
-(The decision, whether to copy a character or a word, is heuristic.)
-
-  Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) grabs the rest
-of the current line, and adds it to the search string.  If point is
-already at the end of a line, it grabs the entire next line.
+appends the current kill to the search string.  @kbd{M-y}
+(@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that
+appended text with an earlier kill, similar to the usual @kbd{M-y}
+(@code{yank-pop}) command (@pxref{Yanking}).  @kbd{Mouse-2} appends
+the current X selection (@pxref{Primary Selection}).
+
+@kindex C-w @r{(Incremental search)}
+@findex isearch-yank-word-or-char
+  @kbd{C-w} (@code{isearch-yank-word-or-char}) appends the next
+character or word at point to the search string.  This is an easy way
+to search for another occurrence of the text at point.  (The decision
+of whether to copy a character or a word is heuristic.)
+
+@kindex M-s C-e @r{(Incremental search)}
+@findex isearch-yank-line
+  Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest
+of the current line to the search string.  If point is already at the
+end of a line, it appends the next line.
 
   If the search is currently case-insensitive, both @kbd{C-w} and
 @kbd{M-s C-e} convert the text they copy to lower case, so that the
 search remains case-insensitive.
 
-  @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one
-character at a time: @kbd{C-M-w} deletes the last character from the
-search string and @kbd{C-M-y} copies the character after point to the
-end of the search string.  An alternative method to add the character
-after point into the search string is to enter the minibuffer by
-@kbd{M-e} and to type @kbd{C-f} at the end of the search string in the
-minibuffer.
+@kindex C-M-w @r{(Incremental search)}
+@kindex C-M-y @r{(Incremental search)}
+@findex isearch-del-char
+@findex isearch-yank-char
+  @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character
+from the search string, and @kbd{C-M-y} (@code{isearch-yank-char})
+appends the character after point to the the search string.  An
+alternative method to add the character after point is to enter the
+minibuffer with @kbd{M-e} (@pxref{Repeat Isearch}) and type @kbd{C-f}
+at the end of the search string in the minibuffer.
 
 @node Isearch Scroll
 @subsection Scrolling During Incremental Search
 
 @vindex isearch-allow-scroll
-  You can enable the use of vertical scrolling during incremental
-search (without exiting the search) by setting the customizable
-variable @code{isearch-allow-scroll} to a non-@code{nil} value.  This
-applies to using the vertical scroll-bar and to certain keyboard
-commands such as @code{scroll-down-command}, @code{scroll-up-command}
-and @code{recenter} (@pxref{Scrolling}).  You must run these commands
-via their key sequences to stay in the search---typing @kbd{M-x} will
-terminate the search.  You can give prefix arguments to these commands
-in the usual way.
-
-  This feature won't let you scroll the current match out of visibility,
-however.
-
-  The feature also affects some other commands, such as @kbd{C-x 2}
-(@code{split-window-vertically}) and @kbd{C-x ^}
-(@code{enlarge-window}) which don't exactly scroll but do affect where
-the text appears on the screen.  In general, it applies to any command
-whose name has a non-@code{nil} @code{isearch-scroll} property.  So you
-can control which commands are affected by changing these properties.
+  Normally, scrolling commands exit incremental search.  If you change
+the variable @code{isearch-allow-scroll} to a non-@code{nil} value,
+that enables the use of the scroll-bar, as well as keyboard scrolling
+commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}).
+This applies only to calling these commands via their bound key
+sequences---typing @kbd{M-x} will still exit the search.  You can give
+prefix arguments to these commands in the usual way.  This feature
+won't let you scroll the current match out of visibility, however.
+
+  The @code{isearch-allow-scroll} feature also affects some other
+commands, such as @kbd{C-x 2} (@code{split-window-vertically}) and
+@kbd{C-x ^} (@code{enlarge-window}), which don't exactly scroll but do
+affect where the text appears on the screen.  It applies to any
+command whose name has a non-@code{nil} @code{isearch-scroll}
+property.  So you can control which commands are affected by changing
+these properties.
 
   For example, to make @kbd{C-h l} usable within an incremental search
 in all future Emacs sessions, use @kbd{C-h c} to find what command it
-runs.  (You type @kbd{C-h c C-h l}; it says @code{view-lossage}.)
-Then you can put the following line in your @file{.emacs} file
-(@pxref{Init File}):
+runs (@pxref{Key Help}), which is @code{view-lossage}.  Then you can
+put the following line in your init file (@pxref{Init File}):
 
 @example
 (put 'view-lossage 'isearch-scroll t)
@@ -380,18 +393,14 @@ This enters the minibuffer to read the search string; terminate the
 string with @key{RET}, and then the search takes place.  If the string
 is not found, the search command signals an error.
 
-  When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
-search as usual.  That command is specially programmed to invoke
-nonincremental search, @code{search-forward}, if the string you
-specify is empty.  (Such an empty argument would otherwise be
-useless.)  @kbd{C-r @key{RET}} does likewise, for a reverse
-incremental search.
-
 @findex search-forward
 @findex search-backward
-  Forward and backward nonincremental searches are implemented by the
-commands @code{search-forward} and @code{search-backward}.  These
-commands may be bound to other keys in the usual manner.
+  When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
+search as usual.  That command is specially programmed to invoke the
+command for nonincremental search, @code{search-forward}, if the
+string you specify is empty.  (Such an empty argument would otherwise
+be useless.)  @kbd{C-r @key{RET}} does likewise, invoking the command
+@code{search-backward}.
 
 @node Word Search
 @section Word Search
@@ -451,7 +460,7 @@ apply to the lazy highlight, which always matches whole words.
 that denotes a class of alternative strings to match.  GNU Emacs
 provides both incremental and nonincremental ways to search for a
 match for a regexp.  The syntax of regular expressions is explained in
-the following section.
+the next section.
 
 @table @kbd
 @item C-M-s
@@ -506,7 +515,7 @@ starting position.  These search methods are not mirror images.
 
 @findex re-search-forward
 @findex re-search-backward
-  Nonincremental search for a regexp is done by the functions
+  Nonincremental search for a regexp is done with the commands
 @code{re-search-forward} and @code{re-search-backward}.  You can
 invoke these with @kbd{M-x}, or by way of incremental regexp search
 with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}.
@@ -916,9 +925,9 @@ close-brackets, quotes, or parentheses, repeated zero or more times.
   Searches in Emacs normally ignore the case of the text they are
 searching through, if you specify the text in lower case.  Thus, if
 you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo}
-are also considered a match.  Regexps, and in particular character
-sets, are included: @samp{[ab]} would match @samp{a} or @samp{A} or
-@samp{b} or @samp{B}.@refill
+also match.  Regexps, and in particular character sets, behave
+likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or
+@samp{B}.@refill
 
   An upper-case letter anywhere in the incremental search string makes
 the search case-sensitive.  Thus, searching for @samp{Foo} does not find
@@ -960,8 +969,8 @@ command, there is @kbd{M-%} (@code{query-replace}), which presents
 each occurrence of the pattern and asks you whether to replace it.
 
   The replace commands normally operate on the text from point to the
-end of the buffer.  When the mark is active, they operate on the
-region instead (@pxref{Mark}).  The basic replace commands replace one
+end of the buffer.  When the region is active, they operate on it
+instead (@pxref{Mark}).  The basic replace commands replace one
 @dfn{search string} (or regexp) with one @dfn{replacement string}.  It
 is possible to perform several replacements in parallel, using the
 command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
@@ -998,7 +1007,7 @@ activating the mark; use @kbd{C-u C-@key{SPC}} to move back there.
 @xref{Mark Ring}.
 
   A prefix argument restricts replacement to matches that are
-surrounded by word boundaries.  The argument's value doesn't matter.
+surrounded by word boundaries.
 
   @xref{Replacement and Case}, for details about case-sensitivity in
 replace commands.
@@ -1128,10 +1137,8 @@ replacement is done without case conversion.
 
 @table @kbd
 @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
-@itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
 Replace some occurrences of @var{string} with @var{newstring}.
 @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
-@itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
 Replace some matches for @var{regexp} with @var{newstring}.
 @end table
 
@@ -1144,7 +1151,7 @@ occurrence and asks you whether to replace it.  Aside from querying,
 @code{query-replace} works just like @code{replace-string}
 (@pxref{Unconditional Replace}).  In particular, it preserves case
 provided @code{case-replace} is non-@code{nil}, as it normally is
-(@pxref{Replacement and Case}).  A numeric argument means consider
+(@pxref{Replacement and Case}).  A numeric argument means to consider
 only occurrences that are bounded by word-delimiter characters.
 
 @kindex C-M-%
@@ -1157,7 +1164,7 @@ like @code{query-replace}.
   These commands highlight the current match using the face
 @code{query-replace}.  They highlight other matches using
 @code{lazy-highlight} just like incremental search (@pxref{Incremental
-Search}).  By default, @code{query-replace-regexp} will show
+Search}).  By default, @code{query-replace-regexp} will show the
 substituted replacement string for the current match in the
 minibuffer.  If you want to keep special sequences @samp{\&} and
 @samp{\@var{n}} unexpanded, customize
@@ -1290,6 +1297,8 @@ matching that regexp.
 This command is just like @code{multi-isearch-buffers}, except it
 performs an incremental regexp search.
 
+@cindex Occur mode
+@cindex mode, Occur
 @item M-x occur
 Prompt for a regexp, and display a list showing each line in the
 buffer that contains a match for it.  To limit the search to part of
@@ -1300,16 +1309,22 @@ displayed before and after each matching line.
 @kindex RET @r{(Occur mode)}
 @kindex o @r{(Occur mode)}
 @kindex C-o @r{(Occur mode)}
-The buffer @samp{*Occur*} containing the output serves as a menu for
-finding the occurrences in their original context.  Click
-@kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position
-point there and type @key{RET}; this switches to the buffer that was
-searched and moves point to the original of the chosen occurrence.
-@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o}
-does not select it.
-
-After using @kbd{M-x occur}, you can use @code{next-error} to visit
-the occurrences found, one by one.  @ref{Compilation Mode}.
+In the @samp{*Occur*} buffer, you can click on each entry, or move
+point there and type @key{RET}, to visit the corresponding position in
+the buffer that was searched.  @kbd{o} and @kbd{C-o} display the match
+in another window; @kbd{C-o} does not select it.  Alternatively, you
+can use the @kbd{C-x `} (@code{next-error}) command to visit the
+occurrences one by one (@pxref{Compilation Mode}).
+
+@cindex Occur Edit mode
+@cindex mode, Occur Edit
+Typing @kbd{e} in the @samp{*Occur*} buffer switches to Occur Edit
+mode, in which edits made to the entries are also applied to the text
+in the originating buffer.  Type @kbd{C-c C-c} to return to Occur
+mode.
+
+The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x
+occur}.
 
 @kindex M-s o
 @item M-s o
@@ -1317,9 +1332,6 @@ Run @code{occur} using the search string of the last incremental
 string search.  You can also run @kbd{M-s o} when an incremental
 search is active; this uses the current search string.
 
-@item M-x list-matching-lines
-Synonym for @kbd{M-x occur}.
-
 @item M-x multi-occur
 This command is just like @code{occur}, except it is able to search
 through multiple buffers.  It asks you to specify the buffer names one
diff --git a/etc/NEWS b/etc/NEWS
index edb7f2c171d..b987e8548cf 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -448,7 +448,7 @@ pops up *Messages*" feature, which can now easily be changed.
 +++
 *** C-y in Isearch is now bound to isearch-yank-kill, instead of
 isearch-yank-line.
----
++++
 *** M-y in Isearch is now bound to isearch-yank-pop, instead of
 isearch-yank-kill.
 +++
@@ -883,6 +883,7 @@ They are superseded by shift-select-mode enabled by default in 23.1.
 
 * New Modes and Packages in Emacs 24.1
 
++++
 ** Occur Edit mode applies edits made in *Occur* buffers to the
 original buffers.  It is bound to "e" in Occur mode.