1 This is ../info/xemacs.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Rectangles, Next: Registers, Prev: Accumulating Text, Up: Top
38 The rectangle commands affect rectangular areas of text: all
39 characters between a certain pair of columns, in a certain range of
40 lines. Commands are provided to kill rectangles, yank killed
41 rectangles, clear them out, or delete them. Rectangle commands are
42 useful with text in multicolumnar formats, like code with comments at
43 the right, or for changing text into or out of such formats.
45 To specify the rectangle a command should work on, put the mark at
46 one corner and point at the opposite corner. The specified rectangle is
47 called the "region-rectangle" because it is controlled about the same
48 way the region is controlled. Remember that a given combination of
49 point and mark values can be interpreted either as specifying a region
50 or as specifying a rectangle; it is up to the command that uses them to
51 choose the interpretation.
53 `M-x delete-rectangle'
54 Delete the text of the region-rectangle, moving any following text
55 on each line leftward to the left edge of the region-rectangle.
58 Similar, but also save the contents of the region-rectangle as the
59 "last killed rectangle".
62 Yank the last killed rectangle with its upper left corner at point.
65 Insert blank space to fill the space of the region-rectangle. The
66 previous contents of the region-rectangle are pushed rightward.
69 Clear the region-rectangle by replacing its contents with spaces.
71 The rectangle operations fall into two classes: commands deleting and
72 moving rectangles, and commands for blank rectangles.
74 There are two ways to get rid of the text in a rectangle: you can
75 discard the text (delete it) or save it as the "last killed" rectangle.
76 The commands for these two ways are `M-x delete-rectangle' and `M-x
77 kill-rectangle'. In either case, the portion of each line that falls
78 inside the rectangle's boundaries is deleted, causing following text
79 (if any) on the line to move left.
81 Note that "killing" a rectangle is not killing in the usual sense;
82 the rectangle is not stored in the kill ring, but in a special place
83 that only records the most recently killed rectangle (that is, does not
84 append to a killed rectangle). Different yank commands have to be used
85 and only one rectangle is stored, because yanking a rectangle is quite
86 different from yanking linear text and yank-popping commands are
87 difficult to make sense of.
89 Inserting a rectangle is the opposite of deleting one. You specify
90 where to put the upper left corner by putting point there. The
91 rectangle's first line is inserted at point, the rectangle's second line
92 is inserted at a point one line vertically down, and so on. The number
93 of lines affected is determined by the height of the saved rectangle.
95 To insert the last killed rectangle, type `M-x yank-rectangle'.
96 This can be used to convert single-column lists into double-column
97 lists; kill the second half of the list as a rectangle and then yank it
98 beside the first line of the list.
100 There are two commands for working with blank rectangles: `M-x
101 clear-rectangle' erases existing text, and `M-x open-rectangle' inserts
102 a blank rectangle. Clearing a rectangle is equivalent to deleting it
103 and then inserting a blank rectangle of the same size.
105 Rectangles can also be copied into and out of registers. *Note
106 Rectangle Registers: RegRect.
109 File: xemacs.info, Node: Registers, Next: Display, Prev: Rectangles, Up: Top
114 XEmacs "registers" are places in which you can save text or
115 positions for later use. Once you save text or a rectangle in a
116 register, you can copy it into the buffer once or many times; a position
117 saved in a register is used by moving point to that position.
118 Rectangles can also be copied into and out of registers (*note
121 Each register has a name which is a single character. A register can
122 store a piece of text, a rectangle, a position, a window configuration,
123 or a file name, but only one thing at any given time. Whatever you
124 store in a register remains there until you store something else in that
125 register. To see what a register R contains, use `M-x view-register'.
127 `M-x view-register <RET> R'
128 Display a description of what register R contains.
130 `M-x view-register' reads a register name as an argument and then
131 displays the contents of the specified register.
135 * Position: RegPos. Saving positions in registers.
136 * Text: RegText. Saving text in registers.
137 * Rectangle: RegRect. Saving rectangles in registers.
138 * Configurations: RegConfig. Saving window configurations in registers.
139 * Files: RegFiles. File names in registers.
140 * Numbers: RegNumbers. Numbers in registers.
141 * Bookmarks:: Bookmarks are like registers, but persistent.
144 File: xemacs.info, Node: RegPos, Next: RegText, Prev: Registers, Up: Registers
146 Saving Positions in Registers
147 =============================
149 Saving a position records a place in a buffer so that you can move
150 back there later. Moving to a saved position switches to that buffer
151 and moves point to that place in it.
154 Save position of point in register R (`point-to-register').
157 Jump to the position saved in register R (`jump-to-register').
159 To save the current position of point in a register, choose a name R
160 and type `C-x r <SPC> R'. The register R retains the position thus
161 saved until you store something else in that register.
163 The command `C-x r j R' moves point to the position recorded in
164 register R. The register is not affected; it continues to record the
165 same location. You can jump to the same position using the same
166 register as often as you want.
168 If you use `C-x r j' to go to a saved position, but the buffer it
169 was saved from has been killed, `C-x r j' tries to create the buffer
170 again by visiting the same file. Of course, this works only for buffers
171 that were visiting files.
174 File: xemacs.info, Node: RegText, Next: RegRect, Prev: RegPos, Up: Registers
176 Saving Text in Registers
177 ========================
179 When you want to insert a copy of the same piece of text many times,
180 it can be impractical to use the kill ring, since each subsequent kill
181 moves the piece of text further down on the ring. It becomes hard to
182 keep track of the argument needed to retrieve the same text with `C-y'.
183 An alternative is to store the text in a register with `C-x r s'
184 (`copy-to-register') and then retrieve it with `C-x r i'
188 Copy region into register R (`copy-to-register').
192 Insert text contents of register R (`insert-register').
194 `C-x r s R' stores a copy of the text of the region into the
195 register named R. Given a numeric argument, `C-x r s R' deletes the
196 text from the buffer as well.
198 `C-x r i R' inserts the text from register R in the buffer. By
199 default it leaves point before the text and places the mark after it.
200 With a numeric argument (`C-u'), it puts point after the text and the
204 File: xemacs.info, Node: RegRect, Next: RegConfig, Prev: RegText, Up: Registers
206 Saving Rectangles in Registers
207 ==============================
209 A register can contain a rectangle instead of lines of text. The
210 rectangle is represented as a list of strings. *Note Rectangles::, for
211 basic information on rectangles and how to specify rectangles in a
215 Copy the region-rectangle into register R
216 (`copy-rectangle-to-register'). With a numeric argument, delete it
221 Insert the rectangle stored in register R (if it contains a
222 rectangle) (`insert-register').
224 The `C-x r i R' command inserts linear text if the register
225 contains that, or inserts a rectangle if the register contains one.
227 See also the command `sort-columns', which you can think of as
228 sorting a rectangle. *Note Sorting::.
231 File: xemacs.info, Node: RegConfig, Next: RegNumbers, Prev: RegRect, Up: Registers
233 Saving Window Configurations in Registers
234 =========================================
236 You can save the window configuration of the selected frame in a
237 register, or even the configuration of all windows in all frames, and
238 restore the configuration later.
241 Save the state of the selected frame's windows in register R
242 (`window-configuration-to-register').
244 `M-x frame-configuration-to-register <RET> R'
245 Save the state of all frames, including all their windows, in
246 register R (`frame-configuration-to-register').
248 Use `C-x r j R' to restore a window or frame configuration. This is
249 the same command used to restore a cursor position. When you restore a
250 frame configuration, any existing frames not included in the
251 configuration become invisible. If you wish to delete these frames
252 instead, use `C-u C-x r j R'.
255 File: xemacs.info, Node: RegNumbers, Next: RegFiles, Prev: RegConfig, Up: Registers
257 Keeping Numbers in Registers
258 ============================
260 There are commands to store a number in a register, to insert the
261 number in the buffer in decimal, and to increment it. These commands
262 can be useful in keyboard macros (*note Keyboard Macros::).
264 `C-u NUMBER C-x r n REG'
265 Store NUMBER into register REG (`number-to-register').
267 `C-u NUMBER C-x r + REG'
268 Increment the number in register REG by NUMBER
269 (`increment-register').
272 Insert the number from register REG into the buffer.
274 `C-x r g' is the same command used to insert any other sort of
275 register contents into the buffer.
278 File: xemacs.info, Node: RegFiles, Next: Bookmarks, Prev: RegNumbers, Up: Registers
280 Keeping File Names in Registers
281 ===============================
283 If you visit certain file names frequently, you can visit them more
284 conveniently if you put their names in registers. Here's the Lisp code
285 used to put a file name in a register:
287 (set-register ?R '(file . NAME))
291 (set-register ?z '(file . "/usr/src/xemacs/src/ChangeLog"))
293 puts the file name shown in register `z'.
295 To visit the file whose name is in register R, type `C-x r j R'.
296 (This is the same command used to jump to a position or restore a frame
300 File: xemacs.info, Node: Bookmarks, Prev: RegFiles, Up: Registers
305 "Bookmarks" are somewhat like registers in that they record
306 positions you can jump to. Unlike registers, they have long names, and
307 they persist automatically from one Emacs session to the next. The
308 prototypical use of bookmarks is to record "where you were reading" in
311 Note: bookmark.el is distributed in edit-utils package. You need to
312 install that to use bookmark facility (*note Packages::).
315 Set the bookmark for the visited file, at point.
317 `C-x r m BOOKMARK <RET>'
318 Set the bookmark named BOOKMARK at point (`bookmark-set').
320 `C-x r b BOOKMARK <RET>'
321 Jump to the bookmark named BOOKMARK (`bookmark-jump').
324 List all bookmarks (`list-bookmarks').
327 Save all the current bookmark values in the default bookmark file.
329 The prototypical use for bookmarks is to record one current position
330 in each of several files. So the command `C-x r m', which sets a
331 bookmark, uses the visited file name as the default for the bookmark
332 name. If you name each bookmark after the file it points to, then you
333 can conveniently revisit any of those files with `C-x r b', and move to
334 the position of the bookmark at the same time.
336 To display a list of all your bookmarks in a separate buffer, type
337 `C-x r l' (`list-bookmarks'). If you switch to that buffer, you can
338 use it to edit your bookmark definitions or annotate the bookmarks.
339 Type `C-h m' in that buffer for more information about its special
342 When you kill XEmacs, XEmacs offers to save your bookmark values in
343 your default bookmark file, `~/.emacs.bmk', if you have changed any
344 bookmark values. You can also save the bookmarks at any time with the
345 `M-x bookmark-save' command. The bookmark commands load your default
346 bookmark file automatically. This saving and loading is how bookmarks
347 persist from one XEmacs session to the next.
349 If you set the variable `bookmark-save-flag' to 1, then each command
350 that sets a bookmark will also save your bookmarks; this way, you don't
351 lose any bookmark values even if XEmacs crashes. (The value, if a
352 number, says how many bookmark modifications should go by between
355 Bookmark position values are saved with surrounding context, so that
356 `bookmark-jump' can find the proper position even if the file is
357 modified slightly. The variable `bookmark-search-size' says how many
358 characters of context to record, on each side of the bookmark's
361 Here are some additional commands for working with bookmarks:
363 `M-x bookmark-load <RET> FILENAME <RET>'
364 Load a file named FILENAME that contains a list of bookmark
365 values. You can use this command, as well as `bookmark-write', to
366 work with other files of bookmark values in addition to your
367 default bookmark file.
369 `M-x bookmark-write <RET> FILENAME <RET>'
370 Save all the current bookmark values in the file FILENAME.
372 `M-x bookmark-delete <RET> BOOKMARK <RET>'
373 Delete the bookmark named BOOKMARK.
375 `M-x bookmark-insert-location <RET> BOOKMARK <RET>'
376 Insert in the buffer the name of the file that bookmark BOOKMARK
379 `M-x bookmark-insert <RET> BOOKMARK <RET>'
380 Insert in the buffer the _contents_ of the file that bookmark
384 File: xemacs.info, Node: Display, Next: Search, Prev: Registers, Up: Top
386 Controlling the Display
387 ***********************
389 Since only part of a large buffer fits in the window, XEmacs tries
390 to show the part that is likely to be interesting. The display control
391 commands allow you to specify which part of the text you want to see.
394 Clear frame and redisplay, scrolling the selected window to center
395 point vertically within it (`recenter').
400 Scroll forward (a windowful or a specified number of lines)
401 (`scroll-up'). On most X keyboards, you can get this
402 functionality using the key labelled `Page Down', which generates
403 either `next' or `pgdn'.
408 Scroll backward (`scroll-down'). On most X keyboards, you can get
409 this functionality using the key labelled `Page Up', which
410 generates either `prior' or `pgup'.
413 Scroll so point is on line ARG (`recenter').
418 Scroll text in current window to the left (`scroll-left').
423 Scroll to the right (`scroll-right').
426 Make deeply indented lines invisible (`set-selective-display').
430 * Scrolling:: Moving text up and down in a window.
431 * Horizontal Scrolling:: Moving text left and right in a window.
432 * Selective Display:: Hiding lines with lots of indentation.
433 * Display Vars:: Information on variables for customizing display.
436 File: xemacs.info, Node: Scrolling, Next: Horizontal Scrolling, Prev: Display, Up: Display
441 If a buffer contains text that is too large to fit entirely within
442 the window that is displaying the buffer, XEmacs shows a contiguous
443 section of the text. The section shown always contains point.
445 "Scrolling" means moving text up or down in the window so that
446 different parts of the text are visible. Scrolling forward means that
447 text moves up, and new text appears at the bottom. Scrolling backward
448 moves text down and new text appears at the top.
450 Scrolling happens automatically if you move point past the bottom or
451 top of the window. You can also explicitly request scrolling with the
452 commands in this section.
455 Clear frame and redisplay, scrolling the selected window to center
456 point vertically within it (`recenter').
461 Scroll forward (a windowful or a specified number of lines)
467 Scroll backward (`scroll-down').
470 Scroll so point is on line ARG (`recenter').
472 The most basic scrolling command is `C-l' (`recenter') with no
473 argument. It clears the entire frame and redisplays all windows. In
474 addition, it scrolls the selected window so that point is halfway down
475 from the top of the window.
477 The scrolling commands `C-v' and `M-v' let you move all the text in
478 the window up or down a few lines. `C-v' (`scroll-up') with an
479 argument shows you that many more lines at the bottom of the window,
480 moving the text and point up together as `C-l' might. `C-v' with a
481 negative argument shows you more lines at the top of the window.
482 `Meta-v' (`scroll-down') is like `C-v', but moves in the opposite
485 To read the buffer a windowful at a time, use `C-v' with no
486 argument. `C-v' takes the last two lines at the bottom of the window
487 and puts them at the top, followed by nearly a whole windowful of lines
488 not previously visible. Point moves to the new top of the window if it
489 was in the text scrolled off the top. `M-v' with no argument moves
490 backward with similar overlap. The number of lines of overlap across a
491 `C-v' or `M-v' is controlled by the variable
492 `next-screen-context-lines'; by default, it is two.
494 Another way to scroll is using `C-l' with a numeric argument. `C-l'
495 does not clear the frame when given an argument; it only scrolls the
496 selected window. With a positive argument N, `C-l' repositions text to
497 put point N lines down from the top. An argument of zero puts point on
498 the very top line. Point does not move with respect to the text;
499 rather, the text and point move rigidly on the frame. `C-l' with a
500 negative argument puts point that many lines from the bottom of the
501 window. For example, `C-u - 1 C-l' puts point on the bottom line, and
502 `C-u - 5 C-l' puts it five lines from the bottom. Just `C-u' as
503 argument, as in `C-u C-l', scrolls point to the center of the frame.
505 Scrolling happens automatically if point has moved out of the visible
506 portion of the text when it is time to display. Usually scrolling is
507 done to put point vertically centered within the window. However, if
508 the variable `scroll-step' has a non-zero value, an attempt is made to
509 scroll the buffer by that many lines; if that is enough to bring point
510 back into visibility, that is what happens.
512 Scrolling happens automatically if point has moved out of the visible
513 portion of the text when it is time to display. Usually scrolling is
514 done to put point vertically centered within the window. However, if
515 the variable `scroll-step' has a non-zero value, an attempt is made to
516 scroll the buffer by that many lines; if that is enough to bring point
517 back into visibility, that is what happens.
519 If you set `scroll-step' to a small value because you want to use
520 arrow keys to scroll the screen without recentering, the redisplay
521 preemption will likely make XEmacs keep recentering the screen when
522 scrolling fast, regardless of `scroll-step'. To prevent this, set
523 `scroll-conservatively' to a small value, which will have the result of
524 overriding the redisplay preemption.
527 File: xemacs.info, Node: Horizontal Scrolling, Prev: Scrolling, Up: Display
533 Scroll text in current window to the left (`scroll-left').
536 Scroll to the right (`scroll-right').
538 The text in a window can also be scrolled horizontally. This means
539 that each line of text is shifted sideways in the window, and one or
540 more characters at the beginning of each line are not displayed at all.
541 When a window has been scrolled horizontally in this way, text lines
542 are truncated rather than continued (*note Continuation Lines::), with
543 a `$' appearing in the first column when there is text truncated to the
544 left, and in the last column when there is text truncated to the right.
546 The command `C-x <' (`scroll-left') scrolls the selected window to
547 the left by N columns with argument N. With no argument, it scrolls by
548 almost the full width of the window (two columns less, to be precise).
549 `C-x >' (`scroll-right') scrolls similarly to the right. The window
550 cannot be scrolled any farther to the right once it is displaying
551 normally (with each line starting at the window's left margin);
552 attempting to do so has no effect.
555 File: xemacs.info, Node: Selective Display, Next: Display Vars, Prev: Display, Up: Display
560 XEmacs can hide lines indented more than a certain number of columns
561 (you specify how many columns). This allows you to get an overview of
564 To hide lines, type `C-x $' (`set-selective-display') with a numeric
565 argument N. (*Note Arguments::, for information on giving the
566 argument.) Lines with at least N columns of indentation disappear from
567 the screen. The only indication of their presence are three dots
568 (`...'), which appear at the end of each visible line that is followed
569 by one or more invisible ones.
571 The invisible lines are still present in the buffer, and most editing
572 commands see them as usual, so it is very easy to put point in the
573 middle of invisible text. When this happens, the cursor appears at the
574 end of the previous line, after the three dots. If point is at the end
575 of the visible line, before the newline that ends it, the cursor
576 appears before the three dots.
578 The commands `C-n' and `C-p' move across the invisible lines as if
581 To make everything visible again, type `C-x $' with no argument.
584 File: xemacs.info, Node: Display Vars, Prev: Selective Display, Up: Display
586 Variables Controlling Display
587 =============================
589 This section contains information for customization only. Beginning
590 users should skip it.
592 When you reenter XEmacs after suspending, XEmacs normally clears the
593 screen and redraws the entire display. On some terminals with more than
594 one page of memory, it is possible to arrange the termcap entry so that
595 the `ti' and `te' strings (output to the terminal when XEmacs is
596 entered and exited, respectively) switch between pages of memory so as
597 to use one page for XEmacs and another page for other output. In that
598 case, you might want to set the variable `no-redraw-on-reenter' to
599 non-`nil' so that XEmacs will assume, when resumed, that the screen
600 page it is using still contains what XEmacs last wrote there.
602 The variable `echo-keystrokes' controls the echoing of
603 multi-character keys; its value is the number of seconds of pause
604 required to cause echoing to start, or zero, meaning don't echo at all.
607 If the variable `ctl-arrow' is `nil', control characters in the
608 buffer are displayed with octal escape sequences, all except newline and
609 tab. If its value is `t', then control characters will be printed with
610 an up-arrow, for example `^A'.
612 If its value is not `t' and not `nil', then characters whose code is
613 greater than 160 (that is, the space character (32) with its high bit
614 set) will be assumed to be printable, and will be displayed without
615 alteration. This is the default when running under X Windows, since
616 XEmacs assumes an ISO/8859-1 character set (also known as "Latin1").
617 The `ctl-arrow' variable may also be set to an integer, in which case
618 all characters whose codes are greater than or equal to that value will
619 be assumed to be printable.
621 Altering the value of `ctl-arrow' makes it local to the current
622 buffer; until that time, the default value is in effect. *Note
625 Normally, a tab character in the buffer is displayed as whitespace
626 which extends to the next display tab stop position, and display tab
627 stops come at intervals equal to eight spaces. The number of spaces
628 per tab is controlled by the variable `tab-width', which is made local
629 by changing it, just like `ctl-arrow'. Note that how the tab character
630 in the buffer is displayed has nothing to do with the definition of
633 If you set the variable `selective-display-ellipses' to `nil', the
634 three dots at the end of a line that precedes invisible lines do not
635 appear. There is no visible indication of the invisible lines. This
636 variable becomes local automatically when set.
639 File: xemacs.info, Node: Search, Next: Fixit, Prev: Display, Up: Top
641 Searching and Replacement
642 *************************
644 Like other editors, Emacs has commands for searching for occurrences
645 of a string. The principal search command is unusual in that it is
646 "incremental": it begins to search before you have finished typing the
647 search string. There are also non-incremental search commands more like
648 those of other editors.
650 Besides the usual `replace-string' command that finds all
651 occurrences of one string and replaces them with another, Emacs has a
652 fancy replacement command called `query-replace' which asks
653 interactively which occurrences to replace.
657 * Incremental Search:: Search happens as you type the string.
658 * Non-Incremental Search:: Specify entire string and then search.
659 * Word Search:: Search for sequence of words.
660 * Regexp Search:: Search for match for a regexp.
661 * Regexps:: Syntax of regular expressions.
662 * Search Case:: To ignore case while searching, or not.
663 * Replace:: Search, and replace some or all matches.
664 * Other Repeating Search:: Operating on all matches for some regexp.
667 File: xemacs.info, Node: Incremental Search, Next: Non-Incremental Search, Prev: Search, Up: Search
672 An incremental search begins searching as soon as you type the first
673 character of the search string. As you type in the search string, Emacs
674 shows you where the string (as you have typed it so far) is found.
675 When you have typed enough characters to identify the place you want,
676 you can stop. Depending on what you do next, you may or may not need to
677 terminate the search explicitly with a <RET>.
680 Incremental search forward (`isearch-forward').
683 Incremental search backward (`isearch-backward').
685 `C-s' starts an incremental search. `C-s' reads characters from the
686 keyboard and positions the cursor at the first occurrence of the
687 characters that you have typed. If you type `C-s' and then `F', the
688 cursor moves right after the first `F'. Type an `O', and see the
689 cursor move to after the first `FO'. After another `O', the cursor is
690 after the first `FOO' after the place where you started the search.
691 Meanwhile, the search string `FOO' has been echoed in the echo area.
693 The echo area display ends with three dots when actual searching is
694 going on. When search is waiting for more input, the three dots are
695 removed. (On slow terminals, the three dots are not displayed.)
697 If you make a mistake in typing the search string, you can erase
698 characters with <DEL>. Each <DEL> cancels the last character of the
699 search string. This does not happen until Emacs is ready to read
700 another input character; first it must either find, or fail to find,
701 the character you want to erase. If you do not want to wait for this
702 to happen, use `C-g' as described below.
704 When you are satisfied with the place you have reached, you can type
705 <RET> (or <C-m>), which stops searching, leaving the cursor where the
706 search brought it. Any command not specially meaningful in searches
707 also stops the search and is then executed. Thus, typing `C-a' exits
708 the search and then moves to the beginning of the line. <RET> is
709 necessary only if the next command you want to type is a printing
710 character, <DEL>, <ESC>, or another control character that is special
711 within searches (`C-q', `C-w', `C-r', `C-s', or `C-y').
713 Sometimes you search for `FOO' and find it, but were actually
714 looking for a different occurrence of it. To move to the next
715 occurrence of the search string, type another `C-s'. Do this as often
716 as necessary. If you overshoot, you can cancel some `C-s' characters
719 After you exit a search, you can search for the same string again by
720 typing just `C-s C-s': the first `C-s' is the key that invokes
721 incremental search, and the second `C-s' means "search again".
723 If the specified string is not found at all, the echo area displays
724 the text `Failing I-Search'. The cursor is after the place where Emacs
725 found as much of your string as it could. Thus, if you search for
726 `FOOT', and there is no `FOOT', the cursor may be after the `FOO' in
727 `FOOL'. At this point there are several things you can do. If you
728 mistyped the search string, correct it. If you like the place you have
729 found, you can type <RET> or some other Emacs command to "accept what
730 the search offered". Or you can type `C-g', which removes from the
731 search string the characters that could not be found (the `T' in
732 `FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second
733 `C-g' at that point cancels the search entirely, returning point to
734 where it was when the search started.
736 If a search is failing and you ask to repeat it by typing another
737 `C-s', it starts again from the beginning of the buffer. Repeating a
738 failing backward search with `C-r' starts again from the end. This is
739 called "wrapping around". `Wrapped' appears in the search prompt once
742 The `C-g' "quit" character does special things during searches; just
743 what it does depends on the status of the search. If the search has
744 found what you specified and is waiting for input, `C-g' cancels the
745 entire search. The cursor moves back to where you started the search.
746 If `C-g' is typed when there are characters in the search string that
747 have not been found--because Emacs is still searching for them, or
748 because it has failed to find them--then the search string characters
749 which have not been found are discarded from the search string. The
750 search is now successful and waiting for more input, so a second `C-g'
751 cancels the entire search.
753 To search for a control character such as `C-s' or <DEL> or <ESC>,
754 you must quote it by typing `C-q' first. This function of `C-q' is
755 analogous to its meaning as an Emacs command: it causes the following
756 character to be treated the way a graphic character would normally be
757 treated in the same context.
759 To search backwards, you can use `C-r' instead of `C-s' to start the
760 search; `C-r' is the key that runs the command (`isearch-backward') to
761 search backward. You can also use `C-r' to change from searching
762 forward to searching backwards. Do this if a search fails because the
763 place you started was too far down in the file. Repeated `C-r' keeps
764 looking for more occurrences backwards. `C-s' starts going forward
765 again. You can cancel `C-r' in a search with <DEL>.
767 The characters `C-y' and `C-w' can be used in incremental search to
768 grab text from the buffer into the search string. This makes it
769 convenient to search for another occurrence of text at point. `C-w'
770 copies the word after point as part of the search string, advancing
771 point over that word. Another `C-s' to repeat the search will then
772 search for a string including that word. `C-y' is similar to `C-w' but
773 copies the rest of the current line into the search string.
775 The characters `M-p' and `M-n' can be used in an incremental search
776 to recall things which you have searched for in the past. A list of
777 the last 16 things you have searched for is retained, and `M-p' and
778 `M-n' let you cycle through that ring.
780 The character `M-<TAB>' does completion on the elements in the
781 search history ring. For example, if you know that you have recently
782 searched for the string `POTATOE', you could type `C-s P O M-<TAB>'.
783 If you had searched for other strings beginning with `PO' then you
784 would be shown a list of them, and would need to type more to select
787 You can change any of the special characters in incremental search
788 via the normal keybinding mechanism: simply add a binding to the
789 `isearch-mode-map'. For example, to make the character `C-b' mean
790 "search backwards" while in isearch-mode, do this:
792 (define-key isearch-mode-map "\C-b" 'isearch-repeat-backward)
794 These are the default bindings of isearch-mode:
797 Delete a character from the incremental search string
798 (`isearch-delete-char').
801 Exit incremental search (`isearch-exit').
804 Quote special characters for incremental search
805 (`isearch-quote-char').
808 Repeat incremental search forward (`isearch-repeat-forward').
811 Repeat incremental search backward (`isearch-repeat-backward').
814 Pull rest of line from buffer into search string
815 (`isearch-yank-line').
818 Pull next word from buffer into search string
819 (`isearch-yank-word').
822 Cancels input back to what has been found successfully, or aborts
823 the isearch (`isearch-abort').
826 Recall the previous element in the isearch history ring
827 (`isearch-ring-retreat').
830 Recall the next element in the isearch history ring
831 (`isearch-ring-advance').
834 Do completion on the elements in the isearch history ring
835 (`isearch-complete').
837 Any other character which is normally inserted into a buffer when
838 typed is automatically added to the search string in isearch-mode.
840 Slow Terminal Incremental Search
841 --------------------------------
843 Incremental search on a slow terminal uses a modified style of
844 display that is designed to take less time. Instead of redisplaying
845 the buffer at each place the search gets to, it creates a new
846 single-line window and uses that to display the line the search has
847 found. The single-line window appears as soon as point gets outside of
848 the text that is already on the screen.
850 When the search is terminated, the single-line window is removed.
851 Only at this time the window in which the search was done is
852 redisplayed to show its new value of point.
854 The three dots at the end of the search string, normally used to
855 indicate that searching is going on, are not displayed in slow style
858 The slow terminal style of display is used when the terminal baud
859 rate is less than or equal to the value of the variable
860 `search-slow-speed', initially 1200.
862 The number of lines to use in slow terminal search display is
863 controlled by the variable `search-slow-window-lines'. Its normal
867 File: xemacs.info, Node: Non-Incremental Search, Next: Word Search, Prev: Incremental Search, Up: Search
869 Non-Incremental Search
870 ======================
872 Emacs also has conventional non-incremental search commands, which
873 require you type the entire search string before searching begins.
875 `C-s <RET> STRING <RET>'
878 `C-r <RET> STRING <RET>'
879 Search backward for STRING.
881 To do a non-incremental search, first type `C-s <RET>' (or `C-s
882 C-m'). This enters the minibuffer to read the search string.
883 Terminate the string with <RET> to start the search. If the string is
884 not found, the search command gets an error.
886 By default, `C-s' invokes incremental search, but if you give it an
887 empty argument, which would otherwise be useless, it invokes
888 non-incremental search. Therefore, `C-s <RET>' invokes non-incremental
889 search. `C-r <RET>' also works this way.
891 Forward and backward non-incremental searches are implemented by the
892 commands `search-forward' and `search-backward'. You can bind these
893 commands to keys. The reason that incremental search is programmed to
894 invoke them as well is that `C-s <RET>' is the traditional sequence of
895 characters used in Emacs to invoke non-incremental search.
897 Non-incremental searches performed using `C-s <RET>' do not call
898 `search-forward' right away. They first check if the next character is
899 `C-w', which requests a word search. *Note Word Search::.
902 File: xemacs.info, Node: Word Search, Next: Regexp Search, Prev: Non-Incremental Search, Up: Search
907 Word search looks for a sequence of words without regard to how the
908 words are separated. More precisely, you type a string of many words,
909 using single spaces to separate them, and the string is found even if
910 there are multiple spaces, newlines or other punctuation between the
913 Word search is useful in editing documents formatted by text
914 formatters. If you edit while looking at the printed, formatted
915 version, you can't tell where the line breaks are in the source file.
916 Word search, allows you to search without having to know the line
919 `C-s <RET> C-w WORDS <RET>'
920 Search for WORDS, ignoring differences in punctuation.
922 `C-r <RET> C-w WORDS <RET>'
923 Search backward for WORDS, ignoring differences in punctuation.
925 Word search is a special case of non-incremental search. It is
926 invoked with `C-s <RET> C-w' followed by the search string, which must
927 always be terminated with another <RET>. Being non-incremental, this
928 search does not start until the argument is terminated. It works by
929 constructing a regular expression and searching for that. *Note Regexp
932 You can do a backward word search with `C-r <RET> C-w'.
934 Forward and backward word searches are implemented by the commands
935 `word-search-forward' and `word-search-backward'. You can bind these
936 commands to keys. The reason that incremental search is programmed to
937 invoke them as well is that `C-s <RET> C-w' is the traditional Emacs
938 sequence of keys for word search.
941 File: xemacs.info, Node: Regexp Search, Next: Regexps, Prev: Word Search, Up: Search
943 Regular Expression Search
944 =========================
946 A "regular expression" ("regexp", for short) is a pattern that
947 denotes a (possibly infinite) set of strings. Searching for matches
948 for a regexp is a powerful operation that editors on Unix systems have
949 traditionally offered.
951 To gain a thorough understanding of regular expressions and how to
952 use them to best advantage, we recommend that you study `Mastering
953 Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
954 1997'. (It's known as the "Hip Owls" book, because of the picture on its
955 cover.) You might also read the manuals to *Note (gawk)Top::, *Note
956 (ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note
957 (rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of
960 The XEmacs regular expression syntax most closely resembles that of
961 `ed', or `grep', the GNU versions of which all utilize the GNU `regex'
962 library. XEmacs' version of `regex' has recently been extended with
963 some Perl-like capabilities, described in the next section.
965 In XEmacs, you can search for the next match for a regexp either
966 incrementally or not.
968 Incremental search for a regexp is done by typing `M-C-s'
969 (`isearch-forward-regexp'). This command reads a search string
970 incrementally just like `C-s', but it treats the search string as a
971 regexp rather than looking for an exact match against the text in the
972 buffer. Each time you add text to the search string, you make the
973 regexp longer, and the new regexp is searched for. A reverse regexp
974 search command `isearch-backward-regexp' also exists, bound to `M-C-r'.
976 All of the control characters that do special things within an
977 ordinary incremental search have the same functionality in incremental
978 regexp search. Typing `C-s' or `C-r' immediately after starting a
979 search retrieves the last incremental search regexp used: incremental
980 regexp and non-regexp searches have independent defaults.
982 Non-incremental search for a regexp is done by the functions
983 `re-search-forward' and `re-search-backward'. You can invoke them with
984 `M-x' or bind them to keys. You can also call `re-search-forward' by
985 way of incremental regexp search with `M-C-s <RET>'; similarly for
986 `re-search-backward' with `M-C-r <RET>'.
projects / chise / xemacs-chise.git / blob