Commit 5abc31ef authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent 939db9ac
......@@ -191,7 +191,7 @@ programs.texi
regs.texi cyd
rmail.texi
screen.texi cyd
search.texi
search.texi cyd
sending.texi
text.texi
trouble.texi
......
2011-10-19 Chong Yidong <cyd@gnu.org>
* 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 <cyd@gnu.org>
* display.texi (Fringes): Move overflow-newline-into-fringe here,
......
......@@ -166,23 +166,27 @@ going past the original starting point of the search, it changes to
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
......@@ -195,6 +199,7 @@ search string the characters that could not be found (the @samp{T} in
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}
......@@ -270,62 +275,70 @@ keybindings. These keybindings are part of the keymap
@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 @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 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-vertically}) 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)
......@@ -380,18 +393,14 @@ This enters the minibuffer to read the search string; terminate the
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
......@@ -451,7 +460,7 @@ apply to the lazy highlight, which always matches whole words.
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 @@ starting position. These search methods are not mirror images.
@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 @@ close-brackets, quotes, or parentheses, repeated zero or more times.
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
......@@ -960,8 +969,8 @@ command, there is @kbd{M-%} (@code{query-replace}), which presents
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 @@ activating the mark; use @kbd{C-u C-@key{SPC}} to move back there.
@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 @@ replacement is done without case conversion.
@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
......@@ -1144,7 +1151,7 @@ occurrence and asks you whether to replace it. Aside from querying,
@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-%
......@@ -1157,7 +1164,7 @@ like @code{query-replace}.
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
......@@ -1290,6 +1297,8 @@ matching that regexp.
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
......@@ -1300,16 +1309,22 @@ 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.
@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
......@@ -1317,9 +1332,6 @@ Run @code{occur} using the search string of the last incremental
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
......
......@@ -448,7 +448,7 @@ pops up *Messages*" feature, which can now easily be changed.
+++
*** 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 @@ They are superseded by shift-select-mode enabled by default in 23.1.
* 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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment