X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/4aa2d40e1a8959db8daf71a4e47eb65fcbd3d56d..adc55deaa5e0496d50042dd5a6bd4d0c41e09c78:/man/search.texi

diff --git a/man/search.texi b/man/search.texi
index 36ed374715..a9d5b5e9ba 100644
--- a/man/search.texi
+++ b/man/search.texi
@@ -181,15 +181,18 @@ backward search finds matches that are entirely before the starting
 point, just as a forward search finds matches that begin after it.
 
   The characters @kbd{C-y} and @kbd{C-w} can be used in incremental
-search to grab text from the buffer into the search string.  This makes
-it convenient to search for another occurrence of text at point.
-@kbd{C-w} copies the word after point as part of the search string,
-advancing point over that word.  Another @kbd{C-s} to repeat the search
-will then search for a string including that word.  @kbd{C-y} is similar
-to @kbd{C-w} but copies all the rest of the current line into the search
-string.  Both @kbd{C-y} and @kbd{C-w} convert the text they copy to
-lower case if the search is currently not case-sensitive; this is so the
-search remains case-insensitive.
+search to grab text from the buffer into the search string.  This
+makes it convenient to search for another occurrence of text at point.
+@kbd{C-w} copies the character or word after point as part of the
+search string, advancing point over it.  (The decision, whether to
+copy a character or a word, is heuristic.)  Another @kbd{C-s} to
+repeat the search will then search for a string including that
+character or word.
+
+  @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the
+current line into the search string.  Both @kbd{C-y} and @kbd{C-w}
+convert the text they copy to lower case if the search is currently
+not case-sensitive; this is so the search remains case-insensitive.
 
   The character @kbd{M-y} copies text from the kill ring into the search
 string.  It uses the same text that @kbd{C-y} as a command would yank.
@@ -463,6 +466,13 @@ the text @samp{abbb}, @samp{ab*} will match it all (the longest valid
 match), while @samp{ab*?}  will match just @samp{a} (the shortest
 valid match).
 
+Non-greedy operators match the shortest possible string starting at a
+given starting point; in a forward search, though, the earliest
+possible starting point for match is always the one chosen.  Thus, if
+you search for @samp{a.*?$} against the text @samp{abbab} followed by
+a newline, it matches the whole string.  Since it @emph{can} match
+starting at the first @samp{a}, it does.
+
 @item \@{@var{n}\@}
 is a postfix operator that specifies repetition @var{n} times---that
 is, the preceding regular expression must match exactly @var{n} times
@@ -791,11 +801,12 @@ there is a @kbd{M-x query-replace} command which finds 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; however, in Transient Mark mode, when the mark is
-active, they operate on the region.  The replace commands all replace
-one string (or regexp) with one replacement string.  It is possible to
-perform several replacements in parallel using the command
-@code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
+end of the buffer; however, in Transient Mark mode (@pxref{Transient
+Mark}), when the mark is active, they operate on the region.  The
+replace commands all replace one string (or regexp) with one
+replacement string.  It is possible to perform several replacements in
+parallel using the command @code{expand-region-abbrevs}
+(@pxref{Expanding Abbrevs}).
 
 @menu
 * Unconditional Replace::  Replacing all matches for a string.
@@ -834,6 +845,18 @@ C-@key{SPC}} to move back there.
   A numeric argument restricts replacement to matches that are surrounded
 by word boundaries.  The argument's value doesn't matter.
 
+  What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} with a @samp{y} and vice versa?  You can do it this way:
+
+@example
+M-x query-replace @key{RET} x @key{RET} @@TEMP@@ @key{RET}
+M-x query-replace @key{RET} y @key{RET} x @key{RET}
+M-x query-replace @key{RET} @@TEMP@@ @key{RET} y @key{RET}
+@end example
+
+@noindent
+This works provided the string @samp{@@TEMP@@} does not appear
+in your text.
+
 @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
 @subsection Regexp Replacement
 
@@ -1028,11 +1051,14 @@ copy, or link files by replacing regexp matches in file names.
   Here are some other commands that find matches for a regular
 expression.  They all ignore case in matching, if the pattern contains
 no upper-case letters and @code{case-fold-search} is non-@code{nil}.
-Aside from @code{occur}, all operate on the text from point to the end
-of the buffer, or on the active region in Transient Mark mode.
+Aside from @code{occur} and its variants, all operate on the text from
+point to the end of the buffer, or on the active region in Transient
+Mark mode.
 
 @findex list-matching-lines
 @findex occur
+@findex multi-occur
+@findex multi-occur-by-filename-regexp
 @findex how-many
 @findex delete-non-matching-lines
 @findex delete-matching-lines
@@ -1048,15 +1074,27 @@ specifies that @var{n} lines of context are to be 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.
+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.
 
 @item M-x list-matching-lines
 Synonym for @kbd{M-x occur}.
 
+@item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET}
+This function is just like @code{occur}, except it is able to search
+through multiple buffers.
+
+@item M-x multi-occur-by-filename-regexp @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET}
+This function is similar to @code{multi-occur}, except the buffers to
+search are specified by a regexp on their filename.
+
 @item M-x how-many @key{RET} @var{regexp} @key{RET}
 Print the number of matches for @var{regexp} that exist in the buffer
 after point.  In Transient Mark mode, if the region is active, the