comparison man/search.texi @ 52968:f785910734e8

(Scrolling During Incremental Search): Document a new scrolling facility in isearch mode.

52967:9cd8b1bd5ecc

occurrences of one string and replaces them with another, Emacs has a
more flexible replacement command called @code{query-replace}, which
asks interactively which occurrences to replace.

@menu
* Incremental Search::	   Search happens as you type the string.
* Nonincremental Search::  Specify entire string and then search.
* Word Search::		   Search for sequence of words.
* Regexp Search::	   Search for match for a regexp.
* Regexps::		   Syntax of regular expressions.
* Search Case::		   To ignore case while searching, or not.
* Replace::		   Search, and replace some or all matches.
* Other Repeating Search:: Operating on all matches for some regexp.
@end menu

@node Incremental Search, Nonincremental Search, Search, Search
@section Incremental Search

@vindex isearch-mode-map
  To customize the special characters that incremental search understands,
alter their bindings in the keymap @code{isearch-mode-map}.  For a list
of bindings, look at the documentation of @code{isearch-mode} with
@kbd{C-h f isearch-mode @key{RET}}.

@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

verify even very complex regexps.  (On displays that don't support
colors, Emacs blinks the cursor around the matched text, as it does
for matching parens.)
@end ignore

@node Search Case, Replace, Regexps, Search
@section Searching and Case

  Incremental 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

there is a default value which you can change as well.  @xref{Locals}.
This variable applies to nonincremental searches also, including those
performed by the replace commands (@pxref{Replace}) and the minibuffer
history matching commands (@pxref{Minibuffer History}).

@node Replace, Other Repeating Search, Search Case, Search
@section Replacement Commands
@cindex replacement
@cindex search-and-replace commands
@cindex string substitution
@cindex global substitution

replacement string.  It is possible to perform several replacements in
parallel using the command @code{expand-region-abbrevs}
(@pxref{Expanding Abbrevs}).

@menu
* Unconditional Replace::  Replacing all matches for a string.
* Regexp Replace::         Replacing all matches for a regexp.
* Replacement and Case::   How replacements preserve case of letters.
* Query Replace::          How to use querying.
@end menu

@node Unconditional Replace, Regexp Replace, Replace, Replace
@subsection Unconditional Replacement
@findex replace-string

52968:f785910734e8

occurrences of one string and replaces them with another, Emacs has a
more flexible replacement command called @code{query-replace}, which
asks interactively which occurrences to replace.

@menu
* Incremental Search::		Search happens as you type the string.
* Nonincremental Search::	Specify entire string and then search.
* Word Search::			Search for sequence of words.
* Regexp Search::		Search for match for a regexp.
* Regexps::			Syntax of regular expressions.
* Search Case::			To ignore case while searching, or not.
* Configuring Scrolling::	Scrolling within incremental search.
* Replace::			Search, and replace some or all matches.
* Other Repeating Search::	Operating on all matches for some regexp.
@end menu

@node Incremental Search, Nonincremental Search, Search, Search
@section Incremental Search

@vindex isearch-mode-map
  To customize the special characters that incremental search understands,
alter their bindings in the keymap @code{isearch-mode-map}.  For a list
of bindings, look at the documentation of @code{isearch-mode} with
@kbd{C-h f isearch-mode @key{RET}}.

@subsection Scrolling During Incremental Search

  Vertical scrolling during incremental search can be enabled by
setting the customizable variable @code{isearch-allow-scroll} to a
non-nil value.

  You can then use the vertical scroll-bar or certain keyboard
commands such as @kbd{@key{PRIOR}} (@code{scroll-down}),
@kbd{@key{NEXT}} (@code{scroll-up}) and @kbd{C-l} (@code{recenter})
within the search, thus letting you see more of the text near the
current match.  You must run these commands via their key sequences to
stay in the search - typing M-x @var{comand-name} will always
terminate a search.

  You can give prefix arguments to these commands in the usual way.
The current match cannot be scrolled out of the window - this is
intentional.

  Several other commands, such as @kbd{C-x 2}
(@code{split-window-vertically}) and @kbd{C-x ^}
(@code{enlarge-window}) which don't scroll the window, are
nevertheless made available under this rubric, since they are likewise
handy during a search.

  For a list of commands which are configured as scrolling commands by
default and instructions on how thus to configure other commands, see
@ref{Configuring Scrolling}.

@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

verify even very complex regexps.  (On displays that don't support
colors, Emacs blinks the cursor around the matched text, as it does
for matching parens.)
@end ignore

