X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-6;h=e6c1b6f64cbeca03eaade73e089feb2b01cabda5;hb=af38928b3ca88709a473780697477466c6ab7c5d;hp=b86f3d670e9974211721363fa528b2a8ef186dd1;hpb=430e0db85cc37821320fe27da9feeacc7961003f;p=chise%2Fxemacs-chise.git- diff --git a/info/xemacs.info-6 b/info/xemacs.info-6 index b86f3d6..e6c1b6f 100644 --- a/info/xemacs.info-6 +++ b/info/xemacs.info-6 @@ -1,5 +1,5 @@ -This is Info file ../../info/xemacs.info, produced by Makeinfo version -1.68 from the input file xemacs.texi. +This is ../info/xemacs.info, produced by makeinfo version 4.0b from +xemacs/xemacs.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -30,1129 +30,958 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -File: xemacs.info, Node: Regexp Search, Next: Regexps, Prev: Word Search, Up: Search +File: xemacs.info, Node: Rectangles, Next: Registers, Prev: Accumulating Text, Up: Top -Regular Expression Search -========================= +Rectangles +========== - A "regular expression" ("regexp", for short) is a pattern that -denotes a set of strings, possibly an infinite set. Searching for -matches for a regexp is a powerful operation that editors on Unix -systems have traditionally offered. In XEmacs, you can search for the -next match for a regexp either incrementally or not. + The rectangle commands affect rectangular areas of text: all +characters between a certain pair of columns, in a certain range of +lines. Commands are provided to kill rectangles, yank killed +rectangles, clear them out, or delete them. Rectangle commands are +useful with text in multicolumnar formats, like code with comments at +the right, or for changing text into or out of such formats. + + To specify the rectangle a command should work on, put the mark at +one corner and point at the opposite corner. The specified rectangle is +called the "region-rectangle" because it is controlled about the same +way the region is controlled. Remember that a given combination of +point and mark values can be interpreted either as specifying a region +or as specifying a rectangle; it is up to the command that uses them to +choose the interpretation. + +`M-x delete-rectangle' + Delete the text of the region-rectangle, moving any following text + on each line leftward to the left edge of the region-rectangle. + +`M-x kill-rectangle' + Similar, but also save the contents of the region-rectangle as the + "last killed rectangle". + +`M-x yank-rectangle' + Yank the last killed rectangle with its upper left corner at point. + +`M-x open-rectangle' + Insert blank space to fill the space of the region-rectangle. The + previous contents of the region-rectangle are pushed rightward. + +`M-x clear-rectangle' + Clear the region-rectangle by replacing its contents with spaces. + + The rectangle operations fall into two classes: commands deleting and +moving rectangles, and commands for blank rectangles. + + There are two ways to get rid of the text in a rectangle: you can +discard the text (delete it) or save it as the "last killed" rectangle. +The commands for these two ways are `M-x delete-rectangle' and `M-x +kill-rectangle'. In either case, the portion of each line that falls +inside the rectangle's boundaries is deleted, causing following text +(if any) on the line to move left. + + Note that "killing" a rectangle is not killing in the usual sense; +the rectangle is not stored in the kill ring, but in a special place +that only records the most recently killed rectangle (that is, does not +append to a killed rectangle). Different yank commands have to be used +and only one rectangle is stored, because yanking a rectangle is quite +different from yanking linear text and yank-popping commands are +difficult to make sense of. + + Inserting a rectangle is the opposite of deleting one. You specify +where to put the upper left corner by putting point there. The +rectangle's first line is inserted at point, the rectangle's second line +is inserted at a point one line vertically down, and so on. The number +of lines affected is determined by the height of the saved rectangle. + + To insert the last killed rectangle, type `M-x yank-rectangle'. +This can be used to convert single-column lists into double-column +lists; kill the second half of the list as a rectangle and then yank it +beside the first line of the list. + + There are two commands for working with blank rectangles: `M-x +clear-rectangle' erases existing text, and `M-x open-rectangle' inserts +a blank rectangle. Clearing a rectangle is equivalent to deleting it +and then inserting a blank rectangle of the same size. + + Rectangles can also be copied into and out of registers. *Note +Rectangle Registers: RegRect. - Incremental search for a regexp is done by typing `M-C-s' -(`isearch-forward-regexp'). This command reads a search string -incrementally just like `C-s', but it treats the search string as a -regexp rather than looking for an exact match against the text in the -buffer. Each time you add text to the search string, you make the -regexp longer, and the new regexp is searched for. A reverse regexp -search command `isearch-backward-regexp' also exists, but no key runs -it. + +File: xemacs.info, Node: Registers, Next: Display, Prev: Rectangles, Up: Top - All of the control characters that do special things within an -ordinary incremental search have the same functionality in incremental -regexp search. Typing `C-s' or `C-r' immediately after starting a -search retrieves the last incremental search regexp used: incremental -regexp and non-regexp searches have independent defaults. +Registers +********* - Non-incremental search for a regexp is done by the functions -`re-search-forward' and `re-search-backward'. You can invoke them with -`M-x' or bind them to keys. You can also call `re-search-forward' by -way of incremental regexp search with `M-C-s '. + XEmacs "registers" are places in which you can save text or +positions for later use. Once you save text or a rectangle in a +register, you can copy it into the buffer once or many times; a position +saved in a register is used by moving point to that position. +Rectangles can also be copied into and out of registers (*note +Rectangles::). + + Each register has a name which is a single character. A register can +store a piece of text, a rectangle, a position, a window configuration, +or a file name, but only one thing at any given time. Whatever you +store in a register remains there until you store something else in that +register. To see what a register R contains, use `M-x view-register'. + +`M-x view-register R' + Display a description of what register R contains. + + `M-x view-register' reads a register name as an argument and then +displays the contents of the specified register. + +* Menu: + +* Position: RegPos. Saving positions in registers. +* Text: RegText. Saving text in registers. +* Rectangle: RegRect. Saving rectangles in registers. +* Configurations: RegConfig. Saving window configurations in registers. +* Files: RegFiles. File names in registers. +* Numbers: RegNumbers. Numbers in registers. +* Bookmarks:: Bookmarks are like registers, but persistent.  -File: xemacs.info, Node: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search +File: xemacs.info, Node: RegPos, Next: RegText, Prev: Registers, Up: Registers -Syntax of Regular Expressions +Saving Positions in Registers ============================= - Regular expressions have a syntax in which a few characters are -special constructs and the rest are "ordinary". An ordinary character -is a simple regular expression which matches that character and nothing -else. The special characters are `$', `^', `.', `*', `+', `?', `[', -`]' and `\'; no new special characters will be defined. Any other -character appearing in a regular expression is ordinary, unless a `\' -precedes it. - - For example, `f' is not a special character, so it is ordinary, and -therefore `f' is a regular expression that matches the string `f' and -no other string. (It does not match the string `ff'.) Likewise, `o' -is a regular expression that matches only `o'. - - Any two regular expressions A and B can be concatenated. The result -is a regular expression which matches a string if A matches some amount -of the beginning of that string and B matches the rest of the string. - - As a simple example, you can concatenate the regular expressions `f' -and `o' to get the regular expression `fo', which matches only the -string `fo'. To do something nontrivial, you need to use one of the -following special characters: - -`. (Period)' - is a special character that matches any single character except a - newline. Using concatenation, you can make regular expressions - like `a.b', which matches any three-character string which begins - with `a' and ends with `b'. - -`*' - is not a construct by itself; it is a suffix, which means the - preceding regular expression is to be repeated as many times as - possible. In `fo*', the `*' applies to the `o', so `fo*' matches - one `f' followed by any number of `o's. The case of zero `o's is - allowed: `fo*' does match `f'. - - `*' always applies to the smallest possible preceding expression. - Thus, `fo*' has a repeating `o', not a repeating `fo'. - - The matcher processes a `*' construct by immediately matching as - many repetitions as it can find. Then it continues with the rest - of the pattern. If that fails, backtracking occurs, discarding - some of the matches of the `*'-modified construct in case that - makes it possible to match the rest of the pattern. For example, - matching `ca*ar' against the string `caaar', the `a*' first tries - to match all three `a's; but the rest of the pattern is `ar' and - there is only `r' left to match, so this try fails. The next - alternative is for `a*' to match only two `a's. With this choice, - the rest of the regexp matches successfully. - -`+' - is a suffix character similar to `*' except that it requires that - the preceding expression be matched at least once. For example, - `ca+r' will match the strings `car' and `caaaar' but not the - string `cr', whereas `ca*r' would match all three strings. - -`?' - is a suffix character similar to `*' except that it can match the - preceding expression either once or not at all. For example, - `ca?r' will match `car' or `cr'; nothing else. - -`[ ... ]' - `[' begins a "character set", which is terminated by a `]'. In - the simplest case, the characters between the two form the set. - Thus, `[ad]' matches either one `a' or one `d', and `[ad]*' - matches any string composed of just `a's and `d's (including the - empty string), from which it follows that `c[ad]*r' matches `cr', - `car', `cdr', `caddaar', etc. - - You can include character ranges in a character set by writing two - characters with a `-' between them. Thus, `[a-z]' matches any - lower-case letter. Ranges may be intermixed freely with individual - characters, as in `[a-z$%.]', which matches any lower-case letter - or `$', `%', or period. - - Note that inside a character set the usual special characters are - not special any more. A completely different set of special - characters exists inside character sets: `]', `-', and `^'. - - To include a `]' in a character set, you must make it the first - character. For example, `[]a]' matches `]' or `a'. To include a - `-', write `---', which is a range containing only `-'. To - include `^', make it other than the first character in the set. - -`[^ ... ]' - `[^' begins a "complement character set", which matches any - character except the ones specified. Thus, `[^a-z0-9A-Z]' matches - all characters except letters and digits. - - `^' is not special in a character set unless it is the first - character. The character following the `^' is treated as if it - were first (`-' and `]' are not special there). - - Note that a complement character set can match a newline, unless - newline is mentioned as one of the characters not to match. - -`^' - is a special character that matches the empty string, but only if - at the beginning of a line in the text being matched. Otherwise, - it fails to match anything. Thus, `^foo' matches a `foo' that - occurs at the beginning of a line. - -`$' - is similar to `^' but matches only at the end of a line. Thus, - `xx*$' matches a string of one `x' or more at the end of a line. - -`\' - does two things: it quotes the special characters (including `\'), - and it introduces additional special constructs. - - Because `\' quotes special characters, `\$' is a regular - expression that matches only `$', and `\[' is a regular expression - that matches only `[', and so on. - - Note: for historical compatibility, special characters are treated as -ordinary ones if they are in contexts where their special meanings make -no sense. For example, `*foo' treats `*' as ordinary since there is no -preceding expression on which the `*' can act. It is poor practice to -depend on this behavior; better to quote the special character anyway, -regardless of where is appears. - - Usually, `\' followed by any character matches only that character. -However, there are several exceptions: characters which, when preceded -by `\', are special constructs. Such characters are always ordinary -when encountered on their own. Here is a table of `\' constructs. - -`\|' - specifies an alternative. Two regular expressions A and B with - `\|' in between form an expression that matches anything A or B - matches. - - Thus, `foo\|bar' matches either `foo' or `bar' but no other string. - - `\|' applies to the largest possible surrounding expressions. - Only a surrounding `\( ... \)' grouping can limit the grouping - power of `\|'. - - Full backtracking capability exists to handle multiple uses of - `\|'. - -`\( ... \)' - is a grouping construct that serves three purposes: - - 1. To enclose a set of `\|' alternatives for other operations. - Thus, `\(foo\|bar\)x' matches either `foox' or `barx'. - - 2. To enclose a complicated expression for the postfix `*' to - operate on. Thus, `ba\(na\)*' matches `bananana', etc., with - any (zero or more) number of `na' strings. - - 3. To mark a matched substring for future reference. - - - This last application is not a consequence of the idea of a - parenthetical grouping; it is a separate feature which happens to - be assigned as a second meaning to the same `\( ... \)' construct - because in practice there is no conflict between the two meanings. - Here is an explanation: - -`\DIGIT' - after the end of a `\( ... \)' construct, the matcher remembers the - beginning and end of the text matched by that construct. Then, - later on in the regular expression, you can use `\' followed by - DIGIT to mean "match the same text matched the DIGIT'th time by the - `\( ... \)' construct." - - The strings matching the first nine `\( ... \)' constructs - appearing in a regular expression are assigned numbers 1 through 9 - in order that the open-parentheses appear in the regular - expression. `\1' through `\9' may be used to refer to the text - matched by the corresponding `\( ... \)' construct. - - For example, `\(.*\)\1' matches any newline-free string that is - composed of two identical halves. The `\(.*\)' matches the first - half, which may be anything, but the `\1' that follows must match - the same exact text. - -`\`' - matches the empty string, provided it is at the beginning of the - buffer. - -`\'' - matches the empty string, provided it is at the end of the buffer. - -`\b' - matches the empty string, provided it is at the beginning or end - of a word. Thus, `\bfoo\b' matches any occurrence of `foo' as a - separate word. `\bballs?\b' matches `ball' or `balls' as a - separate word. - -`\B' - matches the empty string, provided it is not at the beginning or - end of a word. - -`\<' - matches the empty string, provided it is at the beginning of a - word. - -`\>' - matches the empty string, provided it is at the end of a word. - -`\w' - matches any word-constituent character. The editor syntax table - determines which characters these are. - -`\W' - matches any character that is not a word-constituent. - -`\sCODE' - matches any character whose syntax is CODE. CODE is a character - which represents a syntax code: thus, `w' for word constituent, - `-' for whitespace, `(' for open-parenthesis, etc. *Note Syntax::. - -`\SCODE' - matches any character whose syntax is not CODE. - - Here is a complicated regexp used by Emacs to recognize the end of a -sentence together with any whitespace that follows. It is given in Lisp -syntax to enable you to distinguish the spaces from the tab characters. -In Lisp syntax, the string constant begins and ends with a -double-quote. `\"' stands for a double-quote as part of the regexp, -`\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for -a newline. + Saving a position records a place in a buffer so that you can move +back there later. Moving to a saved position switches to that buffer +and moves point to that place in it. + +`C-x r R' + Save position of point in register R (`point-to-register'). + +`C-x r j R' + Jump to the position saved in register R (`jump-to-register'). - "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" + To save the current position of point in a register, choose a name R +and type `C-x r R'. The register R retains the position thus +saved until you store something else in that register. -This regexp contains four parts: a character set matching period, `?' -or `!'; a character set matching close-brackets, quotes or parentheses, -repeated any number of times; an alternative in backslash-parentheses -that matches end-of-line, a tab or two spaces; and a character set -matching whitespace characters, repeated any number of times. + The command `C-x r j R' moves point to the position recorded in +register R. The register is not affected; it continues to record the +same location. You can jump to the same position using the same +register as often as you want. + + If you use `C-x r j' to go to a saved position, but the buffer it +was saved from has been killed, `C-x r j' tries to create the buffer +again by visiting the same file. Of course, this works only for buffers +that were visiting files.  -File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search +File: xemacs.info, Node: RegText, Next: RegRect, Prev: RegPos, Up: Registers -Searching and Case -================== +Saving Text in Registers +======================== + + When you want to insert a copy of the same piece of text many times, +it can be impractical to use the kill ring, since each subsequent kill +moves the piece of text further down on the ring. It becomes hard to +keep track of the argument needed to retrieve the same text with `C-y'. +An alternative is to store the text in a register with `C-x r s' +(`copy-to-register') and then retrieve it with `C-x r i' +(`insert-register'). + +`C-x r s R' + Copy region into register R (`copy-to-register'). - All searches in Emacs normally ignore the case of the text they are -searching through; if you specify searching for `FOO', `Foo' and `foo' -are also considered a match. Regexps, and in particular character -sets, are included: `[aB]' matches `a' or `A' or `b' or `B'. +`C-x r g R' +`C-x r i R' + Insert text contents of register R (`insert-register'). - If you want a case-sensitive search, set the variable -`case-fold-search' to `nil'. Then all letters must match exactly, -including case. `case-fold-search' is a per-buffer variable; altering -it affects only the current buffer, but there is a default value which -you can change as well. *Note Locals::. You can also use Case -Sensitive Search from the Options menu on your screen. + `C-x r s R' stores a copy of the text of the region into the +register named R. Given a numeric argument, `C-x r s R' deletes the +text from the buffer as well. + + `C-x r i R' inserts the text from register R in the buffer. By +default it leaves point before the text and places the mark after it. +With a numeric argument (`C-u'), it puts point after the text and the +mark before it.  -File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search +File: xemacs.info, Node: RegRect, Next: RegConfig, Prev: RegText, Up: Registers -Replacement Commands -==================== +Saving Rectangles in Registers +============================== - Global search-and-replace operations are not needed as often in -Emacs as they are in other editors, but they are available. In -addition to the simple `replace-string' command which is like that -found in most editors, there is a `query-replace' command which asks -you, for each occurrence of a pattern, whether to replace it. + A register can contain a rectangle instead of lines of text. The +rectangle is represented as a list of strings. *Note Rectangles::, for +basic information on rectangles and how to specify rectangles in a +buffer. - The replace commands all replace one string (or regexp) with one -replacement string. It is possible to perform several replacements in -parallel using the command `expand-region-abbrevs'. *Note Expanding -Abbrevs::. +`C-x r r R' + Copy the region-rectangle into register R + (`copy-rectangle-to-register'). With a numeric argument, delete it + as well. -* Menu: +`C-x r g R' +`C-x r i R' + Insert the rectangle stored in register R (if it contains a + rectangle) (`insert-register'). + + The `C-x r i R' command inserts linear text if the register +contains that, or inserts a rectangle if the register contains one. -* 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. + See also the command `sort-columns', which you can think of as +sorting a rectangle. *Note Sorting::.  -File: xemacs.info, Node: Unconditional Replace, Next: Regexp Replace, Prev: Replace, Up: Replace +File: xemacs.info, Node: RegConfig, Next: RegNumbers, Prev: RegRect, Up: Registers + +Saving Window Configurations in Registers +========================================= + + You can save the window configuration of the selected frame in a +register, or even the configuration of all windows in all frames, and +restore the configuration later. -Unconditional Replacement -------------------------- +`C-x r w R' + Save the state of the selected frame's windows in register R + (`window-configuration-to-register'). -`M-x replace-string STRING NEWSTRING ' - Replace every occurrence of STRING with NEWSTRING. +`M-x frame-configuration-to-register R' + Save the state of all frames, including all their windows, in + register R (`frame-configuration-to-register'). + + Use `C-x r j R' to restore a window or frame configuration. This is +the same command used to restore a cursor position. When you restore a +frame configuration, any existing frames not included in the +configuration become invisible. If you wish to delete these frames +instead, use `C-u C-x r j R'. + + +File: xemacs.info, Node: RegNumbers, Next: RegFiles, Prev: RegConfig, Up: Registers -`M-x replace-regexp REGEXP NEWSTRING ' - Replace every match for REGEXP with NEWSTRING. +Keeping Numbers in Registers +============================ - To replace every instance of `foo' after point with `bar', use the -command `M-x replace-string' with the two arguments `foo' and `bar'. -Replacement occurs only after point: if you want to cover the whole -buffer you must go to the beginning first. By default, all occurrences -up to the end of the buffer are replaced. To limit replacement to part -of the buffer, narrow to that part of the buffer before doing the -replacement (*note Narrowing::.). + There are commands to store a number in a register, to insert the +number in the buffer in decimal, and to increment it. These commands +can be useful in keyboard macros (*note Keyboard Macros::). - When `replace-string' exits, point is left at the last occurrence -replaced. The value of point when the `replace-string' command was -issued is remembered on the mark ring; `C-u C-' moves back there. +`C-u NUMBER C-x r n REG' + Store NUMBER into register REG (`number-to-register'). - A numeric argument restricts replacement to matches that are -surrounded by word boundaries. +`C-u NUMBER C-x r + REG' + Increment the number in register REG by NUMBER + (`increment-register'). + +`C-x r g REG' + Insert the number from register REG into the buffer. + + `C-x r g' is the same command used to insert any other sort of +register contents into the buffer.  -File: xemacs.info, Node: Regexp Replace, Next: Replacement and Case, Prev: Unconditional Replace, Up: Replace +File: xemacs.info, Node: RegFiles, Next: Bookmarks, Prev: RegNumbers, Up: Registers -Regexp Replacement ------------------- +Keeping File Names in Registers +=============================== - `replace-string' replaces exact matches for a single string. The -similar command `replace-regexp' replaces any match for a specified -pattern. + If you visit certain file names frequently, you can visit them more +conveniently if you put their names in registers. Here's the Lisp code +used to put a file name in a register: - In `replace-regexp', the NEWSTRING need not be constant. It can -refer to all or part of what is matched by the REGEXP. `\&' in -NEWSTRING stands for the entire text being replaced. `\D' in -NEWSTRING, where D is a digit, stands for whatever matched the D'th -parenthesized grouping in REGEXP. For example, + (set-register ?R '(file . NAME)) - M-x replace-regexp c[ad]+r \&-safe +For example, -would replace (for example) `cadr' with `cadr-safe' and `cddr' with -`cddr-safe'. + (set-register ?z '(file . "/usr/src/xemacs/src/ChangeLog")) - M-x replace-regexp \(c[ad]+r\)-safe \1 +puts the file name shown in register `z'. -would perform exactly the opposite replacements. To include a `\' in -the text to replace with, you must give `\\'. + To visit the file whose name is in register R, type `C-x r j R'. +(This is the same command used to jump to a position or restore a frame +configuration.)  -File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace +File: xemacs.info, Node: Bookmarks, Prev: RegFiles, Up: Registers -Replace Commands and Case -------------------------- +Bookmarks +========= - If the arguments to a replace command are in lower case, the command -preserves case when it makes a replacement. Thus, the following -command: + "Bookmarks" are somewhat like registers in that they record +positions you can jump to. Unlike registers, they have long names, and +they persist automatically from one Emacs session to the next. The +prototypical use of bookmarks is to record "where you were reading" in +various files. - M-x replace-string foo bar + Note: bookmark.el is distributed in edit-utils package. You need to +install that to use bookmark facility (*note Packages::). -replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR', -and `Foo' with `Bar'. If upper-case letters are used in the second -argument, they remain upper-case every time that argument is inserted. -If upper-case letters are used in the first argument, the second -argument is always substituted exactly as given, with no case -conversion. Likewise, if the variable `case-replace' is set to `nil', -replacement is done without case conversion. If `case-fold-search' is -set to `nil', case is significant in matching occurrences of `foo' to -replace; also, case conversion of the replacement string is not done. +`C-x r m ' + Set the bookmark for the visited file, at point. - -File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace - -Query Replace -------------- - -`M-% STRING NEWSTRING ' -`M-x query-replace STRING NEWSTRING ' - Replace some occurrences of STRING with NEWSTRING. - -`M-x query-replace-regexp REGEXP NEWSTRING ' - Replace some matches for REGEXP with NEWSTRING. - - If you want to change only some of the occurrences of `foo' to -`bar', not all of them, you can use `query-replace' instead of `M-%'. -This command finds occurrences of `foo' one by one, displays each -occurrence, and asks you whether to replace it. A numeric argument to -`query-replace' tells it to consider only occurrences that are bounded -by word-delimiter characters. - - Aside from querying, `query-replace' works just like -`replace-string', and `query-replace-regexp' works just like -`replace-regexp'. - - The things you can type when you are shown an occurrence of STRING -or a match for REGEXP are: - -`' - to replace the occurrence with NEWSTRING. This preserves case, - just like `replace-string', provided `case-replace' is non-`nil', - as it normally is. - -`' - to skip to the next occurrence without replacing this one. - -`, (Comma)' - to replace this occurrence and display the result. You are then - prompted for another input character. However, since the - replacement has already been made, and are equivalent. - At this point, you can type `C-r' (see below) to alter the - replaced text. To undo the replacement, you can type `C-x u'. - This exits the `query-replace'. If you want to do further - replacement you must use `C-x ESC' to restart (*note - Repetition::.). - -`' - to exit without doing any more replacements. - -`. (Period)' - to replace this occurrence and then exit. - -`!' - to replace all remaining occurrences without asking again. - -`^' - to go back to the location of the previous occurrence (or what - used to be an occurrence), in case you changed it by mistake. - This works by popping the mark ring. Only one `^' in a row is - allowed, because only one previous replacement location is kept - during `query-replace'. +`C-x r m BOOKMARK ' + Set the bookmark named BOOKMARK at point (`bookmark-set'). -`C-r' - to enter a recursive editing level, in case the occurrence needs - to be edited rather than just replaced with NEWSTRING. When you - are done, exit the recursive editing level with `C-M-c' and the - next occurrence will be displayed. *Note Recursive Edit::. +`C-x r b BOOKMARK ' + Jump to the bookmark named BOOKMARK (`bookmark-jump'). -`C-w' - to delete the occurrence, and then enter a recursive editing level - as in `C-r'. Use the recursive edit to insert text to replace the - deleted occurrence of STRING. When done, exit the recursive - editing level with `C-M-c' and the next occurrence will be - displayed. +`C-x r l' + List all bookmarks (`list-bookmarks'). -`C-l' - to redisplay the screen and then give another answer. +`M-x bookmark-save' + Save all the current bookmark values in the default bookmark file. -`C-h' - to display a message summarizing these options, then give another - answer. + The prototypical use for bookmarks is to record one current position +in each of several files. So the command `C-x r m', which sets a +bookmark, uses the visited file name as the default for the bookmark +name. If you name each bookmark after the file it points to, then you +can conveniently revisit any of those files with `C-x r b', and move to +the position of the bookmark at the same time. - If you type any other character, Emacs exits the `query-replace', and -executes the character as a command. To restart the `query-replace', -use `C-x ', which repeats the `query-replace' because it used the -minibuffer to read its arguments. *Note C-x ESC: Repetition. + To display a list of all your bookmarks in a separate buffer, type +`C-x r l' (`list-bookmarks'). If you switch to that buffer, you can +use it to edit your bookmark definitions or annotate the bookmarks. +Type `C-h m' in that buffer for more information about its special +editing commands. - -File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search + When you kill XEmacs, XEmacs offers to save your bookmark values in +your default bookmark file, `~/.emacs.bmk', if you have changed any +bookmark values. You can also save the bookmarks at any time with the +`M-x bookmark-save' command. The bookmark commands load your default +bookmark file automatically. This saving and loading is how bookmarks +persist from one XEmacs session to the next. -Other Search-and-Loop Commands -============================== + If you set the variable `bookmark-save-flag' to 1, then each command +that sets a bookmark will also save your bookmarks; this way, you don't +lose any bookmark values even if XEmacs crashes. (The value, if a +number, says how many bookmark modifications should go by between +saving.) - Here are some other commands that find matches for a regular -expression. They all operate from point to the end of the buffer. + Bookmark position values are saved with surrounding context, so that +`bookmark-jump' can find the proper position even if the file is +modified slightly. The variable `bookmark-search-size' says how many +characters of context to record, on each side of the bookmark's +position. -`M-x occur' - Print each line that follows point and contains a match for the - specified regexp. A numeric argument specifies the number of - context lines to print before and after each matching line; the - default is none. + Here are some additional commands for working with bookmarks: - The buffer `*Occur*' containing the output serves as a menu for - finding occurrences in their original context. Find an occurrence - as listed in `*Occur*', position point there, and type `C-c C-c'; - this switches to the buffer that was searched and moves point to - the original of the same occurrence. +`M-x bookmark-load FILENAME ' + Load a file named FILENAME that contains a list of bookmark + values. You can use this command, as well as `bookmark-write', to + work with other files of bookmark values in addition to your + default bookmark file. -`M-x list-matching-lines' - Synonym for `M-x occur'. +`M-x bookmark-write FILENAME ' + Save all the current bookmark values in the file FILENAME. -`M-x count-matches' - Print the number of matches following point for the specified - regexp. +`M-x bookmark-delete BOOKMARK ' + Delete the bookmark named BOOKMARK. -`M-x delete-non-matching-lines' - Delete each line that follows point and does not contain a match - for the specified regexp. +`M-x bookmark-insert-location BOOKMARK ' + Insert in the buffer the name of the file that bookmark BOOKMARK + points to. -`M-x delete-matching-lines' - Delete each line that follows point and contains a match for the - specified regexp. +`M-x bookmark-insert BOOKMARK ' + Insert in the buffer the _contents_ of the file that bookmark + BOOKMARK points to.  -File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top +File: xemacs.info, Node: Display, Next: Search, Prev: Registers, Up: Top -Commands for Fixing Typos -************************* +Controlling the Display +*********************** + + Since only part of a large buffer fits in the window, XEmacs tries +to show the part that is likely to be interesting. The display control +commands allow you to specify which part of the text you want to see. - This chapter describes commands that are especially useful when you -catch a mistake in your text just after you have made it, or when you -change your mind while composing text on line. +`C-l' + Clear frame and redisplay, scrolling the selected window to center + point vertically within it (`recenter'). + +`C-v' +`pgdn' +`next' + Scroll forward (a windowful or a specified number of lines) + (`scroll-up'). On most X keyboards, you can get this + functionality using the key labelled `Page Down', which generates + either `next' or `pgdn'. + +`M-v' +`pgup' +`prior' + Scroll backward (`scroll-down'). On most X keyboards, you can get + this functionality using the key labelled `Page Up', which + generates either `prior' or `pgup'. + +`ARG C-l' + Scroll so point is on line ARG (`recenter'). + +`C-x <' +`C-pgdn' +`C-next' + Scroll text in current window to the left (`scroll-left'). + +`C-x >' +`C-pgup' +`C-prior' + Scroll to the right (`scroll-right'). + +`C-x $' + Make deeply indented lines invisible (`set-selective-display'). * Menu: -* Kill Errors:: Commands to kill a batch of recently entered text. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word, or a whole file. +* Scrolling:: Moving text up and down in a window. +* Horizontal Scrolling:: Moving text left and right in a window. +* Selective Display:: Hiding lines with lots of indentation. +* Display Vars:: Information on variables for customizing display. + + +File: xemacs.info, Node: Scrolling, Next: Horizontal Scrolling, Prev: Display, Up: Display + +Scrolling +========= + + If a buffer contains text that is too large to fit entirely within +the window that is displaying the buffer, XEmacs shows a contiguous +section of the text. The section shown always contains point. + + "Scrolling" means moving text up or down in the window so that +different parts of the text are visible. Scrolling forward means that +text moves up, and new text appears at the bottom. Scrolling backward +moves text down and new text appears at the top. + + Scrolling happens automatically if you move point past the bottom or +top of the window. You can also explicitly request scrolling with the +commands in this section. + +`C-l' + Clear frame and redisplay, scrolling the selected window to center + point vertically within it (`recenter'). + +`C-v' +`pgdn' +`next' + Scroll forward (a windowful or a specified number of lines) + (`scroll-up'). + +`M-v' +`pgup' +`prior' + Scroll backward (`scroll-down'). + +`ARG C-l' + Scroll so point is on line ARG (`recenter'). + + The most basic scrolling command is `C-l' (`recenter') with no +argument. It clears the entire frame and redisplays all windows. In +addition, it scrolls the selected window so that point is halfway down +from the top of the window. + + The scrolling commands `C-v' and `M-v' let you move all the text in +the window up or down a few lines. `C-v' (`scroll-up') with an +argument shows you that many more lines at the bottom of the window, +moving the text and point up together as `C-l' might. `C-v' with a +negative argument shows you more lines at the top of the window. +`Meta-v' (`scroll-down') is like `C-v', but moves in the opposite +direction. + + To read the buffer a windowful at a time, use `C-v' with no +argument. `C-v' takes the last two lines at the bottom of the window +and puts them at the top, followed by nearly a whole windowful of lines +not previously visible. Point moves to the new top of the window if it +was in the text scrolled off the top. `M-v' with no argument moves +backward with similar overlap. The number of lines of overlap across a +`C-v' or `M-v' is controlled by the variable +`next-screen-context-lines'; by default, it is two. + + Another way to scroll is using `C-l' with a numeric argument. `C-l' +does not clear the frame when given an argument; it only scrolls the +selected window. With a positive argument N, `C-l' repositions text to +put point N lines down from the top. An argument of zero puts point on +the very top line. Point does not move with respect to the text; +rather, the text and point move rigidly on the frame. `C-l' with a +negative argument puts point that many lines from the bottom of the +window. For example, `C-u - 1 C-l' puts point on the bottom line, and +`C-u - 5 C-l' puts it five lines from the bottom. Just `C-u' as +argument, as in `C-u C-l', scrolls point to the center of the frame. + + Scrolling happens automatically if point has moved out of the visible +portion of the text when it is time to display. Usually scrolling is +done to put point vertically centered within the window. However, if +the variable `scroll-step' has a non-zero value, an attempt is made to +scroll the buffer by that many lines; if that is enough to bring point +back into visibility, that is what happens. + + Scrolling happens automatically if point has moved out of the visible +portion of the text when it is time to display. Usually scrolling is +done to put point vertically centered within the window. However, if +the variable `scroll-step' has a non-zero value, an attempt is made to +scroll the buffer by that many lines; if that is enough to bring point +back into visibility, that is what happens. + + If you set `scroll-step' to a small value because you want to use +arrow keys to scroll the screen without recentering, the redisplay +preemption will likely make XEmacs keep recentering the screen when +scrolling fast, regardless of `scroll-step'. To prevent this, set +`scroll-conservatively' to a small value, which will have the result of +overriding the redisplay preemption.  -File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit +File: xemacs.info, Node: Horizontal Scrolling, Prev: Scrolling, Up: Display + +Horizontal Scrolling +==================== + +`C-x <' + Scroll text in current window to the left (`scroll-left'). -Killing Your Mistakes -===================== +`C-x >' + Scroll to the right (`scroll-right'). -`' - Delete last character (`delete-backward-char'). + The text in a window can also be scrolled horizontally. This means +that each line of text is shifted sideways in the window, and one or +more characters at the beginning of each line are not displayed at all. +When a window has been scrolled horizontally in this way, text lines +are truncated rather than continued (*note Continuation Lines::), with +a `$' appearing in the first column when there is text truncated to the +left, and in the last column when there is text truncated to the right. -`M-' - Kill last word (`backward-kill-word'). + The command `C-x <' (`scroll-left') scrolls the selected window to +the left by N columns with argument N. With no argument, it scrolls by +almost the full width of the window (two columns less, to be precise). +`C-x >' (`scroll-right') scrolls similarly to the right. The window +cannot be scrolled any farther to the right once it is displaying +normally (with each line starting at the window's left margin); +attempting to do so has no effect. + + +File: xemacs.info, Node: Selective Display, Next: Display Vars, Prev: Display, Up: Display -`C-x ' - Kill to beginning of sentence (`backward-kill-sentence'). +Selective Display +================= - The character (`delete-backward-char') is the most important -correction command. When used among graphic (self-inserting) -characters, it can be thought of as canceling the last character typed. + XEmacs can hide lines indented more than a certain number of columns +(you specify how many columns). This allows you to get an overview of +a part of a program. - When your mistake is longer than a couple of characters, it might be -more convenient to use `M-' or `C-x '. `M-' kills back -to the start of the last word, and `C-x ' kills back to the start -of the last sentence. `C-x ' is particularly useful when you are -thinking of what to write as you type it, in case you change your mind -about phrasing. `M-' and `C-x ' save the killed text for -`C-y' and `M-y' to retrieve. *Note Yanking::. + To hide lines, type `C-x $' (`set-selective-display') with a numeric +argument N. (*Note Arguments::, for information on giving the +argument.) Lines with at least N columns of indentation disappear from +the screen. The only indication of their presence are three dots +(`...'), which appear at the end of each visible line that is followed +by one or more invisible ones. - `M-' is often useful even when you have typed only a few -characters wrong, if you know you are confused in your typing and aren't -sure exactly what you typed. At such a time, you cannot correct with - except by looking at the screen to see what you did. It requires -less thought to kill the whole word and start over. + The invisible lines are still present in the buffer, and most editing +commands see them as usual, so it is very easy to put point in the +middle of invisible text. When this happens, the cursor appears at the +end of the previous line, after the three dots. If point is at the end +of the visible line, before the newline that ends it, the cursor +appears before the three dots. + + The commands `C-n' and `C-p' move across the invisible lines as if +they were not there. + + To make everything visible again, type `C-x $' with no argument.  -File: xemacs.info, Node: Transpose, Next: Fixing Case, Prev: Kill Errors, Up: Fixit - -Transposing Text -================ - -`C-t' - Transpose two characters (`transpose-chars'). - -`M-t' - Transpose two words (`transpose-words'). - -`C-M-t' - Transpose two balanced expressions (`transpose-sexps'). - -`C-x C-t' - Transpose two lines (`transpose-lines'). - - The common error of transposing two adjacent characters can be fixed -with the `C-t' command (`transpose-chars'). Normally, `C-t' transposes -the two characters on either side of point. When given at the end of a -line, `C-t' transposes the last two characters on the line, rather than -transposing the last character of the line with the newline, which -would be useless. If you catch a transposition error right away, you -can fix it with just `C-t'. If you catch the error later, move the -cursor back to between the two transposed characters. If you -transposed a space with the last character of the word before it, the -word motion commands are a good way of getting there. Otherwise, a -reverse search (`C-r') is often the best way. *Note Search::. - - `Meta-t' (`transpose-words') transposes the word before point with -the word after point. It moves point forward over a word, dragging the -word preceding or containing point forward as well. The punctuation -characters between the words do not move. For example, `FOO, BAR' -transposes into `BAR, FOO' rather than `BAR FOO,'. - - `C-M-t' (`transpose-sexps') is a similar command for transposing two -expressions (*note Lists::.), and `C-x C-t' (`transpose-lines') -exchanges lines. It works like `M-t' but in determines the division of -the text into syntactic units differently. - - A numeric argument to a transpose command serves as a repeat count: -it tells the transpose command to move the character (word, sexp, line) -before or containing point across several other characters (words, -sexps, lines). For example, `C-u 3 C-t' moves the character before -point forward across three other characters. This is equivalent to -repeating `C-t' three times. `C-u - 4 M-t' moves the word before point -backward across four words. `C-u - C-M-t' would cancel the effect of -plain `C-M-t'. - - A numeric argument of zero transposes the character (word, sexp, -line) ending after point with the one ending after the mark (otherwise a -command with a repeat count of zero would do nothing). +File: xemacs.info, Node: Display Vars, Prev: Selective Display, Up: Display + +Variables Controlling Display +============================= + + This section contains information for customization only. Beginning +users should skip it. + + When you reenter XEmacs after suspending, XEmacs normally clears the +screen and redraws the entire display. On some terminals with more than +one page of memory, it is possible to arrange the termcap entry so that +the `ti' and `te' strings (output to the terminal when XEmacs is +entered and exited, respectively) switch between pages of memory so as +to use one page for XEmacs and another page for other output. In that +case, you might want to set the variable `no-redraw-on-reenter' to +non-`nil' so that XEmacs will assume, when resumed, that the screen +page it is using still contains what XEmacs last wrote there. + + The variable `echo-keystrokes' controls the echoing of +multi-character keys; its value is the number of seconds of pause +required to cause echoing to start, or zero, meaning don't echo at all. +*Note Echo Area::. + + If the variable `ctl-arrow' is `nil', control characters in the +buffer are displayed with octal escape sequences, all except newline and +tab. If its value is `t', then control characters will be printed with +an up-arrow, for example `^A'. + + If its value is not `t' and not `nil', then characters whose code is +greater than 160 (that is, the space character (32) with its high bit +set) will be assumed to be printable, and will be displayed without +alteration. This is the default when running under X Windows, since +XEmacs assumes an ISO/8859-1 character set (also known as "Latin1"). +The `ctl-arrow' variable may also be set to an integer, in which case +all characters whose codes are greater than or equal to that value will +be assumed to be printable. + + Altering the value of `ctl-arrow' makes it local to the current +buffer; until that time, the default value is in effect. *Note +Locals::. + + Normally, a tab character in the buffer is displayed as whitespace +which extends to the next display tab stop position, and display tab +stops come at intervals equal to eight spaces. The number of spaces +per tab is controlled by the variable `tab-width', which is made local +by changing it, just like `ctl-arrow'. Note that how the tab character +in the buffer is displayed has nothing to do with the definition of + as a command. + + If you set the variable `selective-display-ellipses' to `nil', the +three dots at the end of a line that precedes invisible lines do not +appear. There is no visible indication of the invisible lines. This +variable becomes local automatically when set.  -File: xemacs.info, Node: Fixing Case, Next: Spelling, Prev: Transpose, Up: Fixit +File: xemacs.info, Node: Search, Next: Fixit, Prev: Display, Up: Top -Case Conversion -=============== +Searching and Replacement +************************* -`M-- M-l' - Convert last word to lower case. Note that `Meta--' is - "Meta-minus." + Like other editors, Emacs has commands for searching for occurrences +of a string. The principal search command is unusual in that it is +"incremental": it begins to search before you have finished typing the +search string. There are also non-incremental search commands more like +those of other editors. -`M-- M-u' - Convert last word to all upper case. + Besides the usual `replace-string' command that finds all +occurrences of one string and replaces them with another, Emacs has a +fancy replacement command called `query-replace' which asks +interactively which occurrences to replace. -`M-- M-c' - Convert last word to lower case with capital initial. +* Menu: - A common error is to type words in the wrong case. Because of this, -the word case-conversion commands `M-l', `M-u', and `M-c' do not move -the cursor when used with a negative argument. As soon as you see you -have mistyped the last word, you can simply case-convert it and -continue typing. *Note Case::. +* Incremental Search:: Search happens as you type the string. +* Non-Incremental 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.  -File: xemacs.info, Node: Spelling, Prev: Fixing Case, Up: Fixit +File: xemacs.info, Node: Incremental Search, Next: Non-Incremental Search, Prev: Search, Up: Search + +Incremental Search +================== + + An incremental search begins searching as soon as you type the first +character of the search string. As you type in the search string, Emacs +shows you where the string (as you have typed it so far) is found. +When you have typed enough characters to identify the place you want, +you can stop. Depending on what you do next, you may or may not need to +terminate the search explicitly with a . -Checking and Correcting Spelling -================================ +`C-s' + Incremental search forward (`isearch-forward'). -`M-$' - Check and correct spelling of word (`spell-word'). +`C-r' + Incremental search backward (`isearch-backward'). + + `C-s' starts an incremental search. `C-s' reads characters from the +keyboard and positions the cursor at the first occurrence of the +characters that you have typed. If you type `C-s' and then `F', the +cursor moves right after the first `F'. Type an `O', and see the +cursor move to after the first `FO'. After another `O', the cursor is +after the first `FOO' after the place where you started the search. +Meanwhile, the search string `FOO' has been echoed in the echo area. + + The echo area display ends with three dots when actual searching is +going on. When search is waiting for more input, the three dots are +removed. (On slow terminals, the three dots are not displayed.) + + If you make a mistake in typing the search string, you can erase +characters with . Each cancels the last character of the +search string. This does not happen until Emacs is ready to read +another input character; first it must either find, or fail to find, +the character you want to erase. If you do not want to wait for this +to happen, use `C-g' as described below. + + When you are satisfied with the place you have reached, you can type + (or ), which stops searching, leaving the cursor where the +search brought it. Any command not specially meaningful in searches +also stops the search and is then executed. Thus, typing `C-a' exits +the search and then moves to the beginning of the line. is +necessary only if the next command you want to type is a printing +character, , , or another control character that is special +within searches (`C-q', `C-w', `C-r', `C-s', or `C-y'). + + Sometimes you search for `FOO' and find it, but were actually +looking for a different occurrence of it. To move to the next +occurrence of the search string, type another `C-s'. Do this as often +as necessary. If you overshoot, you can cancel some `C-s' characters +with . + + After you exit a search, you can search for the same string again by +typing just `C-s C-s': the first `C-s' is the key that invokes +incremental search, and the second `C-s' means "search again". + + If the specified string is not found at all, the echo area displays +the text `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 +`FOOT', and there is no `FOOT', the cursor may be after the `FOO' in +`FOOL'. At this point there are several things you can do. If you +mistyped the search string, correct it. If you like the place you have +found, you can type or some other Emacs command to "accept what +the search offered". Or you can type `C-g', which removes from the +search string the characters that could not be found (the `T' in +`FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second +`C-g' at that point cancels the search entirely, returning point to +where it was when the search started. + + If a search is failing and you ask to repeat it by typing another +`C-s', it starts again from the beginning of the buffer. Repeating a +failing backward search with `C-r' starts again from the end. This is +called "wrapping around". `Wrapped' appears in the search prompt once +this has happened. + + The `C-g' "quit" character 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, `C-g' cancels the +entire search. The cursor moves back to where you started the search. +If `C-g' is typed when there are characters in the search string that +have not been found--because Emacs is still searching for them, or +because it has failed to find them--then the search string characters +which have not been found are discarded from the search string. The +search is now successful and waiting for more input, so a second `C-g' +cancels the entire search. + + To search for a control character such as `C-s' or or , +you must quote it by typing `C-q' first. This function of `C-q' is +analogous to its meaning as an Emacs command: it causes the following +character to be treated the way a graphic character would normally be +treated in the same context. + + To search backwards, you can use `C-r' instead of `C-s' to start the +search; `C-r' is the key that runs the command (`isearch-backward') to +search backward. You can also use `C-r' to change from searching +forward to searching backwards. Do this if a search fails because the +place you started was too far down in the file. Repeated `C-r' keeps +looking for more occurrences backwards. `C-s' starts going forward +again. You can cancel `C-r' in a search with . + + The characters `C-y' and `C-w' can be used in incremental search to +grab text from the buffer into the search string. This makes it +convenient to search for another occurrence of text at point. `C-w' +copies the word after point as part of the search string, advancing +point over that word. Another `C-s' to repeat the search will then +search for a string including that word. `C-y' is similar to `C-w' but +copies the rest of the current line into the search string. + + The characters `M-p' and `M-n' can be used in an incremental search +to recall things which you have searched for in the past. A list of +the last 16 things you have searched for is retained, and `M-p' and +`M-n' let you cycle through that ring. + + The character `M-' does completion on the elements in the +search history ring. For example, if you know that you have recently +searched for the string `POTATOE', you could type `C-s P O M-'. +If you had searched for other strings beginning with `PO' then you +would be shown a list of them, and would need to type more to select +one. + + You can change any of the special characters in incremental search +via the normal keybinding mechanism: simply add a binding to the +`isearch-mode-map'. For example, to make the character `C-b' mean +"search backwards" while in isearch-mode, do this: + + (define-key isearch-mode-map "\C-b" 'isearch-repeat-backward) + + These are the default bindings of isearch-mode: + +`DEL' + Delete a character from the incremental search string + (`isearch-delete-char'). + +`RET' + Exit incremental search (`isearch-exit'). + +`C-q' + Quote special characters for incremental search + (`isearch-quote-char'). + +`C-s' + Repeat incremental search forward (`isearch-repeat-forward'). -`M-x spell-buffer' - Check and correct spelling of each word in the buffer. +`C-r' + Repeat incremental search backward (`isearch-repeat-backward'). -`M-x spell-region' - Check and correct spelling of each word in the region. +`C-y' + Pull rest of line from buffer into search string + (`isearch-yank-line'). -`M-x spell-string' - Check spelling of specified word. +`C-w' + Pull next word from buffer into search string + (`isearch-yank-word'). - To check the spelling of the word before point, and optionally -correct it, use the command `M-$' (`spell-word'). This command runs an -inferior process containing the `spell' program to see whether the word -is correct English. If it is not, it asks you to edit the word (in the -minibuffer) into a corrected spelling, and then performs a -`query-replace' to substitute the corrected spelling for the old one -throughout the buffer. +`C-g' + Cancels input back to what has been found successfully, or aborts + the isearch (`isearch-abort'). - If you exit the minibuffer without altering the original spelling, it -means you do not want to do anything to that word. In that case, the -`query-replace' is not done. +`M-p' + Recall the previous element in the isearch history ring + (`isearch-ring-retreat'). - `M-x spell-buffer' checks each word in the buffer the same way that -`spell-word' does, doing a `query-replace' for every incorrect word if -appropriate. +`M-n' + Recall the next element in the isearch history ring + (`isearch-ring-advance'). - `M-x spell-region' is similar to `spell-buffer' but operates only on -the region, not the entire buffer. +`M-' + Do completion on the elements in the isearch history ring + (`isearch-complete'). - `M-x spell-string' reads a string as an argument and checks whether -that is a correctly spelled English word. It prints a message giving -the answer in the echo area. + Any other character which is normally inserted into a buffer when +typed is automatically added to the search string in isearch-mode. - -File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top +Slow Terminal Incremental Search +-------------------------------- -File Handling -************* + 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 each place the search gets to, it creates a new +single-line window and uses that to display the line the search has +found. The single-line window appears as soon as point gets outside of +the text that is already on the screen. - The basic unit of stored data in Unix is the "file". To edit a file, -you must tell Emacs to examine the file and prepare a buffer containing -a copy of the file's text. This is called "visiting" the file. Editing -commands apply directly to text in the buffer; that is, to the copy -inside Emacs. Your changes appear in the file itself only when you -"save" the buffer back into the file. + When the search is terminated, the single-line window is removed. +Only at this time the window in which the search was done is +redisplayed to show its new value of point. - In addition to visiting and saving files, Emacs can delete, copy, -rename, and append to files, and operate on file directories. + The three dots at the end of the search string, normally used to +indicate that searching is going on, are not displayed in slow style +display. -* Menu: + The slow terminal style of display is used when the terminal baud +rate is less than or equal to the value of the variable +`search-slow-speed', initially 1200. -* File Names:: How to type and edit file name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -* Auto Save:: Auto Save periodically protects against loss of data. -* Version Control:: Version control systems (RCS and SCCS). -* ListDir:: Listing the contents of a file directory. -* Comparing Files:: Finding where two files differ. -* Dired:: "Editing" a directory to delete, rename, etc. - the files in it. -* Misc File Ops:: Other things you can do on files. + The number of lines to use in slow terminal search display is +controlled by the variable `search-slow-window-lines'. Its normal +value is 1.  -File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files +File: xemacs.info, Node: Non-Incremental Search, Next: Word Search, Prev: Incremental Search, Up: Search -File Names -========== +Non-Incremental Search +====================== - Most Emacs commands that operate on a file require you to specify the -file name. (Saving and reverting are exceptions; the buffer knows which -file name to use for them.) File names are specified in the minibuffer -(*note Minibuffer::.). "Completion" is available, to make it easier to -specify long file names. *Note Completion::. - - There is always a "default file name" which is used if you enter an -empty argument by typing just . Normally the default file name is -the name of the file visited in the current buffer; this makes it easy -to operate on that file with any of the Emacs file commands. - - Each buffer has a default directory, normally the same as the -directory of the file visited in that buffer. When Emacs reads a file -name, the default directory is used if you do not specify a directory. -If you specify a directory in a relative fashion, with a name that does -not start with a slash, it is interpreted with respect to the default -directory. The default directory of the current buffer is kept in the -variable `default-directory', which has a separate value in every -buffer. The value of the variable should end with a slash. - - For example, if the default file name is `/u/rms/gnu/gnu.tasks' then -the default directory is `/u/rms/gnu/'. If you type just `foo', which -does not specify a directory, it is short for `/u/rms/gnu/foo'. -`../.login' would stand for `/u/rms/.login'. `new/foo' would stand for -the filename `/u/rms/gnu/new/foo'. - - The variable `default-directory-alist' takes an alist of major modes -and their opinions on `default-directory' as a Lisp expression to -evaluate. A resulting value of `nil' is ignored in favor of -`default-directory'. - - You can create a new directory with the function `make-directory', -which takes as an argument a file name string. The current directory is -displayed in the minibuffer when the function is called; you can delete -the old directory name and supply a new directory name. For example, if -the current directory is `/u/rms/gnu', you can delete `gnu' and type -`oryx' and to create `/u/rms/oryx'. Removing a directory is -similar to creating one. To remove a directory, use -`remove-directory'; it takes one argument, a file name string. - - The command `M-x pwd' prints the current buffer's default directory, -and the command `M-x cd' sets it (to a value read using the -minibuffer). A buffer's default directory changes only when the `cd' -command is used. A file-visiting buffer's default directory is -initialized to the directory of the file that is visited there. If a -buffer is created with `C-x b', its default directory is copied from -that of the buffer that was current at the time. - - The default directory name actually appears in the minibuffer when -the minibuffer becomes active to read a file name. This serves two -purposes: it shows you what the default is, so that you can type a -relative file name and know with certainty what it will mean, and it -allows you to edit the default to specify a different directory. To -inhibit the insertion of the default directory, set the variable -`insert-default-directory' to `nil'. - - Note that it is legitimate to type an absolute file name after you -enter the minibuffer, ignoring the presence of the default directory -name. The final minibuffer contents may look invalid, but that is not -so. *Note Minibuffer File::. - - `$' in a file name is used to substitute environment variables. For -example, if you have used the shell command `setenv FOO rms/hacks' to -set up an environment variable named `FOO', then you can use -`/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for -`/u/rms/hacks/test.c'. The environment variable name consists of all -the alphanumeric characters after the `$'; alternatively, it may be -enclosed in braces after the `$'. Note that the `setenv' command -affects Emacs only if done before Emacs is started. - - To access a file with `$' in its name, type `$$'. This pair is -converted to a single `$' at the same time variable substitution is -performed for single `$'. The Lisp function that performs the -substitution is called `substitute-in-file-name'. The substitution is -performed only on filenames read as such using the minibuffer. + Emacs also has conventional non-incremental search commands, which +require you type the entire search string before searching begins. - -File: xemacs.info, Node: Visiting, Next: Saving, Prev: File Names, Up: Files - -Visiting Files -============== - -`C-x C-f' - Visit a file (`find-file'). - -`C-x C-v' - Visit a different file instead of the one visited last - (`find-alternate-file'). - -`C-x 4 C-f' - Visit a file, in another window (`find-file-other-window'). Don't - change this window. - -`C-x 5 C-f' - Visit a file, in another frame (`find-file-other-frame'). Don't - change this window or frame. - - "Visiting" a file means copying its contents into an Emacs buffer so -you can edit it. Emacs creates a new buffer for each file you visit. -We say that the buffer is visiting the file that it was created to -hold. Emacs constructs the buffer name from the file name by throwing -away the directory and keeping just the file name. For example, a file -named `/usr/rms/emacs.tex' is displayed in a buffer named `emacs.tex'. -If a buffer with that name exists, a unique name is constructed by -appending `<2>', `<3>',and so on, using the lowest number that makes a -name that is not already in use. - - Each window's mode line shows the name of the buffer that is being -displayed in that window, so you can always tell what buffer you are -editing. - - The changes you make with Emacs are made in the Emacs buffer. They -do not take effect in the file that you visit, or any other permanent -place, until you "save" the buffer. Saving the buffer means that Emacs -writes the current contents of the buffer into its visited file. *Note -Saving::. - - If a buffer contains changes that have not been saved, the buffer is -said to be "modified". This is important because it implies that some -changes will be lost if the buffer is not saved. The mode line displays -two stars near the left margin if the buffer is modified. - - To visit a file, use the command `C-x C-f' (`find-file'). Follow -the command with the name of the file you wish to visit, terminated by a -. If you are using XEmacs under X, you can also use the Open... -command from the File menu bar item. - - The file name is read using the minibuffer (*note Minibuffer::.), -with defaulting and completion in the standard manner (*note File -Names::.). While in the minibuffer, you can abort `C-x C-f' by typing -`C-g'. - - `C-x C-f' has completed successfully when text appears on the screen -and a new buffer name appears in the mode line. If the specified file -does not exist and could not be created or cannot be read, an error -results. The error message is printed in the echo area, and includes -the name of the file that Emacs was trying to visit. - - If you visit a file that is already in Emacs, `C-x C-f' does not make -another copy. It selects the existing buffer containing that file. -However, before doing so, it checks that the file itself has not changed -since you visited or saved it last. If the file has changed, Emacs -prints a warning message. *Note Simultaneous Editing: Interlocking. - - You can switch to a specific file called out in the current buffer by -calling the function `find-this-file'. By providing a prefix argument, -this function calls `filename-at-point' and switches to a buffer -visiting the file FILENAME. It creates one if none already exists. You -can use this function to edit the file mentioned in the buffer you are -working in or to test if the file exists. You can do that by using the -minibuffer completion after snatching the all or part of the filename. - - If the variable `find-file-use-truenames''s value is non-`nil', a -buffer's visited filename will always be traced back to the real file. -The filename will never be a symbolic link, and there will never be a -symbolic link anywhere in its directory path. In other words, the -`buffer-file-name' and `buffer-file-truename' will be equal. - - If the variable `find-file-compare-truenames' value is non-`nil', -the `find-file' command will check the `buffer-file-truename' of all -visited files when deciding whether a given file is already in a -buffer, instead of just `buffer-file-name'. If you attempt to visit -another file which is a hard-link or symbolic-link to a file that is -already in a buffer, the existing buffer will be found instead of a -newly created one. - - If you want to create a file, just visit it. Emacs prints `(New -File)' in the echo area, but in other respects behaves as if you had -visited an existing empty file. If you make any changes and save them, -the file is created. - - If you visit a nonexistent file unintentionally (because you typed -the wrong file name), use the `C-x C-v' (`find-alternate-file') command -to visit the file you wanted. `C-x C-v' is similar to `C-x C-f', but -it kills the current buffer (after first offering to save it if it is -modified). `C-x C-v' is allowed even if the current buffer is not -visiting a file. - - If the file you specify is actually a directory, Dired is called on -that directory (*note Dired::.). To inhibit this, set the variable -`find-file-run-dired' to `nil'; then it is an error to try to visit a -directory. - - `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that -the buffer containing the specified file is selected in another window. -The window that was selected before `C-x 4 f' continues to show the -same buffer it was already showing. If you use this command when only -one window is being displayed, that window is split in two, with one -window showing the same buffer as before, and the other one showing the -newly requested file. *Note Windows::. - - `C-x 5 C-f' (`find-file-other-frame') is like `C-x C-f' except that -it creates a new frame in which the file is displayed. - - Use the function `find-this-file-other-window' to edit a file -mentioned in the buffer you are editing or to test if that file exists. -To do this, use the minibuffer completion after snatching the part or -all of the filename. By providing a prefix argument, the function calls -`filename-at-point' and switches you to a buffer visiting the file -FILENAME in another window. The function creates a buffer if none -already exists. This function is similar to `find-file-other-window'. - - There are two hook variables that allow extensions to modify the -operation of visiting files. Visiting a file that does not exist runs -the functions in the list `find-file-not-found-hooks'; the value of this -variable is expected to be a list of functions which are called one by -one until one of them returns non-`nil'. Any visiting of a file, -whether extant or not, expects `find-file-hooks' to contain list of -functions and calls them all, one by one. In both cases the functions -receive no arguments. Visiting a nonexistent file runs the -`find-file-not-found-hooks' first. +`C-s STRING ' + Search for STRING. - -File: xemacs.info, Node: Saving, Next: Reverting, Prev: Visiting, Up: Files - -Saving Files -============ - - "Saving" a buffer in Emacs means writing its contents back into the -file that was visited in the buffer. - -`C-x C-s' - Save the current buffer in its visited file (`save-buffer'). - -`C-x s' - Save any or all buffers in their visited files - (`save-some-buffers'). - -`M-~' - Forget that the current buffer has been changed (`not-modified'). - -`C-x C-w' - Save the current buffer in a specified file, and record that file - as the one visited in the buffer (`write-file'). - -`M-x set-visited-file-name' - Change file the name under which the current buffer will be saved. - - To save a file and make your changes permanent, type `C-x C-s' -(`save-buffer'). After saving is finished, `C-x C-s' prints a message -such as: - - Wrote /u/rms/gnu/gnu.tasks - -If the selected buffer is not modified (no changes have been made in it -since the buffer was created or last saved), Emacs does not save it -because it would have no effect. Instead, `C-x C-s' prints a message -in the echo area saying: - - (No changes need to be saved) - - The command `C-x s' (`save-some-buffers') can save any or all -modified buffers. First it asks, for each modified buffer, whether to -save it. The questions should be answered with `y' or `n'. `C-x C-c', -the key that kills Emacs, invokes `save-some-buffers' and therefore -asks the same questions. - - If you have changed a buffer and do not want the changes to be saved, -you should take some action to prevent it. Otherwise, you are liable to -save it by mistake each time you use `save-some-buffers' or a related -command. One thing you can do is type `M-~' (`not-modified'), which -removes the indication that the buffer is modified. If you do this, -none of the save commands will believe that the buffer needs to be -saved. (`~' is often used as a mathematical symbol for `not'; thus -`Meta-~' is `not', metafied.) You could also use -`set-visited-file-name' (see below) to mark the buffer as visiting a -different file name, not in use for anything important. - - You can also undo all the changes made since the file was visited or -saved, by reading the text from the file again. This is called -"reverting". *Note Reverting::. Alternatively, you can undo all the -changes by repeating the undo command `C-x u'; but this only works if -you have not made more changes than the undo mechanism can remember. - - `M-x set-visited-file-name' alters the name of the file that the -current buffer is visiting. It prompts you for the new file name in the -minibuffer. You can also use `set-visited-file-name' on a buffer that -is not visiting a file. The buffer's name is changed to correspond to -the file it is now visiting unless the new name is already used by a -different buffer; in that case, the buffer name is not changed. -`set-visited-file-name' does not save the buffer in the newly visited -file; it just alters the records inside Emacs so that it will save the -buffer in that file. It also marks the buffer as "modified" so that -`C-x C-s' will save. - - If you wish to mark a buffer as visiting a different file and save it -right away, use `C-x C-w' (`write-file'). It is precisely equivalent -to `set-visited-file-name' followed by `C-x C-s'. `C-x C-s' used on a -buffer that is not visiting a file has the same effect as `C-x C-w'; -that is, it reads a file name, marks the buffer as visiting that file, -and saves it there. The default file name in a buffer that is not -visiting a file is made by combining the buffer name with the buffer's -default directory. - - If Emacs is about to save a file and sees that the date of the latest -version on disk does not match what Emacs last read or wrote, Emacs -notifies you of this fact, because it probably indicates a problem -caused by simultaneous editing and requires your immediate attention. -*Note Simultaneous Editing: Interlocking. - - If the variable `require-final-newline' is non-`nil', Emacs puts a -newline at the end of any file that doesn't already end in one, every -time a file is saved or written. - - Use the hook variable `write-file-hooks' to implement other ways to -write files, and specify things to be done before files are written. -The value of this variable should be a list of Lisp functions. When a -file is to be written, the functions in the list are called, one by -one, with no arguments. If one of them returns a non-`nil' value, Emacs -takes this to mean that the file has been written in some suitable -fashion; the rest of the functions are not called, and normal writing is -not done. Use the hook variable `after-save-hook' to list all the -functions to be called after writing out a buffer to a file. +`C-r STRING ' + Search backward for STRING. -* Menu: + To do a non-incremental search, first type `C-s ' (or `C-s +C-m'). This enters the minibuffer to read the search string. +Terminate the string with to start the search. If the string is +not found, the search command gets an error. + + By default, `C-s' invokes incremental search, but if you give it an +empty argument, which would otherwise be useless, it invokes +non-incremental search. Therefore, `C-s ' invokes non-incremental +search. `C-r ' also works this way. + + Forward and backward non-incremental searches are implemented by the +commands `search-forward' and `search-backward'. You can bind these +commands to keys. The reason that incremental search is programmed to +invoke them as well is that `C-s ' is the traditional sequence of +characters used in Emacs to invoke non-incremental search. -* Backup:: How Emacs saves the old version of your file. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. + Non-incremental searches performed using `C-s ' do not call +`search-forward' right away. They first check if the next character is +`C-w', which requests a word search. *Note Word Search::.  -File: xemacs.info, Node: Backup, Next: Interlocking, Prev: Saving, Up: Saving - -Backup Files ------------- - - Because Unix does not provide version numbers in file names, -rewriting a file in Unix automatically destroys all record of what the -file used to contain. Thus, saving a file from Emacs throws away the -old contents of the file--or it would, except that Emacs carefully -copies the old contents to another file, called the "backup" file, -before actually saving. (Make sure that the variable -`make-backup-files' is non-`nil'. Backup files are not written if this -variable is `nil'). - - At your option, Emacs can keep either a single backup file or a -series of numbered backup files for each file you edit. - - Emacs makes a backup for a file only the first time a file is saved -from one buffer. No matter how many times you save a file, its backup -file continues to contain the contents from before the file was visited. -Normally this means that the backup file contains the contents from -before the current editing session; however, if you kill the buffer and -then visit the file again, a new backup file is made by the next save. +File: xemacs.info, Node: Word Search, Next: Regexp Search, Prev: Non-Incremental Search, Up: Search -* Menu: +Word Search +=========== -* Names: Backup Names. How backup files are named; - Choosing single or numbered backup files. -* Deletion: Backup Deletion. Emacs deletes excess numbered backups. -* Copying: Backup Copying. Backups can be made by copying or renaming. + Word search looks for a sequence of words without regard to how the +words are separated. More precisely, you type a string of many words, +using single spaces to separate them, and the string is found even if +there are multiple spaces, newlines or other punctuation between the +words. - -File: xemacs.info, Node: Backup Names, Next: Backup Deletion, Prev: Backup, Up: Backup + Word search is useful in editing documents formatted by text +formatters. If you edit while looking at the printed, formatted +version, you can't tell where the line breaks are in the source file. +Word search, allows you to search without having to know the line +breaks. -Single or Numbered Backups -.......................... +`C-s C-w WORDS ' + Search for WORDS, ignoring differences in punctuation. - If you choose to have a single backup file (the default), the backup -file's name is constructed by appending `~' to the file name being -edited; thus, the backup file for `eval.c' is `eval.c~'. +`C-r C-w WORDS ' + Search backward for WORDS, ignoring differences in punctuation. - If you choose to have a series of numbered backup files, backup file -names are made by appending `.~', the number, and another `~' to the -original file name. Thus, the backup files of `eval.c' would be called -`eval.c.~1~', `eval.c.~2~', and so on, through names like -`eval.c.~259~' and beyond. + Word search is a special case of non-incremental search. It is +invoked with `C-s C-w' followed by the search string, which must +always be terminated with another . Being non-incremental, this +search does not start until the argument is terminated. It works by +constructing a regular expression and searching for that. *Note Regexp +Search::. - If protection stops you from writing backup files under the usual -names, the backup file is written as `%backup%~' in your home directory. -Only one such file can exist, so only the most recently made backup is -available. + You can do a backward word search with `C-r C-w'. - The choice of single backup or numbered backups is controlled by the -variable `version-control'. Its possible values are: + Forward and backward word searches are implemented by the commands +`word-search-forward' and `word-search-backward'. You can bind these +commands to keys. The reason that incremental search is programmed to +invoke them as well is that `C-s C-w' is the traditional Emacs +sequence of keys for word search. -`t' - Make numbered backups. + +File: xemacs.info, Node: Regexp Search, Next: Regexps, Prev: Word Search, Up: Search -`nil' - Make numbered backups for files that have numbered backups already. - Otherwise, make single backups. +Regular Expression Search +========================= -`never' - Never make numbered backups; always make single backups. + A "regular expression" ("regexp", for short) is a pattern that +denotes a (possibly infinite) set of strings. Searching for matches +for a regexp is a powerful operation that editors on Unix systems have +traditionally offered. + + To gain a thorough understanding of regular expressions and how to +use them to best advantage, we recommend that you study `Mastering +Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates, +1997'. (It's known as the "Hip Owls" book, because of the picture on its +cover.) You might also read the manuals to *Note (gawk)Top::, *Note +(ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note +(rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of +regular expressions. + + The XEmacs regular expression syntax most closely resembles that of +`ed', or `grep', the GNU versions of which all utilize the GNU `regex' +library. XEmacs' version of `regex' has recently been extended with +some Perl-like capabilities, described in the next section. + + In XEmacs, you can search for the next match for a regexp either +incrementally or not. -`version-control' may be set locally in an individual buffer to control -the making of backups for that buffer's file. For example, Rmail mode -locally sets `version-control' to `never' to make sure that there is -only one backup for an Rmail file. *Note Locals::. + Incremental search for a regexp is done by typing `M-C-s' +(`isearch-forward-regexp'). This command reads a search string +incrementally just like `C-s', but it treats the search string as a +regexp rather than looking for an exact match against the text in the +buffer. Each time you add text to the search string, you make the +regexp longer, and the new regexp is searched for. A reverse regexp +search command `isearch-backward-regexp' also exists, bound to `M-C-r'. - -File: xemacs.info, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup - -Automatic Deletion of Backups -............................. - - To prevent unlimited consumption of disk space, Emacs can delete -numbered backup versions automatically. Generally Emacs keeps the -first few backups and the latest few backups, deleting any in between. -This happens every time a new backup is made. The two variables that -control the deletion are `kept-old-versions' and `kept-new-versions'. -Their values are, respectively the number of oldest (lowest-numbered) -backups to keep and the number of newest (highest-numbered) ones to -keep, each time a new backup is made. The values are used just after a -new backup version is made; that newly made backup is included in the -count in `kept-new-versions'. By default, both variables are 2. - - If `trim-versions-without-asking' is non-`nil', excess middle -versions are deleted without notification. If it is `nil', the -default, you are asked whether the excess middle versions should really -be deleted. - - You can also use Dired's `.' (Period) command to delete old versions. -*Note Dired::. + All of the control characters that do special things within an +ordinary incremental search have the same functionality in incremental +regexp search. Typing `C-s' or `C-r' immediately after starting a +search retrieves the last incremental search regexp used: incremental +regexp and non-regexp searches have independent defaults. + + Non-incremental search for a regexp is done by the functions +`re-search-forward' and `re-search-backward'. You can invoke them with +`M-x' or bind them to keys. You can also call `re-search-forward' by +way of incremental regexp search with `M-C-s '; similarly for +`re-search-backward' with `M-C-r '.