1 This is Info file ../../info/xemacs.info, produced by Makeinfo version
2 1.68 from the input file xemacs.texi.
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: Regexp Search, Next: Regexps, Prev: Word Search, Up: Search
35 Regular Expression Search
36 =========================
38 A "regular expression" ("regexp", for short) is a pattern that
39 denotes a set of strings, possibly an infinite set. Searching for
40 matches for a regexp is a powerful operation that editors on Unix
41 systems have traditionally offered. In XEmacs, you can search for the
42 next match for a regexp either incrementally or not.
44 Incremental search for a regexp is done by typing `M-C-s'
45 (`isearch-forward-regexp'). This command reads a search string
46 incrementally just like `C-s', but it treats the search string as a
47 regexp rather than looking for an exact match against the text in the
48 buffer. Each time you add text to the search string, you make the
49 regexp longer, and the new regexp is searched for. A reverse regexp
50 search command `isearch-backward-regexp' also exists, but no key runs
53 All of the control characters that do special things within an
54 ordinary incremental search have the same functionality in incremental
55 regexp search. Typing `C-s' or `C-r' immediately after starting a
56 search retrieves the last incremental search regexp used: incremental
57 regexp and non-regexp searches have independent defaults.
59 Non-incremental search for a regexp is done by the functions
60 `re-search-forward' and `re-search-backward'. You can invoke them with
61 `M-x' or bind them to keys. You can also call `re-search-forward' by
62 way of incremental regexp search with `M-C-s <RET>'.
65 File: xemacs.info, Node: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search
67 Syntax of Regular Expressions
68 =============================
70 Regular expressions have a syntax in which a few characters are
71 special constructs and the rest are "ordinary". An ordinary character
72 is a simple regular expression which matches that character and nothing
73 else. The special characters are `$', `^', `.', `*', `+', `?', `[',
74 `]' and `\'; no new special characters will be defined. Any other
75 character appearing in a regular expression is ordinary, unless a `\'
78 For example, `f' is not a special character, so it is ordinary, and
79 therefore `f' is a regular expression that matches the string `f' and
80 no other string. (It does not match the string `ff'.) Likewise, `o'
81 is a regular expression that matches only `o'.
83 Any two regular expressions A and B can be concatenated. The result
84 is a regular expression which matches a string if A matches some amount
85 of the beginning of that string and B matches the rest of the string.
87 As a simple example, you can concatenate the regular expressions `f'
88 and `o' to get the regular expression `fo', which matches only the
89 string `fo'. To do something nontrivial, you need to use one of the
90 following special characters:
93 is a special character that matches any single character except a
94 newline. Using concatenation, you can make regular expressions
95 like `a.b', which matches any three-character string which begins
96 with `a' and ends with `b'.
99 is not a construct by itself; it is a suffix, which means the
100 preceding regular expression is to be repeated as many times as
101 possible. In `fo*', the `*' applies to the `o', so `fo*' matches
102 one `f' followed by any number of `o's. The case of zero `o's is
103 allowed: `fo*' does match `f'.
105 `*' always applies to the smallest possible preceding expression.
106 Thus, `fo*' has a repeating `o', not a repeating `fo'.
108 The matcher processes a `*' construct by immediately matching as
109 many repetitions as it can find. Then it continues with the rest
110 of the pattern. If that fails, backtracking occurs, discarding
111 some of the matches of the `*'-modified construct in case that
112 makes it possible to match the rest of the pattern. For example,
113 matching `ca*ar' against the string `caaar', the `a*' first tries
114 to match all three `a's; but the rest of the pattern is `ar' and
115 there is only `r' left to match, so this try fails. The next
116 alternative is for `a*' to match only two `a's. With this choice,
117 the rest of the regexp matches successfully.
120 is a suffix character similar to `*' except that it requires that
121 the preceding expression be matched at least once. For example,
122 `ca+r' will match the strings `car' and `caaaar' but not the
123 string `cr', whereas `ca*r' would match all three strings.
126 is a suffix character similar to `*' except that it can match the
127 preceding expression either once or not at all. For example,
128 `ca?r' will match `car' or `cr'; nothing else.
131 `[' begins a "character set", which is terminated by a `]'. In
132 the simplest case, the characters between the two form the set.
133 Thus, `[ad]' matches either one `a' or one `d', and `[ad]*'
134 matches any string composed of just `a's and `d's (including the
135 empty string), from which it follows that `c[ad]*r' matches `cr',
136 `car', `cdr', `caddaar', etc.
138 You can include character ranges in a character set by writing two
139 characters with a `-' between them. Thus, `[a-z]' matches any
140 lower-case letter. Ranges may be intermixed freely with individual
141 characters, as in `[a-z$%.]', which matches any lower-case letter
142 or `$', `%', or period.
144 Note that inside a character set the usual special characters are
145 not special any more. A completely different set of special
146 characters exists inside character sets: `]', `-', and `^'.
148 To include a `]' in a character set, you must make it the first
149 character. For example, `[]a]' matches `]' or `a'. To include a
150 `-', write `---', which is a range containing only `-'. To
151 include `^', make it other than the first character in the set.
154 `[^' begins a "complement character set", which matches any
155 character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
156 all characters except letters and digits.
158 `^' is not special in a character set unless it is the first
159 character. The character following the `^' is treated as if it
160 were first (`-' and `]' are not special there).
162 Note that a complement character set can match a newline, unless
163 newline is mentioned as one of the characters not to match.
166 is a special character that matches the empty string, but only if
167 at the beginning of a line in the text being matched. Otherwise,
168 it fails to match anything. Thus, `^foo' matches a `foo' that
169 occurs at the beginning of a line.
172 is similar to `^' but matches only at the end of a line. Thus,
173 `xx*$' matches a string of one `x' or more at the end of a line.
176 does two things: it quotes the special characters (including `\'),
177 and it introduces additional special constructs.
179 Because `\' quotes special characters, `\$' is a regular
180 expression that matches only `$', and `\[' is a regular expression
181 that matches only `[', and so on.
183 Note: for historical compatibility, special characters are treated as
184 ordinary ones if they are in contexts where their special meanings make
185 no sense. For example, `*foo' treats `*' as ordinary since there is no
186 preceding expression on which the `*' can act. It is poor practice to
187 depend on this behavior; better to quote the special character anyway,
188 regardless of where is appears.
190 Usually, `\' followed by any character matches only that character.
191 However, there are several exceptions: characters which, when preceded
192 by `\', are special constructs. Such characters are always ordinary
193 when encountered on their own. Here is a table of `\' constructs.
196 specifies an alternative. Two regular expressions A and B with
197 `\|' in between form an expression that matches anything A or B
200 Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
202 `\|' applies to the largest possible surrounding expressions.
203 Only a surrounding `\( ... \)' grouping can limit the grouping
206 Full backtracking capability exists to handle multiple uses of
210 is a grouping construct that serves three purposes:
212 1. To enclose a set of `\|' alternatives for other operations.
213 Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
215 2. To enclose a complicated expression for the postfix `*' to
216 operate on. Thus, `ba\(na\)*' matches `bananana', etc., with
217 any (zero or more) number of `na' strings.
219 3. To mark a matched substring for future reference.
222 This last application is not a consequence of the idea of a
223 parenthetical grouping; it is a separate feature which happens to
224 be assigned as a second meaning to the same `\( ... \)' construct
225 because in practice there is no conflict between the two meanings.
226 Here is an explanation:
229 after the end of a `\( ... \)' construct, the matcher remembers the
230 beginning and end of the text matched by that construct. Then,
231 later on in the regular expression, you can use `\' followed by
232 DIGIT to mean "match the same text matched the DIGIT'th time by the
233 `\( ... \)' construct."
235 The strings matching the first nine `\( ... \)' constructs
236 appearing in a regular expression are assigned numbers 1 through 9
237 in order that the open-parentheses appear in the regular
238 expression. `\1' through `\9' may be used to refer to the text
239 matched by the corresponding `\( ... \)' construct.
241 For example, `\(.*\)\1' matches any newline-free string that is
242 composed of two identical halves. The `\(.*\)' matches the first
243 half, which may be anything, but the `\1' that follows must match
247 matches the empty string, provided it is at the beginning of the
251 matches the empty string, provided it is at the end of the buffer.
254 matches the empty string, provided it is at the beginning or end
255 of a word. Thus, `\bfoo\b' matches any occurrence of `foo' as a
256 separate word. `\bballs?\b' matches `ball' or `balls' as a
260 matches the empty string, provided it is not at the beginning or
264 matches the empty string, provided it is at the beginning of a
268 matches the empty string, provided it is at the end of a word.
271 matches any word-constituent character. The editor syntax table
272 determines which characters these are.
275 matches any character that is not a word-constituent.
278 matches any character whose syntax is CODE. CODE is a character
279 which represents a syntax code: thus, `w' for word constituent,
280 `-' for whitespace, `(' for open-parenthesis, etc. *Note Syntax::.
283 matches any character whose syntax is not CODE.
285 Here is a complicated regexp used by Emacs to recognize the end of a
286 sentence together with any whitespace that follows. It is given in Lisp
287 syntax to enable you to distinguish the spaces from the tab characters.
288 In Lisp syntax, the string constant begins and ends with a
289 double-quote. `\"' stands for a double-quote as part of the regexp,
290 `\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for
293 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
295 This regexp contains four parts: a character set matching period, `?'
296 or `!'; a character set matching close-brackets, quotes or parentheses,
297 repeated any number of times; an alternative in backslash-parentheses
298 that matches end-of-line, a tab or two spaces; and a character set
299 matching whitespace characters, repeated any number of times.
302 File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search
307 All searches in Emacs normally ignore the case of the text they are
308 searching through; if you specify searching for `FOO', `Foo' and `foo'
309 are also considered a match. Regexps, and in particular character
310 sets, are included: `[aB]' matches `a' or `A' or `b' or `B'.
312 If you want a case-sensitive search, set the variable
313 `case-fold-search' to `nil'. Then all letters must match exactly,
314 including case. `case-fold-search' is a per-buffer variable; altering
315 it affects only the current buffer, but there is a default value which
316 you can change as well. *Note Locals::. You can also use Case
317 Sensitive Search from the Options menu on your screen.
320 File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search
325 Global search-and-replace operations are not needed as often in
326 Emacs as they are in other editors, but they are available. In
327 addition to the simple `replace-string' command which is like that
328 found in most editors, there is a `query-replace' command which asks
329 you, for each occurrence of a pattern, whether to replace it.
331 The replace commands all replace one string (or regexp) with one
332 replacement string. It is possible to perform several replacements in
333 parallel using the command `expand-region-abbrevs'. *Note Expanding
338 * Unconditional Replace:: Replacing all matches for a string.
339 * Regexp Replace:: Replacing all matches for a regexp.
340 * Replacement and Case:: How replacements preserve case of letters.
341 * Query Replace:: How to use querying.
344 File: xemacs.info, Node: Unconditional Replace, Next: Regexp Replace, Prev: Replace, Up: Replace
346 Unconditional Replacement
347 -------------------------
349 `M-x replace-string <RET> STRING <RET> NEWSTRING <RET>'
350 Replace every occurrence of STRING with NEWSTRING.
352 `M-x replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
353 Replace every match for REGEXP with NEWSTRING.
355 To replace every instance of `foo' after point with `bar', use the
356 command `M-x replace-string' with the two arguments `foo' and `bar'.
357 Replacement occurs only after point: if you want to cover the whole
358 buffer you must go to the beginning first. By default, all occurrences
359 up to the end of the buffer are replaced. To limit replacement to part
360 of the buffer, narrow to that part of the buffer before doing the
361 replacement (*note Narrowing::.).
363 When `replace-string' exits, point is left at the last occurrence
364 replaced. The value of point when the `replace-string' command was
365 issued is remembered on the mark ring; `C-u C-<SPC>' moves back there.
367 A numeric argument restricts replacement to matches that are
368 surrounded by word boundaries.
371 File: xemacs.info, Node: Regexp Replace, Next: Replacement and Case, Prev: Unconditional Replace, Up: Replace
376 `replace-string' replaces exact matches for a single string. The
377 similar command `replace-regexp' replaces any match for a specified
380 In `replace-regexp', the NEWSTRING need not be constant. It can
381 refer to all or part of what is matched by the REGEXP. `\&' in
382 NEWSTRING stands for the entire text being replaced. `\D' in
383 NEWSTRING, where D is a digit, stands for whatever matched the D'th
384 parenthesized grouping in REGEXP. For example,
386 M-x replace-regexp <RET> c[ad]+r <RET> \&-safe <RET>
388 would replace (for example) `cadr' with `cadr-safe' and `cddr' with
391 M-x replace-regexp <RET> \(c[ad]+r\)-safe <RET> \1 <RET>
393 would perform exactly the opposite replacements. To include a `\' in
394 the text to replace with, you must give `\\'.
397 File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace
399 Replace Commands and Case
400 -------------------------
402 If the arguments to a replace command are in lower case, the command
403 preserves case when it makes a replacement. Thus, the following
406 M-x replace-string <RET> foo <RET> bar <RET>
408 replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR',
409 and `Foo' with `Bar'. If upper-case letters are used in the second
410 argument, they remain upper-case every time that argument is inserted.
411 If upper-case letters are used in the first argument, the second
412 argument is always substituted exactly as given, with no case
413 conversion. Likewise, if the variable `case-replace' is set to `nil',
414 replacement is done without case conversion. If `case-fold-search' is
415 set to `nil', case is significant in matching occurrences of `foo' to
416 replace; also, case conversion of the replacement string is not done.
419 File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace
424 `M-% STRING <RET> NEWSTRING <RET>'
425 `M-x query-replace <RET> STRING <RET> NEWSTRING <RET>'
426 Replace some occurrences of STRING with NEWSTRING.
428 `M-x query-replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
429 Replace some matches for REGEXP with NEWSTRING.
431 If you want to change only some of the occurrences of `foo' to
432 `bar', not all of them, you can use `query-replace' instead of `M-%'.
433 This command finds occurrences of `foo' one by one, displays each
434 occurrence, and asks you whether to replace it. A numeric argument to
435 `query-replace' tells it to consider only occurrences that are bounded
436 by word-delimiter characters.
438 Aside from querying, `query-replace' works just like
439 `replace-string', and `query-replace-regexp' works just like
442 The things you can type when you are shown an occurrence of STRING
443 or a match for REGEXP are:
446 to replace the occurrence with NEWSTRING. This preserves case,
447 just like `replace-string', provided `case-replace' is non-`nil',
451 to skip to the next occurrence without replacing this one.
454 to replace this occurrence and display the result. You are then
455 prompted for another input character. However, since the
456 replacement has already been made, <DEL> and <SPC> are equivalent.
457 At this point, you can type `C-r' (see below) to alter the
458 replaced text. To undo the replacement, you can type `C-x u'.
459 This exits the `query-replace'. If you want to do further
460 replacement you must use `C-x ESC' to restart (*note
464 to exit without doing any more replacements.
467 to replace this occurrence and then exit.
470 to replace all remaining occurrences without asking again.
473 to go back to the location of the previous occurrence (or what
474 used to be an occurrence), in case you changed it by mistake.
475 This works by popping the mark ring. Only one `^' in a row is
476 allowed, because only one previous replacement location is kept
477 during `query-replace'.
480 to enter a recursive editing level, in case the occurrence needs
481 to be edited rather than just replaced with NEWSTRING. When you
482 are done, exit the recursive editing level with `C-M-c' and the
483 next occurrence will be displayed. *Note Recursive Edit::.
486 to delete the occurrence, and then enter a recursive editing level
487 as in `C-r'. Use the recursive edit to insert text to replace the
488 deleted occurrence of STRING. When done, exit the recursive
489 editing level with `C-M-c' and the next occurrence will be
493 to redisplay the screen and then give another answer.
496 to display a message summarizing these options, then give another
499 If you type any other character, Emacs exits the `query-replace', and
500 executes the character as a command. To restart the `query-replace',
501 use `C-x <ESC>', which repeats the `query-replace' because it used the
502 minibuffer to read its arguments. *Note C-x ESC: Repetition.
505 File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search
507 Other Search-and-Loop Commands
508 ==============================
510 Here are some other commands that find matches for a regular
511 expression. They all operate from point to the end of the buffer.
514 Print each line that follows point and contains a match for the
515 specified regexp. A numeric argument specifies the number of
516 context lines to print before and after each matching line; the
519 The buffer `*Occur*' containing the output serves as a menu for
520 finding occurrences in their original context. Find an occurrence
521 as listed in `*Occur*', position point there, and type `C-c C-c';
522 this switches to the buffer that was searched and moves point to
523 the original of the same occurrence.
525 `M-x list-matching-lines'
526 Synonym for `M-x occur'.
529 Print the number of matches following point for the specified
532 `M-x delete-non-matching-lines'
533 Delete each line that follows point and does not contain a match
534 for the specified regexp.
536 `M-x delete-matching-lines'
537 Delete each line that follows point and contains a match for the
541 File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top
543 Commands for Fixing Typos
544 *************************
546 This chapter describes commands that are especially useful when you
547 catch a mistake in your text just after you have made it, or when you
548 change your mind while composing text on line.
552 * Kill Errors:: Commands to kill a batch of recently entered text.
553 * Transpose:: Exchanging two characters, words, lines, lists...
554 * Fixing Case:: Correcting case of last word entered.
555 * Spelling:: Apply spelling checker to a word, or a whole file.
558 File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit
560 Killing Your Mistakes
561 =====================
564 Delete last character (`delete-backward-char').
567 Kill last word (`backward-kill-word').
570 Kill to beginning of sentence (`backward-kill-sentence').
572 The <DEL> character (`delete-backward-char') is the most important
573 correction command. When used among graphic (self-inserting)
574 characters, it can be thought of as canceling the last character typed.
576 When your mistake is longer than a couple of characters, it might be
577 more convenient to use `M-<DEL>' or `C-x <DEL>'. `M-<DEL>' kills back
578 to the start of the last word, and `C-x <DEL>' kills back to the start
579 of the last sentence. `C-x <DEL>' is particularly useful when you are
580 thinking of what to write as you type it, in case you change your mind
581 about phrasing. `M-<DEL>' and `C-x <DEL>' save the killed text for
582 `C-y' and `M-y' to retrieve. *Note Yanking::.
584 `M-<DEL>' is often useful even when you have typed only a few
585 characters wrong, if you know you are confused in your typing and aren't
586 sure exactly what you typed. At such a time, you cannot correct with
587 <DEL> except by looking at the screen to see what you did. It requires
588 less thought to kill the whole word and start over.
591 File: xemacs.info, Node: Transpose, Next: Fixing Case, Prev: Kill Errors, Up: Fixit
597 Transpose two characters (`transpose-chars').
600 Transpose two words (`transpose-words').
603 Transpose two balanced expressions (`transpose-sexps').
606 Transpose two lines (`transpose-lines').
608 The common error of transposing two adjacent characters can be fixed
609 with the `C-t' command (`transpose-chars'). Normally, `C-t' transposes
610 the two characters on either side of point. When given at the end of a
611 line, `C-t' transposes the last two characters on the line, rather than
612 transposing the last character of the line with the newline, which
613 would be useless. If you catch a transposition error right away, you
614 can fix it with just `C-t'. If you catch the error later, move the
615 cursor back to between the two transposed characters. If you
616 transposed a space with the last character of the word before it, the
617 word motion commands are a good way of getting there. Otherwise, a
618 reverse search (`C-r') is often the best way. *Note Search::.
620 `Meta-t' (`transpose-words') transposes the word before point with
621 the word after point. It moves point forward over a word, dragging the
622 word preceding or containing point forward as well. The punctuation
623 characters between the words do not move. For example, `FOO, BAR'
624 transposes into `BAR, FOO' rather than `BAR FOO,'.
626 `C-M-t' (`transpose-sexps') is a similar command for transposing two
627 expressions (*note Lists::.), and `C-x C-t' (`transpose-lines')
628 exchanges lines. It works like `M-t' but in determines the division of
629 the text into syntactic units differently.
631 A numeric argument to a transpose command serves as a repeat count:
632 it tells the transpose command to move the character (word, sexp, line)
633 before or containing point across several other characters (words,
634 sexps, lines). For example, `C-u 3 C-t' moves the character before
635 point forward across three other characters. This is equivalent to
636 repeating `C-t' three times. `C-u - 4 M-t' moves the word before point
637 backward across four words. `C-u - C-M-t' would cancel the effect of
640 A numeric argument of zero transposes the character (word, sexp,
641 line) ending after point with the one ending after the mark (otherwise a
642 command with a repeat count of zero would do nothing).
645 File: xemacs.info, Node: Fixing Case, Next: Spelling, Prev: Transpose, Up: Fixit
651 Convert last word to lower case. Note that `Meta--' is
655 Convert last word to all upper case.
658 Convert last word to lower case with capital initial.
660 A common error is to type words in the wrong case. Because of this,
661 the word case-conversion commands `M-l', `M-u', and `M-c' do not move
662 the cursor when used with a negative argument. As soon as you see you
663 have mistyped the last word, you can simply case-convert it and
664 continue typing. *Note Case::.
667 File: xemacs.info, Node: Spelling, Prev: Fixing Case, Up: Fixit
669 Checking and Correcting Spelling
670 ================================
673 Check and correct spelling of word (`spell-word').
676 Check and correct spelling of each word in the buffer.
679 Check and correct spelling of each word in the region.
682 Check spelling of specified word.
684 To check the spelling of the word before point, and optionally
685 correct it, use the command `M-$' (`spell-word'). This command runs an
686 inferior process containing the `spell' program to see whether the word
687 is correct English. If it is not, it asks you to edit the word (in the
688 minibuffer) into a corrected spelling, and then performs a
689 `query-replace' to substitute the corrected spelling for the old one
690 throughout the buffer.
692 If you exit the minibuffer without altering the original spelling, it
693 means you do not want to do anything to that word. In that case, the
694 `query-replace' is not done.
696 `M-x spell-buffer' checks each word in the buffer the same way that
697 `spell-word' does, doing a `query-replace' for every incorrect word if
700 `M-x spell-region' is similar to `spell-buffer' but operates only on
701 the region, not the entire buffer.
703 `M-x spell-string' reads a string as an argument and checks whether
704 that is a correctly spelled English word. It prints a message giving
705 the answer in the echo area.
708 File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top
713 The basic unit of stored data in Unix is the "file". To edit a file,
714 you must tell Emacs to examine the file and prepare a buffer containing
715 a copy of the file's text. This is called "visiting" the file. Editing
716 commands apply directly to text in the buffer; that is, to the copy
717 inside Emacs. Your changes appear in the file itself only when you
718 "save" the buffer back into the file.
720 In addition to visiting and saving files, Emacs can delete, copy,
721 rename, and append to files, and operate on file directories.
725 * File Names:: How to type and edit file name arguments.
726 * Visiting:: Visiting a file prepares Emacs to edit the file.
727 * Saving:: Saving makes your changes permanent.
728 * Reverting:: Reverting cancels all the changes not saved.
729 * Auto Save:: Auto Save periodically protects against loss of data.
730 * Version Control:: Version control systems (RCS and SCCS).
731 * ListDir:: Listing the contents of a file directory.
732 * Comparing Files:: Finding where two files differ.
733 * Dired:: "Editing" a directory to delete, rename, etc.
735 * Misc File Ops:: Other things you can do on files.
738 File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
743 Most Emacs commands that operate on a file require you to specify the
744 file name. (Saving and reverting are exceptions; the buffer knows which
745 file name to use for them.) File names are specified in the minibuffer
746 (*note Minibuffer::.). "Completion" is available, to make it easier to
747 specify long file names. *Note Completion::.
749 There is always a "default file name" which is used if you enter an
750 empty argument by typing just <RET>. Normally the default file name is
751 the name of the file visited in the current buffer; this makes it easy
752 to operate on that file with any of the Emacs file commands.
754 Each buffer has a default directory, normally the same as the
755 directory of the file visited in that buffer. When Emacs reads a file
756 name, the default directory is used if you do not specify a directory.
757 If you specify a directory in a relative fashion, with a name that does
758 not start with a slash, it is interpreted with respect to the default
759 directory. The default directory of the current buffer is kept in the
760 variable `default-directory', which has a separate value in every
761 buffer. The value of the variable should end with a slash.
763 For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
764 the default directory is `/u/rms/gnu/'. If you type just `foo', which
765 does not specify a directory, it is short for `/u/rms/gnu/foo'.
766 `../.login' would stand for `/u/rms/.login'. `new/foo' would stand for
767 the filename `/u/rms/gnu/new/foo'.
769 The variable `default-directory-alist' takes an alist of major modes
770 and their opinions on `default-directory' as a Lisp expression to
771 evaluate. A resulting value of `nil' is ignored in favor of
774 You can create a new directory with the function `make-directory',
775 which takes as an argument a file name string. The current directory is
776 displayed in the minibuffer when the function is called; you can delete
777 the old directory name and supply a new directory name. For example, if
778 the current directory is `/u/rms/gnu', you can delete `gnu' and type
779 `oryx' and <RET> to create `/u/rms/oryx'. Removing a directory is
780 similar to creating one. To remove a directory, use
781 `remove-directory'; it takes one argument, a file name string.
783 The command `M-x pwd' prints the current buffer's default directory,
784 and the command `M-x cd' sets it (to a value read using the
785 minibuffer). A buffer's default directory changes only when the `cd'
786 command is used. A file-visiting buffer's default directory is
787 initialized to the directory of the file that is visited there. If a
788 buffer is created with `C-x b', its default directory is copied from
789 that of the buffer that was current at the time.
791 The default directory name actually appears in the minibuffer when
792 the minibuffer becomes active to read a file name. This serves two
793 purposes: it shows you what the default is, so that you can type a
794 relative file name and know with certainty what it will mean, and it
795 allows you to edit the default to specify a different directory. To
796 inhibit the insertion of the default directory, set the variable
797 `insert-default-directory' to `nil'.
799 Note that it is legitimate to type an absolute file name after you
800 enter the minibuffer, ignoring the presence of the default directory
801 name. The final minibuffer contents may look invalid, but that is not
802 so. *Note Minibuffer File::.
804 `$' in a file name is used to substitute environment variables. For
805 example, if you have used the shell command `setenv FOO rms/hacks' to
806 set up an environment variable named `FOO', then you can use
807 `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
808 `/u/rms/hacks/test.c'. The environment variable name consists of all
809 the alphanumeric characters after the `$'; alternatively, it may be
810 enclosed in braces after the `$'. Note that the `setenv' command
811 affects Emacs only if done before Emacs is started.
813 To access a file with `$' in its name, type `$$'. This pair is
814 converted to a single `$' at the same time variable substitution is
815 performed for single `$'. The Lisp function that performs the
816 substitution is called `substitute-in-file-name'. The substitution is
817 performed only on filenames read as such using the minibuffer.
820 File: xemacs.info, Node: Visiting, Next: Saving, Prev: File Names, Up: Files
826 Visit a file (`find-file').
829 Visit a different file instead of the one visited last
830 (`find-alternate-file').
833 Visit a file, in another window (`find-file-other-window'). Don't
837 Visit a file, in another frame (`find-file-other-frame'). Don't
838 change this window or frame.
840 "Visiting" a file means copying its contents into an Emacs buffer so
841 you can edit it. Emacs creates a new buffer for each file you visit.
842 We say that the buffer is visiting the file that it was created to
843 hold. Emacs constructs the buffer name from the file name by throwing
844 away the directory and keeping just the file name. For example, a file
845 named `/usr/rms/emacs.tex' is displayed in a buffer named `emacs.tex'.
846 If a buffer with that name exists, a unique name is constructed by
847 appending `<2>', `<3>',and so on, using the lowest number that makes a
848 name that is not already in use.
850 Each window's mode line shows the name of the buffer that is being
851 displayed in that window, so you can always tell what buffer you are
854 The changes you make with Emacs are made in the Emacs buffer. They
855 do not take effect in the file that you visit, or any other permanent
856 place, until you "save" the buffer. Saving the buffer means that Emacs
857 writes the current contents of the buffer into its visited file. *Note
860 If a buffer contains changes that have not been saved, the buffer is
861 said to be "modified". This is important because it implies that some
862 changes will be lost if the buffer is not saved. The mode line displays
863 two stars near the left margin if the buffer is modified.
865 To visit a file, use the command `C-x C-f' (`find-file'). Follow
866 the command with the name of the file you wish to visit, terminated by a
867 <RET>. If you are using XEmacs under X, you can also use the Open...
868 command from the File menu bar item.
870 The file name is read using the minibuffer (*note Minibuffer::.),
871 with defaulting and completion in the standard manner (*note File
872 Names::.). While in the minibuffer, you can abort `C-x C-f' by typing
875 `C-x C-f' has completed successfully when text appears on the screen
876 and a new buffer name appears in the mode line. If the specified file
877 does not exist and could not be created or cannot be read, an error
878 results. The error message is printed in the echo area, and includes
879 the name of the file that Emacs was trying to visit.
881 If you visit a file that is already in Emacs, `C-x C-f' does not make
882 another copy. It selects the existing buffer containing that file.
883 However, before doing so, it checks that the file itself has not changed
884 since you visited or saved it last. If the file has changed, Emacs
885 prints a warning message. *Note Simultaneous Editing: Interlocking.
887 You can switch to a specific file called out in the current buffer by
888 calling the function `find-this-file'. By providing a prefix argument,
889 this function calls `filename-at-point' and switches to a buffer
890 visiting the file FILENAME. It creates one if none already exists. You
891 can use this function to edit the file mentioned in the buffer you are
892 working in or to test if the file exists. You can do that by using the
893 minibuffer completion after snatching the all or part of the filename.
895 If the variable `find-file-use-truenames''s value is non-`nil', a
896 buffer's visited filename will always be traced back to the real file.
897 The filename will never be a symbolic link, and there will never be a
898 symbolic link anywhere in its directory path. In other words, the
899 `buffer-file-name' and `buffer-file-truename' will be equal.
901 If the variable `find-file-compare-truenames' value is non-`nil',
902 the `find-file' command will check the `buffer-file-truename' of all
903 visited files when deciding whether a given file is already in a
904 buffer, instead of just `buffer-file-name'. If you attempt to visit
905 another file which is a hard-link or symbolic-link to a file that is
906 already in a buffer, the existing buffer will be found instead of a
909 If you want to create a file, just visit it. Emacs prints `(New
910 File)' in the echo area, but in other respects behaves as if you had
911 visited an existing empty file. If you make any changes and save them,
914 If you visit a nonexistent file unintentionally (because you typed
915 the wrong file name), use the `C-x C-v' (`find-alternate-file') command
916 to visit the file you wanted. `C-x C-v' is similar to `C-x C-f', but
917 it kills the current buffer (after first offering to save it if it is
918 modified). `C-x C-v' is allowed even if the current buffer is not
921 If the file you specify is actually a directory, Dired is called on
922 that directory (*note Dired::.). To inhibit this, set the variable
923 `find-file-run-dired' to `nil'; then it is an error to try to visit a
926 `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that
927 the buffer containing the specified file is selected in another window.
928 The window that was selected before `C-x 4 f' continues to show the
929 same buffer it was already showing. If you use this command when only
930 one window is being displayed, that window is split in two, with one
931 window showing the same buffer as before, and the other one showing the
932 newly requested file. *Note Windows::.
934 `C-x 5 C-f' (`find-file-other-frame') is like `C-x C-f' except that
935 it creates a new frame in which the file is displayed.
937 Use the function `find-this-file-other-window' to edit a file
938 mentioned in the buffer you are editing or to test if that file exists.
939 To do this, use the minibuffer completion after snatching the part or
940 all of the filename. By providing a prefix argument, the function calls
941 `filename-at-point' and switches you to a buffer visiting the file
942 FILENAME in another window. The function creates a buffer if none
943 already exists. This function is similar to `find-file-other-window'.
945 There are two hook variables that allow extensions to modify the
946 operation of visiting files. Visiting a file that does not exist runs
947 the functions in the list `find-file-not-found-hooks'; the value of this
948 variable is expected to be a list of functions which are called one by
949 one until one of them returns non-`nil'. Any visiting of a file,
950 whether extant or not, expects `find-file-hooks' to contain list of
951 functions and calls them all, one by one. In both cases the functions
952 receive no arguments. Visiting a nonexistent file runs the
953 `find-file-not-found-hooks' first.
956 File: xemacs.info, Node: Saving, Next: Reverting, Prev: Visiting, Up: Files
961 "Saving" a buffer in Emacs means writing its contents back into the
962 file that was visited in the buffer.
965 Save the current buffer in its visited file (`save-buffer').
968 Save any or all buffers in their visited files
969 (`save-some-buffers').
972 Forget that the current buffer has been changed (`not-modified').
975 Save the current buffer in a specified file, and record that file
976 as the one visited in the buffer (`write-file').
978 `M-x set-visited-file-name'
979 Change file the name under which the current buffer will be saved.
981 To save a file and make your changes permanent, type `C-x C-s'
982 (`save-buffer'). After saving is finished, `C-x C-s' prints a message
985 Wrote /u/rms/gnu/gnu.tasks
987 If the selected buffer is not modified (no changes have been made in it
988 since the buffer was created or last saved), Emacs does not save it
989 because it would have no effect. Instead, `C-x C-s' prints a message
990 in the echo area saying:
992 (No changes need to be saved)
994 The command `C-x s' (`save-some-buffers') can save any or all
995 modified buffers. First it asks, for each modified buffer, whether to
996 save it. The questions should be answered with `y' or `n'. `C-x C-c',
997 the key that kills Emacs, invokes `save-some-buffers' and therefore
998 asks the same questions.
1000 If you have changed a buffer and do not want the changes to be saved,
1001 you should take some action to prevent it. Otherwise, you are liable to
1002 save it by mistake each time you use `save-some-buffers' or a related
1003 command. One thing you can do is type `M-~' (`not-modified'), which
1004 removes the indication that the buffer is modified. If you do this,
1005 none of the save commands will believe that the buffer needs to be
1006 saved. (`~' is often used as a mathematical symbol for `not'; thus
1007 `Meta-~' is `not', metafied.) You could also use
1008 `set-visited-file-name' (see below) to mark the buffer as visiting a
1009 different file name, not in use for anything important.
1011 You can also undo all the changes made since the file was visited or
1012 saved, by reading the text from the file again. This is called
1013 "reverting". *Note Reverting::. Alternatively, you can undo all the
1014 changes by repeating the undo command `C-x u'; but this only works if
1015 you have not made more changes than the undo mechanism can remember.
1017 `M-x set-visited-file-name' alters the name of the file that the
1018 current buffer is visiting. It prompts you for the new file name in the
1019 minibuffer. You can also use `set-visited-file-name' on a buffer that
1020 is not visiting a file. The buffer's name is changed to correspond to
1021 the file it is now visiting unless the new name is already used by a
1022 different buffer; in that case, the buffer name is not changed.
1023 `set-visited-file-name' does not save the buffer in the newly visited
1024 file; it just alters the records inside Emacs so that it will save the
1025 buffer in that file. It also marks the buffer as "modified" so that
1026 `C-x C-s' will save.
1028 If you wish to mark a buffer as visiting a different file and save it
1029 right away, use `C-x C-w' (`write-file'). It is precisely equivalent
1030 to `set-visited-file-name' followed by `C-x C-s'. `C-x C-s' used on a
1031 buffer that is not visiting a file has the same effect as `C-x C-w';
1032 that is, it reads a file name, marks the buffer as visiting that file,
1033 and saves it there. The default file name in a buffer that is not
1034 visiting a file is made by combining the buffer name with the buffer's
1037 If Emacs is about to save a file and sees that the date of the latest
1038 version on disk does not match what Emacs last read or wrote, Emacs
1039 notifies you of this fact, because it probably indicates a problem
1040 caused by simultaneous editing and requires your immediate attention.
1041 *Note Simultaneous Editing: Interlocking.
1043 If the variable `require-final-newline' is non-`nil', Emacs puts a
1044 newline at the end of any file that doesn't already end in one, every
1045 time a file is saved or written.
1047 Use the hook variable `write-file-hooks' to implement other ways to
1048 write files, and specify things to be done before files are written.
1049 The value of this variable should be a list of Lisp functions. When a
1050 file is to be written, the functions in the list are called, one by
1051 one, with no arguments. If one of them returns a non-`nil' value, Emacs
1052 takes this to mean that the file has been written in some suitable
1053 fashion; the rest of the functions are not called, and normal writing is
1054 not done. Use the hook variable `after-save-hook' to list all the
1055 functions to be called after writing out a buffer to a file.
1059 * Backup:: How Emacs saves the old version of your file.
1060 * Interlocking:: How Emacs protects against simultaneous editing
1061 of one file by two users.
1064 File: xemacs.info, Node: Backup, Next: Interlocking, Prev: Saving, Up: Saving
1069 Because Unix does not provide version numbers in file names,
1070 rewriting a file in Unix automatically destroys all record of what the
1071 file used to contain. Thus, saving a file from Emacs throws away the
1072 old contents of the file--or it would, except that Emacs carefully
1073 copies the old contents to another file, called the "backup" file,
1074 before actually saving. (Make sure that the variable
1075 `make-backup-files' is non-`nil'. Backup files are not written if this
1078 At your option, Emacs can keep either a single backup file or a
1079 series of numbered backup files for each file you edit.
1081 Emacs makes a backup for a file only the first time a file is saved
1082 from one buffer. No matter how many times you save a file, its backup
1083 file continues to contain the contents from before the file was visited.
1084 Normally this means that the backup file contains the contents from
1085 before the current editing session; however, if you kill the buffer and
1086 then visit the file again, a new backup file is made by the next save.
1090 * Names: Backup Names. How backup files are named;
1091 Choosing single or numbered backup files.
1092 * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
1093 * Copying: Backup Copying. Backups can be made by copying or renaming.
1096 File: xemacs.info, Node: Backup Names, Next: Backup Deletion, Prev: Backup, Up: Backup
1098 Single or Numbered Backups
1099 ..........................
1101 If you choose to have a single backup file (the default), the backup
1102 file's name is constructed by appending `~' to the file name being
1103 edited; thus, the backup file for `eval.c' is `eval.c~'.
1105 If you choose to have a series of numbered backup files, backup file
1106 names are made by appending `.~', the number, and another `~' to the
1107 original file name. Thus, the backup files of `eval.c' would be called
1108 `eval.c.~1~', `eval.c.~2~', and so on, through names like
1109 `eval.c.~259~' and beyond.
1111 If protection stops you from writing backup files under the usual
1112 names, the backup file is written as `%backup%~' in your home directory.
1113 Only one such file can exist, so only the most recently made backup is
1116 The choice of single backup or numbered backups is controlled by the
1117 variable `version-control'. Its possible values are:
1120 Make numbered backups.
1123 Make numbered backups for files that have numbered backups already.
1124 Otherwise, make single backups.
1127 Never make numbered backups; always make single backups.
1129 `version-control' may be set locally in an individual buffer to control
1130 the making of backups for that buffer's file. For example, Rmail mode
1131 locally sets `version-control' to `never' to make sure that there is
1132 only one backup for an Rmail file. *Note Locals::.
1135 File: xemacs.info, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup
1137 Automatic Deletion of Backups
1138 .............................
1140 To prevent unlimited consumption of disk space, Emacs can delete
1141 numbered backup versions automatically. Generally Emacs keeps the
1142 first few backups and the latest few backups, deleting any in between.
1143 This happens every time a new backup is made. The two variables that
1144 control the deletion are `kept-old-versions' and `kept-new-versions'.
1145 Their values are, respectively the number of oldest (lowest-numbered)
1146 backups to keep and the number of newest (highest-numbered) ones to
1147 keep, each time a new backup is made. The values are used just after a
1148 new backup version is made; that newly made backup is included in the
1149 count in `kept-new-versions'. By default, both variables are 2.
1151 If `trim-versions-without-asking' is non-`nil', excess middle
1152 versions are deleted without notification. If it is `nil', the
1153 default, you are asked whether the excess middle versions should really
1156 You can also use Dired's `.' (Period) command to delete old versions.
projects / chise / xemacs-chise.git.1 / blob