# HG changeset patch # User Eli Zaretskii # Date 1067706360 0 # Node ID f785910734e87220c06f18b56a86cfa6ae6a4c69 # Parent 9cd8b1bd5ecc5edb6c0c3d10c2c480b752102a8d (Scrolling During Incremental Search): Document a new scrolling facility in isearch mode. diff -r 9cd8b1bd5ecc -r f785910734e8 man/search.texi --- a/man/search.texi Sat Nov 01 17:02:32 2003 +0000 +++ b/man/search.texi Sat Nov 01 17:06:00 2003 +0000 @@ -19,14 +19,15 @@ 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. +* 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 @@ -226,6 +227,34 @@ 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 @@ -762,7 +791,7 @@ for matching parens.) @end ignore -@node Search Case, Replace, Regexps, Search +@node Search Case, Configuring Scrolling, Regexps, Search @section Searching and Case Incremental searches in Emacs normally ignore the case of the text @@ -792,7 +821,82 @@ performed by the replace commands (@pxref{Replace}) and the minibuffer history matching commands (@pxref{Minibuffer History}). -@node Replace, Other Repeating Search, Search Case, Search +@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 @@ -814,10 +918,10 @@ (@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. +* 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