@node Search Case, Configuring Scrolling, Regexps, Search
@section Searching and Case

  Incremental 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

there is a default value which you can change as well.  @xref{Locals}.
This variable applies to nonincremental searches also, including those
performed by the replace commands (@pxref{Replace}) and the minibuffer
history matching commands (@pxref{Minibuffer History}).

@node Configuring Scrolling, Replace, Search Case, Search
@section Configuring Scrolling
@cindex scrolling in incremental search
@vindex isearch-allow-scroll

Scrolling, etc., during incremental search is enabled by setting the
customizable variable @code{isearch-allow-scroll} to a non-nil value.

@c See Subject: Info file:  How do I get an itemized list without blank lines?
@c Date: Sat, 12 Apr 2003 09:45:31 +0000  in gnu.emacs.help
@subsection Standard scrolling commands
Here is the list of commands which are configured by default to be
``scrolling'' commands in an incremental search, together with their
usual bindings:
@subsubsection Commands which scroll the window:
@table @asis
@item @code{scroll-bar-toolkit-scroll} (@kbd{@key{vertical-scroll-bar}@key{mouse-1}} in X-Windows)
@itemx @code{mac-handle-scroll-bar-event} (@kbd{@key{vertical-scroll-bar}@key{mouse-1}} on a Mac)
@itemx @code{w32-handle-scroll-bar-event} (@kbd{@key{vertical-scroll-bar}@key{mouse-1}} in MS-Windows)
@item @code{recenter} (@kbd{C-l}) @xref{Scrolling}.
@itemx @code{reposition-window} (@kbd{C-M-l}) @xref{Scrolling}.
@itemx @code{scroll-up} (@kbd{@key{NEXT}}) @xref{Scrolling}.
@itemx @code{scroll-down} (@kbd{@key{PRIOR}}) @xref{Scrolling}.
@end table

@subsubsection Commands which act on the other window:
@table @asis
@item @code{list-buffers} (@kbd{C-x C-b}) @xref{List Buffers}.
@itemx @code{scroll-other-window} (@kbd{C-M-v}) @xref{Other Window}.
@itemx @code{scroll-other-window-down} (@kbd{C-M-S-v}) @xref{Other Window}.
@itemx @code{beginning-of-buffer-other-window} (@kbd{M-@key{home}})
@itemx @code{end-of-buffer-other-window} (@kbd{M-@key{end}})
@end table

@subsubsection Commands which change the window layout:
@table @asis
@item @code{delete-other-windows} (@kbd{C-x 1}) @xref{Change Window}.
@itemx @code{balance-windows} (@kbd{C-x +}) @xref{Change Window}.
@itemx @code{split-window-vertically} (@kbd{C-x 2}) @xref{Split Window}.
@itemx @code{enlarge-window} (@kbd{C-x ^}) @xref{Change Window}.
@end table

@subsection Configuring other commands as scrolling commands
To do this, set a command's isearch-scroll property to the value t.
For example:

@example
@code{(put 'my-command 'isearch-scroll t)}
@end example

You should only thus configure commands which are ``safe'': i.e., they
won't leave emacs in an inconsistent state when executed within a
search - that is to say, the following things may be changed by a
command only temporarily, and must be restored before the command
finishes:

@enumerate
@item
Point.
@item
The buffer contents.
@item
The selected window and selected frame.
@item
The current match-data @xref{Match Data,,,elisp}.
@end enumerate

Additionally, the command must not delete the current window and must
not itself attempt an incremental search.  It may, however, change the
window's size, or create or delete other windows and frames.

Note that an attempt by a command to scroll the text
@emph{horizontally} won't work, although it will do no harm - any such
scrolling will be overriden and nullified by the display code.

@node Replace, Other Repeating Search, Configuring Scrolling, Search
@section Replacement Commands
@cindex replacement
@cindex search-and-replace commands
@cindex string substitution
@cindex global substitution

replacement string.  It is possible to perform several replacements in
parallel using the command @code{expand-region-abbrevs}
(@pxref{Expanding Abbrevs}).

@menu
* Unconditional Replace::	Replacing all matches for a string.
* Regexp Replace::		Replacing all matches for a regexp.
* Replacement and Case::	How replacements preserve case of letters.
* Query Replace::		How to use querying.
@end menu

@node Unconditional Replace, Regexp Replace, Replace, Replace
@subsection Unconditional Replacement
@findex replace-string