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.
This commit is contained in:
Chong Yidong
parent
939db9ac78
commit
5abc31ef18
4 changed files with 105 additions and 84 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,3 +1,11 @@
|
|||
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}.
|
||||
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}).
|
||||
|
||||
@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.)
|
||||
@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.)
|
||||
|
||||
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.
|
||||
@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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
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}).
|
||||
|
||||
After using @kbd{M-x occur}, you can use @code{next-error} to visit
|
||||
the occurrences found, one by one. @ref{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
|
||||
|
|
|
|||
3
etc/NEWS
3
etc/NEWS
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue