(expose_window): Fix error in calculation of

[gnu-emacs] / man / search.texi

diff --git a/man/search.texi b/man/search.texi
index 3c6cc3539ed2a3671348ec46791e67137c304c0b..ea08626a6abe521eaf088d1fa14d1659d14bfb26 100644 (file)
--- 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
 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.
 
   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.


@@ -382,6 +385,11 @@ Search}.
 @section Syntax of Regular Expressions
 @cindex syntax of regexps
 
 @section Syntax of Regular Expressions
 @cindex syntax of regexps
 

+  This manual describes regular expression features that users
+typically want to use.  There are additional features that are
+mainly used in Lisp programs; see @ref{Regular Expressions,,,
+elisp, the same manual}.
+

   Regular expressions have a syntax in which a few characters are
 special constructs and the rest are @dfn{ordinary}.  An ordinary
 character is a simple regular expression which matches that same
   Regular expressions have a syntax in which a few characters are
 special constructs and the rest are @dfn{ordinary}.  An ordinary
 character is a simple regular expression which matches that same


@@ -410,14 +418,14 @@ and @samp{o} to get the regular expression @samp{fo}, which matches only
 the string @samp{fo}.  Still trivial.  To do something nontrivial, you
 need to use one of the special characters.  Here is a list of them.
 
 the string @samp{fo}.  Still trivial.  To do something nontrivial, you
 need to use one of the special characters.  Here is a list of them.
 

-@table @kbd
-@item .@: @r{(Period)}
+@table @asis
+@item @kbd{.}@: @r{(Period)}

 is a special character that matches any single character except a newline.
 Using concatenation, we can make regular expressions like @samp{a.b}, which
 matches any three-character string that begins with @samp{a} and ends with
 @samp{b}.@refill
 
 is a special character that matches any single character except a newline.
 Using concatenation, we can make regular expressions like @samp{a.b}, which
 matches any three-character string that begins with @samp{a} and ends with
 @samp{b}.@refill
 

-@item *
+@item @kbd{*}

 is not a construct by itself; it is a postfix operator that means to
 match the preceding regular expression repetitively as many times as
 possible.  Thus, @samp{o*} matches any number of @samp{o}s (including no
 is not a construct by itself; it is a postfix operator that means to
 match the preceding regular expression repetitively as many times as
 possible.  Thus, @samp{o*} matches any number of @samp{o}s (including no


@@ -438,18 +446,18 @@ tries to match all three @samp{a}s; but the rest of the pattern is
 The next alternative is for @samp{a*} to match only two @samp{a}s.
 With this choice, the rest of the regexp matches successfully.@refill
 
 The next alternative is for @samp{a*} to match only two @samp{a}s.
 With this choice, the rest of the regexp matches successfully.@refill
 

-@item +
+@item @kbd{+}

 is a postfix operator, similar to @samp{*} except that it must match
 the preceding expression at least once.  So, for example, @samp{ca+r}
 matches the strings @samp{car} and @samp{caaaar} but not the string
 @samp{cr}, whereas @samp{ca*r} matches all three strings.
 
 is a postfix operator, similar to @samp{*} except that it must match
 the preceding expression at least once.  So, for example, @samp{ca+r}
 matches the strings @samp{car} and @samp{caaaar} but not the string
 @samp{cr}, whereas @samp{ca*r} matches all three strings.
 

-@item ?
+@item @kbd{?}

 is a postfix operator, similar to @samp{*} except that it can match the
 preceding expression either once or not at all.  For example,
 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
 
 is a postfix operator, similar to @samp{*} except that it can match the
 preceding expression either once or not at all.  For example,
 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
 

-@item *?, +?, ??
+@item @kbd{*?}, @kbd{+?}, @kbd{??}

 @cindex non-greedy regexp matching
 are non-greedy variants of the operators above.  The normal operators
 @samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as
 @cindex non-greedy regexp matching
 are non-greedy variants of the operators above.  The normal operators
 @samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as


@@ -463,13 +471,20 @@ 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).
 
 match), while @samp{ab*?}  will match just @samp{a} (the shortest
 valid match).
 

-@item \@{@var{n}\@}
+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 @kbd{\@{@var{n}\@}}

 is a postfix operator that specifies repetition @var{n} times---that
 is, the preceding regular expression must match exactly @var{n} times
 in a row.  For example, @samp{x\@{4\@}} matches the string @samp{xxxx}
 and nothing else.
 
 is a postfix operator that specifies repetition @var{n} times---that
 is, the preceding regular expression must match exactly @var{n} times
 in a row.  For example, @samp{x\@{4\@}} matches the string @samp{xxxx}
 and nothing else.
 

-@item \@{@var{n},@var{m}\@}
+@item @kbd{\@{@var{n},@var{m}\@}}

 is a postfix operator that specifies repetition between @var{n} and
 @var{m} times---that is, the preceding regular expression must match
 at least @var{n} times, but no more than @var{m} times.  If @var{m} is
 is a postfix operator that specifies repetition between @var{n} and
 @var{m} times---that is, the preceding regular expression must match
 at least @var{n} times, but no more than @var{m} times.  If @var{m} is


@@ -478,7 +493,7 @@ expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is
 equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
 @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
 
 equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
 @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
 

-@item [ @dots{} ]
+@item @kbd{[ @dots{} ]}

 is a @dfn{character set}, which begins with @samp{[} and is terminated
 by @samp{]}.  In the simplest case, the characters between the two
 brackets are what this set can match.
 is a @dfn{character set}, which begins with @samp{[} and is terminated
 by @samp{]}.  In the simplest case, the characters between the two
 brackets are what this set can match.


@@ -513,7 +528,7 @@ ends of the range in upper case, or both in lower case, or both should
 be non-letters.  The behavior of a mixed-case range such as @samp{A-z}
 is somewhat ill-defined, and it may change in future Emacs versions.
 
 be non-letters.  The behavior of a mixed-case range such as @samp{A-z}
 is somewhat ill-defined, and it may change in future Emacs versions.
 

-@item [^ @dots{} ]
+@item @kbd{[^ @dots{} ]}

 @samp{[^} begins a @dfn{complemented character set}, which matches any
 character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
 all characters @emph{except} ASCII letters and digits.
 @samp{[^} begins a @dfn{complemented character set}, which matches any
 character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
 all characters @emph{except} ASCII letters and digits.


@@ -526,17 +541,17 @@ A complemented character set can match a newline, unless newline is
 mentioned as one of the characters not to match.  This is in contrast to
 the handling of regexps in programs such as @code{grep}.
 
 mentioned as one of the characters not to match.  This is in contrast to
 the handling of regexps in programs such as @code{grep}.
 

-@item ^
+@item @kbd{^}

 is a special character that matches the empty string, but only at the
 beginning of a line in the text being matched.  Otherwise it fails to
 match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
 the beginning of a line.
 
 is a special character that matches the empty string, but only at the
 beginning of a line in the text being matched.  Otherwise it fails to
 match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
 the beginning of a line.
 

-@item $
+@item @kbd{$}

 is similar to @samp{^} but matches only at the end of a line.  Thus,
 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
 
 is similar to @samp{^} but matches only at the end of a line.  Thus,
 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
 

-@item \
+@item @kbd{\}

 has two functions: it quotes the special characters (including
 @samp{\}), and it introduces additional special constructs.
 
 has two functions: it quotes the special characters (including
 @samp{\}), and it introduces additional special constructs.
 


@@ -632,12 +647,12 @@ If a particular @samp{\( @dots{} \)} construct matches more than once
 match is recorded.
 
 @item \`
 match is recorded.
 
 @item \`

-matches the empty string, but only at the beginning
-of the buffer or string being matched against.
+matches the empty string, but only at the beginning of the string or
+buffer (or its accessible portion) being matched against.

 
 @item \'
 
 @item \'

-matches the empty string, but only at the end of
-the buffer or string being matched against.
+matches the empty string, but only at the end of the string or buffer
+(or its accessible portion) being matched against.

 
 @item \=
 matches the empty string, but only at point.
 
 @item \=
 matches the empty string, but only at point.


@@ -791,11 +806,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
 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.
 
 @menu
 * Unconditional Replace::  Replacing all matches for a string.


@@ -834,6 +850,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.
 
   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
 
 @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
 @subsection Regexp Replacement
 


@@ -1028,11 +1056,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}.
   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 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
 @findex how-many
 @findex delete-non-matching-lines
 @findex delete-matching-lines


@@ -1048,15 +1079,27 @@ specifies that @var{n} lines of context are to be displayed before and
 after each matching line.
 
 @kindex RET @r{(Occur mode)}
 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
 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 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
 @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