[Emacs-diffs] /srv/bzr/emacs/trunk r106128: Update Search chapter in Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106128
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2011-10-19 00:21:52 -0400
message:
  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.
modified:
  admin/FOR-RELEASE
  doc/emacs/ChangeLog
  doc/emacs/search.texi
  etc/NEWS

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2011-10-18 21:11:17 +0000
+++ b/admin/FOR-RELEASE 2011-10-19 04:21:52 +0000
@@ -191,7 +191,7 @@
 regs.texi         cyd
 rmail.texi        
 screen.texi       cyd
-search.texi       
+search.texi       cyd
 sending.texi      
 text.texi         
 trouble.texi      

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-10-18 21:11:17 +0000
+++ b/doc/emacs/ChangeLog       2011-10-19 04:21:52 +0000
@@ -1,3 +1,11 @@
+2011-10-19  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * display.texi (Fringes): Move overflow-newline-into-fringe here,

=== modified file 'doc/emacs/search.texi'
--- a/doc/emacs/search.texi     2011-10-18 21:11:17 +0000
+++ b/doc/emacs/search.texi     2011-10-19 04:21:52 +0000
@@ -166,23 +166,27 @@
 you have already seen.
 
 @cindex search ring
address@hidden M-n @r{(Incremental search)}
address@hidden 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.
+
address@hidden 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
address@hidden 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
address@hidden 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 @@
 entirely, returning point to where it was when the search started.
 
 @cindex quitting (in search)
address@hidden 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 @@
 @node Isearch Yank
 @subsection Isearch Yanking
 
address@hidden C-y @r{(Incremental search)}
address@hidden M-y @r{(Incremental search)}
address@hidden isearch-yank-kill
address@hidden 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}).
+
address@hidden C-w @r{(Incremental search)}
address@hidden 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.)
+
address@hidden M-s C-e @r{(Incremental search)}
address@hidden 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
address@hidden and to type @kbd{C-f} at the end of the search string in the
-minibuffer.
address@hidden C-M-w @r{(Incremental search)}
address@hidden C-M-y @r{(Incremental search)}
address@hidden isearch-del-char
address@hidden 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 address@hidden 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 address@hidden @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 address@hidden 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
address@hidden ^} (@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 address@hidden @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 @@
 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
address@hidden
 
 @node Word Search
 @section Word Search
@@ -451,7 +460,7 @@
 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 @@
 
 @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 @@
   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
address@hidden or @address@hidden
+also match.  Regexps, and in particular character sets, behave
+likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or
address@hidden@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 @@
 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 @@
 @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 @@
 
 @table @kbd
 @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
address@hidden 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}
address@hidden 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 @@
 @code{query-replace} works just like @code{replace-string}
 (@pxref{Unconditional Replace}).  In particular, it preserves case
 provided @code{case-replace} is address@hidden, 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 @@
   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
 @address@hidden unexpanded, customize
@@ -1290,6 +1297,8 @@
 This command is just like @code{multi-isearch-buffers}, except it
 performs an incremental regexp search.
 
address@hidden Occur mode
address@hidden 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 @@
 @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
address@hidden 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.
address@hidden 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}).
+
address@hidden Occur Edit mode
address@hidden 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 @@
 string search.  You can also run @kbd{M-s o} when an incremental
 search is active; this uses the current search string.
 
address@hidden 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-10-18 21:11:17 +0000
+++ b/etc/NEWS  2011-10-19 04:21:52 +0000
@@ -448,7 +448,7 @@
 +++
 *** 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 @@
 
 * 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.