@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Search, Fixit, Display, Top
or else edit the search string.
* Isearch Scroll:: Scrolling during an incremental search.
* Isearch Minibuffer:: Incremental search of the minibuffer history.
-* Slow Isearch:: Incremental search features for slow terminals.
@end menu
@node Basic Isearch
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
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}
@vindex isearch-mode-map
When incremental search is active, you can type @kbd{C-h C-h} to
-access interactive help options, including a list of special
-keybindings. These keybindings are part of the keymap
+access interactive help options, including a list of special key
+bindings. These key bindings are part of the keymap
@code{isearch-mode-map} (@pxref{Keymaps}).
@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 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 @key{prior} (@code{scroll-down}), @key{next}
-(@code{scroll-up}) and @kbd{C-l} (@code{recenter}). 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-below}) 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)
When the current match is on a history element, that history element
is pulled into the minibuffer. If you exit the incremental search
normally (e.g. by typing @key{RET}), it remains in the minibuffer
-afterwards. Cancelling the search, with @kbd{C-g}, restores the
+afterwards. Canceling the search, with @kbd{C-g}, restores the
contents of the minibuffer when you began the search.
-@node Slow Isearch
-@subsection Slow Terminal Incremental Search
-
- Incremental search on a slow terminal uses a modified style of display
-that is designed to take less time. Instead of redisplaying the buffer at
-each place the search gets to, it creates a new single-line window and uses
-that to display the line that the search has found. The single-line window
-comes into play as soon as point moves outside of the text that is already
-on the screen.
-
- When you terminate the search, the single-line window is removed.
-Emacs then redisplays the window in which the search was done, to show
-its new position of point.
-
-@vindex search-slow-speed
- The slow terminal style of display is used when the terminal baud rate is
-less than or equal to the value of the variable @code{search-slow-speed},
-initially 1200. See also the discussion of the variable @code{baud-rate}
-(@pxref{baud-rate,, Customization of Display}).
-
-@vindex search-slow-window-lines
- The number of lines to use in slow terminal search display is controlled
-by the variable @code{search-slow-window-lines}. Its normal value is 1.
-
@node Nonincremental Search
@section Nonincremental Search
@cindex nonincremental search
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
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
@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}}.
word-constituent character.
@item \w
-matches any word-constituent character. The syntax table
-determines which characters these are. @xref{Syntax}.
+matches any word-constituent character. The syntax table determines
+which characters these are. @xref{Syntax Tables,, Syntax Tables,
+elisp, The Emacs Lisp Reference Manual}.
@item \W
matches any character that is not a word-constituent.
matches any character whose syntax is @var{c}. Here @var{c} is a
character that designates a particular syntax class: thus, @samp{w}
for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.}
-for ordinary punctuation, etc. @xref{Syntax}.
+for ordinary punctuation, etc. @xref{Syntax Tables,, Syntax Tables,
+elisp, The Emacs Lisp Reference Manual}.
@item \S@var{c}
matches any character whose syntax is not @var{c}.
@var{c}.
@end table
- The constructs that pertain to words and syntax are controlled by the
-setting of the syntax table (@pxref{Syntax}).
+ The constructs that pertain to words and syntax are controlled by
+the setting of the syntax table. @xref{Syntax Tables,, Syntax Tables,
+elisp, The Emacs Lisp Reference Manual}.
@node Regexp Example
@section Regular Expression Example
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
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}).
@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.
@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
@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-%
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
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
@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
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