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 ...@@ -191,7 +191,7 @@ programs.texi
regs.texi cyd regs.texi cyd
rmail.texi rmail.texi
screen.texi cyd screen.texi cyd
search.texi search.texi cyd
sending.texi sending.texi
text.texi text.texi
trouble.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> 2011-10-18 Chong Yidong <cyd@gnu.org>
* display.texi (Fringes): Move overflow-newline-into-fringe here, * 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 ...@@ -166,23 +166,27 @@ going past the original starting point of the search, it changes to
you have already seen. you have already seen.
@cindex search ring @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 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 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 search string to reuse. These commands leave the selected search ring
element in the minibuffer, where you can edit it. To edit the current element in the minibuffer, where you can edit it.
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 @kindex M-e @r{(Incremental search)}
terminate editing the string and search for 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 finish editing the string and search for it.
@node Error in Isearch @node Error in Isearch
@subsection Errors in Incremental Search @subsection Errors in Incremental Search
If your string is not found at all, the echo area says @samp{Failing 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 I-Search}, and the cursor moves past the place where Emacs found as
your string as it could. Thus, if you search for @samp{FOOT}, and much of your string as it could. Thus, if you search for @samp{FOOT},
there is no @samp{FOOT}, you might see the cursor after the @samp{FOO} and there is no @samp{FOOT}, you might see the cursor after the
in @samp{FOOL}. In the echo area, the part of the search string that @samp{FOO} in @samp{FOOL}. In the echo area, the part of the search
failed to match is highlighted using the customizable face string that failed to match is highlighted using the face
@code{isearch-fail}. @code{isearch-fail}.
At this point, there are several things you can do. If your string 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 ...@@ -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. entirely, returning point to where it was when the search started.
@cindex quitting (in search) @cindex quitting (in search)
@kindex C-g @r{(Incremental search)}
The quit command, @kbd{C-g}, does special things during searches; 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 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} 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 ...@@ -270,62 +275,70 @@ keybindings. These keybindings are part of the keymap
@node Isearch Yank @node Isearch Yank
@subsection Isearch Yanking @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}) Within incremental search, @kbd{C-y} (@code{isearch-yank-kill})
copies text from the kill ring into the search string. It uses the appends the current kill to the search string. @kbd{M-y}
same text that @kbd{C-y}, outside of incremental search, would (@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that
normally yank into the buffer. @kbd{Mouse-2} in the echo area does appended text with an earlier kill, similar to the usual @kbd{M-y}
the same. @xref{Yanking}. (@code{yank-pop}) command (@pxref{Yanking}). @kbd{Mouse-2} appends
the current X selection (@pxref{Primary Selection}).
@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 @kindex C-w @r{(Incremental search)}
convenient for searching for another occurrence of the text at point. @findex isearch-yank-word-or-char
(The decision, whether to copy a character or a word, is heuristic.) @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
Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) grabs the rest to search for another occurrence of the text at point. (The decision
of the current line, and adds it to the search string. If point is of whether to copy a character or a word is heuristic.)
already at the end of a line, it grabs the entire next line.
@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 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 @kbd{M-s C-e} convert the text they copy to lower case, so that the
search remains case-insensitive. search remains case-insensitive.
@kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one @kindex C-M-w @r{(Incremental search)}
character at a time: @kbd{C-M-w} deletes the last character from the @kindex C-M-y @r{(Incremental search)}
search string and @kbd{C-M-y} copies the character after point to the @findex isearch-del-char
end of the search string. An alternative method to add the character @findex isearch-yank-char
after point into the search string is to enter the minibuffer by @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character
@kbd{M-e} and to type @kbd{C-f} at the end of the search string in the from the search string, and @kbd{C-M-y} (@code{isearch-yank-char})
minibuffer. 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 @node Isearch Scroll
@subsection Scrolling During Incremental Search @subsection Scrolling During Incremental Search
@vindex isearch-allow-scroll @vindex isearch-allow-scroll
You can enable the use of vertical scrolling during incremental Normally, scrolling commands exit incremental search. If you change
search (without exiting the search) by setting the customizable the variable @code{isearch-allow-scroll} to a non-@code{nil} value,
variable @code{isearch-allow-scroll} to a non-@code{nil} value. This that enables the use of the scroll-bar, as well as keyboard scrolling
applies to using the vertical scroll-bar and to certain keyboard commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}).
commands such as @code{scroll-down-command}, @code{scroll-up-command} This applies only to calling these commands via their bound key
and @code{recenter} (@pxref{Scrolling}). You must run these commands sequences---typing @kbd{M-x} will still exit the search. You can give
via their key sequences to stay in the search---typing @kbd{M-x} will prefix arguments to these commands in the usual way. This feature
terminate the search. You can give prefix arguments to these commands won't let you scroll the current match out of visibility, however.
in the usual way.
The @code{isearch-allow-scroll} feature also affects some other
This feature won't let you scroll the current match out of visibility, commands, such as @kbd{C-x 2} (@code{split-window-vertically}) and
however. @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
The feature also affects some other commands, such as @kbd{C-x 2} command whose name has a non-@code{nil} @code{isearch-scroll}
(@code{split-window-vertically}) and @kbd{C-x ^} property. So you can control which commands are affected by changing
(@code{enlarge-window}) which don't exactly scroll but do affect where these properties.
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.
For example, to make @kbd{C-h l} usable within an incremental search 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 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}.) runs (@pxref{Key Help}), which is @code{view-lossage}. Then you can
Then you can put the following line in your @file{.emacs} file put the following line in your init file (@pxref{Init File}):
(@pxref{Init File}):
@example @example
(put 'view-lossage 'isearch-scroll t) (put 'view-lossage 'isearch-scroll t)
...@@ -380,18 +393,14 @@ This enters the minibuffer to read the search string; terminate the ...@@ -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 string with @key{RET}, and then the search takes place. If the string
is not found, the search command signals an error. 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-forward
@findex search-backward @findex search-backward
Forward and backward nonincremental searches are implemented by the When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
commands @code{search-forward} and @code{search-backward}. These search as usual. That command is specially programmed to invoke the
commands may be bound to other keys in the usual manner. 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 @node Word Search
@section Word Search @section Word Search
...@@ -451,7 +460,7 @@ apply to the lazy highlight, which always matches whole words. ...@@ -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 that denotes a class of alternative strings to match. GNU Emacs
provides both incremental and nonincremental ways to search for a provides both incremental and nonincremental ways to search for a
match for a regexp. The syntax of regular expressions is explained in match for a regexp. The syntax of regular expressions is explained in
the following section. the next section.
@table @kbd @table @kbd
@item C-M-s @item C-M-s
...@@ -506,7 +515,7 @@ starting position. These search methods are not mirror images. ...@@ -506,7 +515,7 @@ starting position. These search methods are not mirror images.
@findex re-search-forward @findex re-search-forward
@findex re-search-backward @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 @code{re-search-forward} and @code{re-search-backward}. You can
invoke these with @kbd{M-x}, or by way of incremental regexp search 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}}. 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. ...@@ -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 Searches in Emacs normally ignore the case of the text they are
searching through, if you specify the text in lower case. Thus, if searching through, if you specify the text in lower case. Thus, if
you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo} you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo}
are also considered a match. Regexps, and in particular character also match. Regexps, and in particular character sets, behave
sets, are included: @samp{[ab]} would match @samp{a} or @samp{A} or likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or
@samp{b} or @samp{B}.@refill @samp{B}.@refill
An upper-case letter anywhere in the incremental search string makes An upper-case letter anywhere in the incremental search string makes
the search case-sensitive. Thus, searching for @samp{Foo} does not find 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 ...@@ -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. each occurrence of the pattern and asks you whether to replace it.
The replace commands normally operate on the text from point to the 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 end of the buffer. When the region is active, they operate on it
region instead (@pxref{Mark}). The basic replace commands replace one instead (@pxref{Mark}). The basic replace commands replace one
@dfn{search string} (or regexp) with one @dfn{replacement string}. It @dfn{search string} (or regexp) with one @dfn{replacement string}. It
is possible to perform several replacements in parallel, using the is possible to perform several replacements in parallel, using the
command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}). 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. ...@@ -998,7 +1007,7 @@ activating the mark; use @kbd{C-u C-@key{SPC}} to move back there.
@xref{Mark Ring}. @xref{Mark Ring}.
A prefix argument restricts replacement to matches that are 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 @xref{Replacement and Case}, for details about case-sensitivity in
replace commands. replace commands.
...@@ -1128,10 +1137,8 @@ replacement is done without case conversion. ...@@ -1128,10 +1137,8 @@ replacement is done without case conversion.
@table @kbd @table @kbd
@item M-% @var{string} @key{RET} @var{newstring} @key{RET} @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}. Replace some occurrences of @var{string} with @var{newstring}.
@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET} @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}. Replace some matches for @var{regexp} with @var{newstring}.
@end table @end table
...@@ -1144,7 +1151,7 @@ occurrence and asks you whether to replace it. Aside from querying, ...@@ -1144,7 +1151,7 @@ occurrence and asks you whether to replace it. Aside from querying,
@code{query-replace} works just like @code{replace-string} @code{query-replace} works just like @code{replace-string}
(@pxref{Unconditional Replace}). In particular, it preserves case (@pxref{Unconditional Replace}). In particular, it preserves case
provided @code{case-replace} is non-@code{nil}, as it normally is 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. only occurrences that are bounded by word-delimiter characters.
@kindex C-M-% @kindex C-M-%
...@@ -1157,7 +1164,7 @@ like @code{query-replace}. ...@@ -1157,7 +1164,7 @@ like @code{query-replace}.
These commands highlight the current match using the face These commands highlight the current match using the face
@code{query-replace}. They highlight other matches using @code{query-replace}. They highlight other matches using
@code{lazy-highlight} just like incremental search (@pxref{Incremental @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 substituted replacement string for the current match in the
minibuffer. If you want to keep special sequences @samp{\&} and minibuffer. If you want to keep special sequences @samp{\&} and
@samp{\@var{n}} unexpanded, customize @samp{\@var{n}} unexpanded, customize
...@@ -1290,6 +1297,8 @@ matching that regexp. ...@@ -1290,6 +1297,8 @@ matching that regexp.
This command is just like @code{multi-isearch-buffers}, except it This command is just like @code{multi-isearch-buffers}, except it
performs an incremental regexp search. performs an incremental regexp search.
@cindex Occur mode
@cindex mode, Occur
@item M-x occur @item M-x occur
Prompt for a regexp, and display a list showing each line in the 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 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. ...@@ -1300,16 +1309,22 @@ displayed before and after each matching line.
@kindex RET @r{(Occur mode)} @kindex RET @r{(Occur mode)}
@kindex o @r{(Occur mode)} @kindex o @r{(Occur mode)}
@kindex C-o @r{(Occur mode)} @kindex C-o @r{(Occur mode)}
The buffer @samp{*Occur*} containing the output serves as a menu for In the @samp{*Occur*} buffer, you can click on each entry, or move
finding the occurrences in their original context. Click point there and type @key{RET}, to visit the corresponding position in
@kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position the buffer that was searched. @kbd{o} and @kbd{C-o} display the match
point there and type @key{RET}; this switches to the buffer that was in another window; @kbd{C-o} does not select it. Alternatively, you
searched and moves point to the original of the chosen occurrence. can use the @kbd{C-x `} (@code{next-error}) command to visit the
@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} occurrences one by one (@pxref{Compilation Mode}).
does not select it.
@cindex Occur Edit mode
After using @kbd{M-x occur}, you can use @code{next-error} to visit @cindex mode, Occur Edit
the occurrences found, one by one. @ref{Compilation Mode}. 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 @kindex M-s o
@item M-s o @item M-s o
...@@ -1317,9 +1332,6 @@ Run @code{occur} using the search string of the last incremental ...@@ -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 string search. You can also run @kbd{M-s o} when an incremental
search is active; this uses the current search string. 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 @item M-x multi-occur
This command is just like @code{occur}, except it is able to search 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 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. ...@@ -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 *** C-y in Isearch is now bound to isearch-yank-kill, instead of
isearch-yank-line. isearch-yank-line.
--- +++
*** M-y in Isearch is now bound to isearch-yank-pop, instead of *** M-y in Isearch is now bound to isearch-yank-pop, instead of
isearch-yank-kill. isearch-yank-kill.
+++ +++
...@@ -883,6 +883,7 @@ They are superseded by shift-select-mode enabled by default in 23.1. ...@@ -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 * New Modes and Packages in Emacs 24.1
+++
** Occur Edit mode applies edits made in *Occur* buffers to the ** Occur Edit mode applies edits made in *Occur* buffers to the
original buffers. It is bound to "e" in Occur mode. 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