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 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}}.
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