X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-7;h=8fcc8e184b7fdb38ba7e85a2d6e693843f6ea11a;hb=478bbff714872a6032f56d1a4081a13c24d3ac66;hp=b085ba183f1baf6e07efc6e8eac8d19ca8f95042;hpb=430e0db85cc37821320fe27da9feeacc7961003f;p=chise%2Fxemacs-chise.git diff --git a/info/xemacs.info-7 b/info/xemacs.info-7 index b085ba1..8fcc8e1 100644 --- a/info/xemacs.info-7 +++ b/info/xemacs.info-7 @@ -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,1109 +30,1156 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -File: xemacs.info, Node: Backup Copying, Prev: Backup Deletion, Up: Backup - -Copying vs. Renaming -.................... - - You can make backup files by copying the old file or by renaming it. -This makes a difference when the old file has multiple names. If you -rename the old file into the backup file, the alternate names become -names for the backup file. If you copy the old file instead, the -alternate names remain names for the file that you are editing, and the -contents accessed by those names will be the new contents. - - How you make a backup file may also affect the file's owner and -group. If you use copying, they do not change. If renaming is used, -you become the file's owner, and the file's group becomes the default -(different operating systems have different defaults for the group). - - Having the owner change is usually a good idea, because then the -owner is always the person who last edited the file. Occasionally -there is a file whose owner should not change. Since most files should -change owners, it is a good idea to use local variable lists to set -`backup-by-copying-when-mismatch' for the special cases where the owner -should not change (*note File Variables::.). - - Three variables control the choice of renaming or copying. -Normally, renaming is done. If the variable `backup-by-copying' is -non-`nil', copying is used. Otherwise, if the variable -`backup-by-copying-when-linked' is non-`nil', copying is done for files -that have multiple names, but renaming may still be done when the file -being edited has only one name. If the variable -`backup-by-copying-when-mismatch' is non-`nil', copying is done if -renaming would cause the file's owner or group to change. +File: xemacs.info, Node: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search - -File: xemacs.info, Node: Interlocking, Prev: Backup, Up: Saving - -Protection Against Simultaneous Editing ---------------------------------------- - - Simultaneous editing occurs when two users visit the same file, both -make changes, and both save their changes. If no one was informed that -this was happening, and you saved first, you would later find that your -changes were lost. On some systems, Emacs notices immediately when the -second user starts to change a file already being edited, and issues a -warning. When this is not possible, or if the second user has started -to change the file despite the warning, Emacs checks when the file is -saved, and issues a second warning when a user is about to overwrite a -file containing another user's changes. If you are the user editing the -file, you can take corrective action at this point and prevent actual -loss of work. - - When you make the first modification in an Emacs buffer that is -visiting a file, Emacs records that you have locked the file. (It does -this by writing another file in a directory reserved for this purpose.) -The lock is removed when you save the changes. The idea is that the -file is locked whenever the buffer is modified. If you begin to modify -the buffer while the visited file is locked by someone else, this -constitutes a collision, and Emacs asks you what to do. It does this -by calling the Lisp function `ask-user-about-lock', which you can -redefine to customize what it does. The standard definition of this -function asks you a question and accepts three possible answers: - -`s' - Steal the lock. Whoever was already changing the file loses the - lock, and you get the lock. - -`p' - Proceed. Go ahead and edit the file despite its being locked by - someone else. - -`q' - Quit. This causes an error (`file-locked') and the modification - you were trying to make in the buffer does not actually take place. - - Note that locking works on the basis of a file name; if a file has -multiple names, Emacs does not realize that the two names are the same -file and cannot prevent two users from editing it simultaneously under -different names. However, basing locking on names means that Emacs can -interlock the editing of new files that do not really exist until they -are saved. - - Some systems are not configured to allow Emacs to make locks. On -these systems, Emacs cannot detect trouble in advance, but it can still -detect it in time to prevent you from overwriting someone else's -changes. - - Every time Emacs saves a buffer, it first checks the -last-modification date of the existing file on disk to see that it has -not changed since the file was last visited or saved. If the date does -not match, it implies that changes were made in the file in some other -way, and these changes are about to be lost if Emacs actually does -save. To prevent this, Emacs prints a warning message and asks for -confirmation before saving. Occasionally you will know why the file -was changed and know that it does not matter; then you can answer `yes' -and proceed. Otherwise, you should cancel the save with `C-g' and -investigate the situation. - - The first thing you should do when notified that simultaneous editing -has already taken place is to list the directory with `C-u C-x C-d' -(*note Directory Listing: ListDir.). This will show the file's current -author. You should attempt to contact that person and ask him not to -continue editing. Often the next step is to save the contents of your -Emacs buffer under a different name, and use `diff' to compare the two -files. - - Simultaneous editing checks are also made when you visit a file that -is already visited with `C-x C-f' and when you start to modify a file. -This is not strictly necessary, but it is useful to find out about such -a problem as early as possible, when corrective action takes less work. - - Another way to protect your file is to set the read, write, and -executable permissions for the file. Use the function -`set-default-file-modes' to set the UNIX `umask' value to the NMASK -argument. The `umask' value is the default protection mode for new -files. +Syntax of Regular Expressions +============================= - -File: xemacs.info, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files + 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 that matches that character and nothing +else. The special characters are `.', `*', `+', `?', `[', `]', `^', +`$', and `\'; no new special characters will be defined in the future. +Any other character appearing in a regular expression is ordinary, +unless a `\' precedes it. -Reverting a Buffer -================== + 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'. - If you have made extensive changes to a file and then change your -mind about them, you can get rid of all changes by reading in the -previous version of the file. To do this, use `M-x revert-buffer', -which operates on the current buffer. Since reverting a buffer can -result in very extensive changes, you must confirm it with `yes'. - - If the current buffer has been auto-saved more recently than it has -been saved explicitly, `revert-buffer' offers to read the auto save file -instead of the visited file (*note Auto Save::.). Emacs asks you about -the auto-save file before the request for confirmation of the -`revert-buffer' operation, and demands `y' or `n' as an answer. If you -have started to type `yes' for confirmation without realizing that the -auto-save question was going to be asked, the `y' will answer that -question, but the `es' will not be valid confirmation. This gives you -a chance to cancel the operation with `C-g' and try again with the -answers you really intend. - - `revert-buffer' keeps point at the same distance (measured in -characters) from the beginning of the file. If the file was edited only -slightly, you will be at approximately the same piece of text after -reverting as before. If you have made more extensive changes, the -value of point in the old file may bring you to a totally different -piece of text than your last editing point. - - A buffer reverted from its visited file is marked "not modified" -until you make a change. - - Some kinds of buffers whose contents reflect data bases other than -files, such as Dired buffers, can also be reverted. For them, -reverting means recalculating their contents from the appropriate data. -Buffers created randomly with `C-x b' cannot be reverted; -`revert-buffer' reports an error when asked to do so. + Any two regular expressions A and B can be concatenated. The result +is a regular expression that matches a string if A matches some amount +of the beginning of that string and B matches the rest of the string. - -File: xemacs.info, Node: Auto Save, Next: Version Control, Prev: Reverting, Up: Files + As a simple example, we can concatenate the regular expressions `f' +and `o' to get the regular expression `fo', which matches only the +string `fo'. Still trivial. To do something more powerful, you need +to use one of the special characters. Here is a list of them: -Auto-Saving: Protection Against Disasters -========================================= - - Emacs saves all the visited files from time to time (based on -counting your keystrokes) without being asked. This is called -"auto-saving". It prevents you from losing more than a limited amount -of work if the system crashes. - - When Emacs determines it is time for auto-saving, each buffer is -considered and is auto-saved if auto-saving is turned on for it and it -has changed since the last time it was auto-saved. If any auto-saving -is done, the message `Auto-saving...' is displayed in the echo area -until auto-saving is finished. Errors occurring during auto-saving are -caught so that they do not interfere with the execution of commands you -have been typing. +`. (Period)' + is a special character that matches any single character except a + newline. Using concatenation, we can make regular expressions + like `a.b', which matches any three-character string that begins + with `a' and ends with `b'. + +`*' + is not a construct by itself; it is a quantifying suffix operator + that means to repeat the preceding regular expression 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 matching, immediately, as + many repetitions as can be found; it is "greedy". 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, in 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. + + Nested repetition operators can be extremely slow if they specify + backtracking loops. For example, it could take hours for the + regular expression `\(x+y*\)*a' to match the sequence + `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because + Emacs must try each imaginable way of grouping the 35 `x''s before + concluding that none of them can work. To make sure your regular + expressions run fast, check nested repetitions carefully. + +`+' + is a quantifying suffix operator similar to `*' except that the + preceding expression must match at least once. It is also + "greedy". So, for example, `ca+r' matches the strings `car' and + `caaaar' but not the string `cr', whereas `ca*r' matches all three + strings. + +`?' + is a quantifying suffix operator similar to `*', except that the + preceding expression can match either once or not at all. For + example, `ca?r' matches `car' or `cr', but does not match anything + else. + +`*?' + works just like `*', except that rather than matching the longest + match, it matches the shortest match. `*?' is known as a + "non-greedy" quantifier, a regexp construct borrowed from Perl. + + This construct is very useful for when you want to match the text + inside a pair of delimiters. For instance, `/\*.*?\*/' will match + C comments in a string. This could not easily be achieved without + the use of a non-greedy quantifier. + + This construct has not been available prior to XEmacs 20.4. It is + not available in FSF Emacs. + +`+?' + is the non-greedy version of `+'. + +`??' + is the non-greedy version of `?'. + +`\{n,m\}' + serves as an interval quantifier, analogous to `*' or `+', but + specifies that the expression must match at least N times, but no + more than M times. This syntax is supported by most Unix regexp + utilities, and has been introduced to XEmacs for the version 20.3. + + Unfortunately, the non-greedy version of this quantifier does not + exist currently, although it does in Perl. + +`[ ... ]' + `[' begins a "character set", which is terminated by a `]'. In + the simplest case, the characters between the two brackets 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. + + The usual regular expression special characters are not special + inside a character set. A completely different set of special + characters exists inside character sets: `]', `-' and `^'. + + `-' is used for ranges of characters. To write a range, write 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 a period. + + To include a `]' in a character set, make it the first character. + For example, `[]a]' matches `]' or `a'. To include a `-', write + `-' as the first character in the set, or put it immediately after + a range. (You can replace one individual character C with the + range `C-C' to make a place to put the `-'.) There is no way to + write a set containing just `-' and `]'. + + To include `^' in a set, put it anywhere but at the beginning of + 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 (thus, `-' 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 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. + + When matching a string instead of a buffer, `^' matches at the + beginning of the string or after a newline character `\n'. + +`$' + is similar to `^' but matches only at the end of a line. Thus, + `x+$' matches a string of one `x' or more at the end of a line. + + When matching a string instead of a buffer, `$' matches at the end + of the string or before a newline character `\n'. + +`\' + has two functions: 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. + + *Please 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; quote the special character +anyway, regardless of where it appears. + + For the most part, `\' followed by any character matches only that +character. However, there are several exceptions: characters that, +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 that + either 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 an expression for a suffix operator such as `*' to + act on. Thus, `ba\(na\)*' matches `bananana', etc., with any + (zero or more) number of `na' strings. + + 3. To record 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 that happens to be + assigned as a second meaning to the same `\( ... \)' construct + because there is no conflict in practice between the two meanings. + Here is an explanation of this feature: + +`\DIGIT' + matches the same text that matched the DIGITth occurrence of a `\( + ... \)' construct. + + In other words, 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 match that same text, whatever it may + have been. + + The strings matching the first nine `\( ... \)' constructs + appearing in a regular expression are assigned numbers 1 through 9 + in the order that the open parentheses appear in the regular + expression. So you can use `\1' through `\9' to refer to the text + matched by the corresponding `\( ... \)' constructs. + + 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. + +`\(?: ... \)' + is called a "shy" grouping operator, and it is used just like `\( + ... \)', except that it does not cause the matched substring to be + recorded for future reference. + + This is useful when you need a lot of grouping `\( ... \)' + constructs, but only want to remember one or two - or if you have + more than nine groupings and need to use backreferences to refer to + the groupings at the end. + + Using `\(?: ... \)' rather than `\( ... \)' when you don't need + the captured substrings ought to speed up your programs some, + since it shortens the code path followed by the regular expression + engine, as well as the amount of memory allocation and string + copying it must do. The actual performance gain to be observed + has not been measured or quantified as of this writing. + + The shy grouping operator has been borrowed from Perl, and has not + been available prior to XEmacs 20.3, nor is it available in FSF + Emacs. + +`\w' + matches any word-constituent character. The editor syntax table + determines which characters these are. *Note Syntax::. + +`\W' + matches any character that is not a word constituent. + +`\sCODE' + matches any character whose syntax is CODE. Here CODE is a + character that represents a syntax code: thus, `w' for word + constituent, `-' for whitespace, `(' for open parenthesis, etc. + *Note Syntax::, for a list of syntax codes and the characters that + stand for them. + +`\SCODE' + matches any character whose syntax is not CODE. + + The following regular expression constructs match the empty +string--that is, they don't use up any characters--but whether they +match depends on the context. + +`\`' + matches the empty string, but only at the beginning of the buffer + or string being matched against. + +`\'' + matches the empty string, but only at the end of the buffer or + string being matched against. + +`\=' + matches the empty string, but only at point. (This construct is + not defined when matching against a string.) + +`\b' + matches the empty string, but only 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, but _not_ at the beginning or end of a + word. + +`\<' + matches the empty string, but only at the beginning of a word. + +`\>' + matches the empty string, but only at the end of a word. + + 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. + + "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" + +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. -* Menu: + +File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search -* Files: Auto Save Files. -* Control: Auto Save Control. -* Recover:: Recovering text from auto-save files. +Searching and Case +================== - -File: xemacs.info, Node: Auto Save Files, Next: Auto Save Control, Prev: Auto Save, Up: Auto Save - -Auto-Save Files ---------------- - - Auto-saving does not normally write to the files you visited, because -it can be undesirable to save a program that is in an inconsistent -state when you have made only half of a planned change. Instead, -auto-saving is done in a different file called the "auto-save file", -and the visited file is changed only when you save explicitly, for -example, with `C-x C-s'. - - Normally, the name of the auto-save file is generated by appending -`#' to the front and back of the visited file name. Thus, a buffer -visiting file `foo.c' would be auto-saved in a file `#foo.c#'. Most -buffers that are not visiting files are auto-saved only if you request -it explicitly; when they are auto-saved, the auto-save file name is -generated by appending `#%' to the front and `#' to the back of buffer -name. For example, the `*mail*' buffer in which you compose messages -to be sent is auto-saved in a file named `#%*mail*#'. Names of -auto-save files are generated this way unless you customize the -functions `make-auto-save-file-name' and `auto-save-file-name-p' to do -something different. The file name to be used for auto-saving a buffer -is calculated at the time auto-saving is turned on in that buffer. - - If you want auto-saving to be done in the visited file, set the -variable `auto-save-visited-file-name' to be non-`nil'. In this mode, -there is really no difference between auto-saving and explicit saving. - - Emacs deletes a buffer's auto-save file when you explicitly save the -buffer. To inhibit the deletion, set the variable -`delete-auto-save-files' to `nil'. Changing the visited file name with -`C-x C-w' or `set-visited-file-name' renames any auto-save file to -correspond to the new visited name. + 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'. - -File: xemacs.info, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save - -Controlling Auto-Saving ------------------------ - - Each time you visit a file, auto-saving is turned on for that file's -buffer if the variable `auto-save-default' is non-`nil' (but not in -batch mode; *note Entering Emacs::.). The default for this variable is -`t', so Emacs auto-saves buffers that visit files by default. You can -use the command `M-x auto-save-mode' to turn auto-saving for a buffer -on or off. Like other minor mode commands, `M-x auto-save-mode' turns -auto-saving on with a positive argument, off with a zero or negative -argument; with no argument, it toggles. - - Emacs performs auto-saving periodically based on counting how many -characters you have typed since the last time auto-saving happened. The -variable `auto-save-interval' specifies the number of characters -between auto-saves. By default, it is 300. Emacs also auto-saves -whenever you call the function `do-auto-save'. - - Emacs also does auto-saving whenever it gets a fatal error. This -includes killing the Emacs job with a shell command such as `kill --emacs', or disconnecting a phone line or network connection. - - You can set the number of seconds of idle time before an auto-save is -done. Setting the value of the variable `auto-save-timeout' to zero or -`nil' will disable auto-saving due to idleness. - - The actual amount of idle time between auto-saves is logarithmically -related to the size of the current buffer. This variable is the number -of seconds after which an auto-save will happen when the current buffer -is 50k or less; the timeout will be 2 1/4 times this in a 200k buffer, 3 -3/4 times this in a 1000k buffer, and 4 1/2 times this in a 2000k -buffer. - - For this variable to have any effect, you must do `(require 'timer)'. + 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.  -File: xemacs.info, Node: Recover, Prev: Auto Save Control, Up: Auto Save +File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search -Recovering Data from Auto-Saves -------------------------------- +Replacement Commands +==================== - If you want to use the contents of an auto-save file to recover from -a loss of data, use the command `M-x recover-file FILE '. -Emacs visits FILE and then (after your confirmation) restores the -contents from the auto-save file `#FILE#'. You can then save the file -with `C-x C-s' to put the recovered text into FILE itself. For -example, to recover file `foo.c' from its auto-save file `#foo.c#', do: + 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. - M-x recover-file foo.c - C-x C-s + 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::. - Before asking for confirmation, `M-x recover-file' displays a -directory listing describing the specified file and the auto-save file, -so you can compare their sizes and dates. If the auto-save file is -older, `M-x recover-file' does not offer to read it. +* Menu: - Auto-saving is disabled by `M-x recover-file' because using this -command implies that the auto-save file contains valuable data from a -past session. If you save the data in the visited file and then go on -to make new changes, turn auto-saving back on with `M-x auto-save-mode'. +* 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.  -File: xemacs.info, Node: Version Control, Next: ListDir, Prev: Auto Save, Up: Files +File: xemacs.info, Node: Unconditional Replace, Next: Regexp Replace, Prev: Replace, Up: Replace -Version Control -=============== +Unconditional Replacement +------------------------- - "Version control systems" are packages that can record multiple -versions of a source file, usually storing the unchanged parts of the -file just once. Version control systems also record history information -such as the creation time of each version, who created it, and a -description of what was changed in that version. +`M-x replace-string STRING NEWSTRING ' + Replace every occurrence of STRING with NEWSTRING. - The GNU project recommends the version control system known as RCS, -which is free software and available from the Free Software Foundation. -Emacs supports use of either RCS or SCCS (a proprietary, but widely -used, version control system that is not quite as powerful as RCS) -through a facility called VC. The same Emacs commands work with either -RCS or SCCS, so you hardly have to know which one of them you are using. +`M-x replace-regexp REGEXP NEWSTRING ' + Replace every match for REGEXP with NEWSTRING. -* Menu: + 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::). -* Concepts of VC:: Basic version control information; - checking files in and out. -* Editing with VC:: Commands for editing a file maintained - with version control. -* Variables for Check-in/out:: Variables that affect the commands used - to check files in or out. -* Log Entries:: Logging your changes. -* Change Logs and VC:: Generating a change log file from log - entries. -* Old Versions:: Examining and comparing old versions. -* VC Status:: Commands to view the VC status of files and - look at log entries. -* Renaming and VC:: A command to rename both the source and - master file correctly. -* Snapshots:: How to make and use snapshots, a set of - file versions that can be treated as a unit. -* Version Headers:: Inserting version control headers into - working files. + 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. - -File: xemacs.info, Node: Concepts of VC, Next: Editing with VC, Prev: Version Control, Up: Version Control + A numeric argument restricts replacement to matches that are +surrounded by word boundaries. -Concepts of Version Control ---------------------------- + +File: xemacs.info, Node: Regexp Replace, Next: Replacement and Case, Prev: Unconditional Replace, Up: Replace - When a file is under version control, we also say that it is -"registered" in the version control system. Each registered file has a -corresponding "master file" which represents the file's present state -plus its change history, so that you can reconstruct from it either the -current version or any specified earlier version. Usually the master -file also records a "log entry" for each version describing what was -changed in that version. +Regexp Replacement +------------------ - The file that is maintained under version control is sometimes called -the "work file" corresponding to its master file. + `replace-string' replaces exact matches for a single string. The +similar command `replace-regexp' replaces any match for a specified +pattern. - To examine a file, you "check it out". This extracts a version of -the source file (typically, the most recent) from the master file. If -you want to edit the file, you must check it out "locked". Only one -user can do this at a time for any given source file. (This kind of -locking is completely unrelated to the locking that Emacs uses to -detect simultaneous editing of a file.) + 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, - When you are done with your editing, you must "check in" the new -version. This records the new version in the master file, and unlocks -the source file so that other people can lock it and thus modify it. + M-x replace-regexp c[ad]+r \&-safe - Checkin and checkout are the basic operations of version control. -You can do both of them with a single Emacs command: `C-x C-q' -(`vc-toggle-read-only'). +would replace (for example) `cadr' with `cadr-safe' and `cddr' with +`cddr-safe'. - A "snapshot" is a coherent collection of versions of the various -files that make up a program. *Note Snapshots::. + M-x replace-regexp \(c[ad]+r\)-safe \1 - -File: xemacs.info, Node: Editing with VC, Next: Variables for Check-in/out, Prev: Concepts of VC, Up: Version Control - -Editing with Version Control ----------------------------- - - When you visit a file that is maintained using version control, the -mode line displays `RCS' or `SCCS' to inform you that version control -is in use, and also (in case you care) which low-level system the file -is actually stored in. Normally, such a source file is read-only, and -the mode line indicates this with `%%'. With RCS, the mode line also -indicates the number of the head version, which is normally also the -version you are looking at. - - These are the commands for editing a file maintained with version -control: - -`C-x C-q' - Check the visited file in or out. - -`C-x v u' - Revert the buffer and the file to the last checked in version. - -`C-x v c' - Remove the last-entered change from the master for the visited - file. This undoes your last check-in. - -`C-x v i' - Register the visited file in version control. - -(`C-x v' is the prefix key for version control commands; all of these -commands except for `C-x C-q' start with `C-x v'.) - - When you want to modify a file maintained with version control, type -`C-x C-q' (`vc-toggle-read-only'). This "checks out" the file, and -tells RCS or SCCS to lock the file. This means making the file -writable for you (but not for anyone else). - - When you are finished editing the file, type `C-x C-q' again. When -used on a file that is checked out, this command checks the file in. -But check-in does not start immediately; first, you must enter the "log -entry"--a description of the changes in the new version. `C-x C-q' -pops up a buffer for you to enter this in. When you are finished -typing in the log entry, type `C-c C-c' to terminate it; this is when -actual check-in takes place. - - Once you have checked in your changes, the file is unlocked, so that -other users can lock it and modify it. - - Emacs does not save backup files for source files that are maintained -with version control. If you want to make backup files despite version -control, set the variable `vc-make-backup-files' to a non-`nil' value. - - Normally the work file exists all the time, whether it is locked or -not. If you set `vc-keep-workfiles' to `nil', then checking in a new -version with `C-x C-q' deletes the work file; but any attempt to visit -the file with Emacs creates it again. - - It is not impossible to lock a file that someone else has locked. If -you try to check out a file that is locked, `C-x C-q' asks you whether -you want to "steal the lock." If you say yes, the file becomes locked -by you, but a message is sent to the person who had formerly locked the -file, to inform him of what has happened. The mode line indicates that -a file is locked by someone else by displaying the login name of that -person, before the version number. - - If you want to discard your current set of changes and revert to the -last version checked in, use `C-x v u' (`vc-revert-buffer'). This -cancels your last check-out, leaving the file unlocked. If you want to -make a different set of changes, you must first check the file out -again. `C-x v u' requires confirmation, unless it sees that you -haven't made any changes since the last checked-in version. - - `C-x v u' is also the command to use if you lock a file and then -don't actually change it. - - You can cancel a change after checking it in, with `C-x v c' -(`vc-cancel-version'). This command discards all record of the most -recent checked in version, so be careful about using it. It requires -confirmation with `yes'. By default, `C-x v c' reverts your workfile -and buffer to the previous version (the one that precedes the version -that is deleted), but you can prevent the reversion by giving the -command a prefix argument. Then the buffer does not change. - - This command with a prefix argument is useful when you have checked -in a change and then discover a trivial error in it; you can cancel the -erroneous check-in, fix the error, and repeat the check-in. - - Be careful when invoking `C-x v c', as it is easy to throw away a -lot of work with it. To help you be careful, this command always -requires confirmation with `yes'. - - You can register the visited file for version control using -`C-x v i' (`vc-register'). If the variable `vc-default-back-end' is -non-`nil', it specifies which version control system to use; otherwise, -this uses RCS if it is installed on your system and SCCS if not. After -`C-x v i', the file is unlocked and read-only. Type `C-x C-q' if you -wish to edit it. - - By default, the initial version number is 1.1. If you want to use a -different number, give `C-x v i' a prefix argument; then it reads the -initial version number using the minibuffer. - - If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial -comment (much like a log entry) to describe the purpose of this source -file. - - To specify the version number for a subsequent checkin, use the -command `C-u C-x v v'. `C-x v v' (`vc-next-action') is the command -that `C-x C-q' uses to do the "real work" when the visited file uses -version control. When used for checkin, and given a prefix argument, -it reads the version number with the minibuffer. +would perform exactly the opposite replacements. To include a `\' in +the text to replace with, you must give `\\'.  -File: xemacs.info, Node: Variables for Check-in/out, Next: Log Entries, Prev: Editing with VC, Up: Version Control - -Variables Affecting Check-in and Check-out ------------------------------------------- - - If `vc-suppress-confirm' is non-`nil', then `C-x C-q' and `C-x v i' -can save the current buffer without asking, and `C-x v u' also operates -without asking for confirmation. (This variable does not affect `C-x v -c'; that is so drastic that it should always ask for confirmation.) - - VC mode does much of its work by running the shell commands for RCS -and SCCS. If `vc-command-messages' is non-`nil', VC displays messages -to indicate which shell commands it runs, and additional messages when -the commands finish. - - Normally, VC assumes that it can deduce the locked/unlocked state of -files by looking at the file permissions of the work file; this is -fast. However, if the `RCS' or `SCCS' subdirectory is actually a -symbolic link, then VC does not trust the file permissions to reflect -this status. - - You can specify the criterion for whether to trust the file -permissions by setting the variable `vc-mistrust-permissions'. Its -value may be `t' (always mistrust the file permissions and check the -master file), `nil' (always trust the file permissions), or a function -of one argument which makes the decision. The argument is the directory -name of the `RCS' or `SCCS' subdirectory. A non-`nil' value from the -function says to mistrust the file permissions. - - If you find that the file permissions of work files are changed -erroneously, set `vc-mistrust-permissions' to `t'. Then VC always -checks the master file to determine the file's status. - - You can specify additional directories to search for version control -programs by setting the variable `vc-path'. These directories are -searched before the usual search path. The proper result usually -happens automatically. +File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace - -File: xemacs.info, Node: Log Entries, Next: Change Logs and VC, Prev: Variables for Check-in/out, Up: Version Control - -Log Entries ------------ - - When you're editing an initial comment or log entry for inclusion in -a master file, finish your entry by typing `C-c C-c'. - -`C-c C-c' - Finish the comment edit normally (`vc-finish-logentry'). This - finishes check-in. +Replace Commands and Case +------------------------- - To abort check-in, just don't type `C-c C-c' in that buffer. You -can switch buffers and do other editing. As long as you don't try to -check in another file, the entry you were editing remains in its -buffer, and you can go back to that buffer at any time to complete the -check-in. + If the arguments to a replace command are in lower case, the command +preserves case when it makes a replacement. Thus, the following +command: - If you change several source files for the same reason, it is often -convenient to specify the same log entry for many of the files. To do -this, use the history of previous log entries. The commands `M-n', -`M-p', `M-s' and `M-r' for doing this work just like the minibuffer -history commands (except that these versions are used outside the -minibuffer). + M-x replace-string foo bar - Each time you check in a file, the log entry buffer is put into VC -Log mode, which involves running two hooks: `text-mode-hook' and -`vc-log-mode-hook'. +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.  -File: xemacs.info, Node: Change Logs and VC, Next: Old Versions, Prev: Log Entries, Up: Version Control +File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace -Change Logs and VC ------------------- +Query Replace +------------- - If you use RCS for a program and also maintain a change log file for -it (*note Change Log::.), you can generate change log entries -automatically from the version control log entries: - -`C-x v a' - Visit the current directory's change log file and create new - entries for versions checked in since the most recent entry in the - change log file (`vc-update-change-log'). - - This command works with RCS only; it does not work with SCCS. - - For example, suppose the first line of `ChangeLog' is dated 10 April -1992, and that the only check-in since then was by Nathaniel Bowditch -to `rcs2log' on 8 May 1992 with log text `Ignore log messages that -start with `#'.'. Then `C-x v a' visits `ChangeLog' and inserts text -like this: - - Fri May 8 21:45:00 1992 Nathaniel Bowditch (nat@apn.org) - - * rcs2log: Ignore log messages that start with `#'. - -You can then edit the new change log entry further as you wish. - - Normally, the log entry for file `foo' is displayed as `* foo: TEXT -OF LOG ENTRY'. The `:' after `foo' is omitted if the text of the log -entry starts with `(FUNCTIONNAME): '. For example, if the log entry -for `vc.el' is `(vc-do-command): Check call-process status.', then the -text in `ChangeLog' looks like this: - - Wed May 6 10:53:00 1992 Nathaniel Bowditch (nat@apn.org) - - * vc.el (vc-do-command): Check call-process status. - - When `C-x v a' adds several change log entries at once, it groups -related log entries together if they all are checked in by the same -author at nearly the same time. If the log entries for several such -files all have the same text, it coalesces them into a single entry. -For example, suppose the most recent checkins have the following log -entries: - -For `vc.texinfo': - Fix expansion typos. -For `vc.el': - Don't call expand-file-name. -For `vc-hooks.el': - Don't call expand-file-name. - - They appear like this in `ChangeLog': - - Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org) - - * vc.texinfo: Fix expansion typos. - - * vc.el, vc-hooks.el: Don't call expand-file-name. - - Normally, `C-x v a' separates log entries by a blank line, but you -can mark several related log entries to be clumped together (without an -intervening blank line) by starting the text of each related log entry -with a label of the form `{CLUMPNAME} '. The label itself is not -copied to `ChangeLog'. For example, suppose the log entries are: - -For `vc.texinfo': - {expand} Fix expansion typos. -For `vc.el': - {expand} Don't call expand-file-name. -For `vc-hooks.el': - {expand} Don't call expand-file-name. - -Then the text in `ChangeLog' looks like this: - - Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org) - - * vc.texinfo: Fix expansion typos. - * vc.el, vc-hooks.el: Don't call expand-file-name. - - A log entry whose text begins with `#' is not copied to `ChangeLog'. -For example, if you merely fix some misspellings in comments, you can -log the change with an entry beginning with `#' to avoid putting such -trivia into `ChangeLog'. +`M-% STRING NEWSTRING ' +`M-x query-replace STRING NEWSTRING ' + Replace some occurrences of STRING with NEWSTRING. - -File: xemacs.info, Node: Old Versions, Next: VC Status, Prev: Change Logs and VC, Up: Version Control +`M-x query-replace-regexp REGEXP NEWSTRING ' + Replace some matches for REGEXP with NEWSTRING. -Examining And Comparing Old Versions ------------------------------------- + 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. -`C-x v ~ VERSION ' - Examine version VERSION of the visited file, in a buffer of its - own (`vc-version-other-window'). + Aside from querying, `query-replace' works just like +`replace-string', and `query-replace-regexp' works just like +`replace-regexp'. -`C-x v =' - Compare the current buffer contents with the latest checked-in - version of the file. + The things you can type when you are shown an occurrence of STRING +or a match for REGEXP are: -`C-u C-x v = FILE OLDVERS NEWVERS ' - Compare the specified two versions of FILE. +`' + to replace the occurrence with NEWSTRING. This preserves case, + just like `replace-string', provided `case-replace' is non-`nil', + as it normally is. - You can examine any version of a file by first visiting it, and then -using `C-x v ~ VERSION ' (`vc-version-other-window'). This puts -the text of version VERSION in a file named `FILENAME.~VERSION~', then -visits it in a separate window. +`' + to skip to the next occurrence without replacing this one. - To compare two versions of a file, use the command `C-x v =' -(`vc-diff'). +`, (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::). - Plain `C-x v =' compares the current buffer contents (saving them in -the file if necessary) with the last checked-in version of the file. -With a prefix argument, `C-x v =' reads a file name and two version -numbers, then compares those versions of the specified file. +`' + to exit without doing any more replacements. - If you supply a directory name instead of the name of a work file, -this command compares the two specified versions of all registered files -in that directory and its subdirectories. You can also specify a -snapshot name (*note Snapshots::.) instead of one or both version -numbers. +`. (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-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-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-l' + to redisplay the screen and then give another answer. + +`C-h' + to display a message summarizing these options, then give another + answer. + + 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. - You can specify a checked-in version by its number; you can specify -the most recent checked-in version with an empty version number. + +File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search - This command works by running the `vcdiff' utility, getting the -options from the variable `diff-switches'. It displays the output in a -special buffer in another window. Unlike the `M-x diff' command, `C-x -v =' does not try to find the changes in the old and new versions. -This is because one or both versions normally do not exist as files. -They exist only in the records of the master file. *Note Comparing -Files::, for more information about `M-x diff'. +Other Search-and-Loop Commands +============================== - -File: xemacs.info, Node: VC Status, Next: Renaming and VC, Prev: Old Versions, Up: Version Control + Here are some other commands that find matches for a regular +expression. They all operate from point to the end of the buffer. -VC Status Commands ------------------- +`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. - To view the detailed version control status and history of a file, -type `C-x v l' (`vc-print-log'). It displays the history of changes to -the current file, including the text of the log entries. The output -appears in a separate window. - - When you are working on a large program, it's often useful to find -all the files that are currently locked, or all the files maintained in -version control at all. You can use `C-x v d' (`vc-directory') to show -all the locked files in or beneath the current directory. This -includes all files that are locked by any user. `C-u C-x v d' lists -all files in or beneath the current directory that are maintained with -version control. - - The list of files is displayed as a buffer that uses an augmented -Dired mode. The names of the users locking various files are shown (in -parentheses) in place of the owner and group. All the normal Dired -commands work in this buffer. Most interactive VC commands work also, -and apply to the file name on the current line. - - The `C-x v v' command (`vc-next-action'), when used in the augmented -Dired buffer, operates on all the marked files (or the file on the -current line). If it operates on more than one file, it handles each -file according to its current state; thus, it may check out one file -and check in another (because it is already checked out). If it has to -check in any files, it reads a single log entry, then uses that text -for all the files being checked in. This can be convenient for -registering or checking in several files at once, as part of the same -change. + 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. - -File: xemacs.info, Node: Renaming and VC, Next: Snapshots, Prev: VC Status, Up: Version Control +`M-x list-matching-lines' + Synonym for `M-x occur'. -Renaming VC Work Files and Master Files ---------------------------------------- +`M-x count-matches' + Print the number of matches following point for the specified + regexp. - When you rename a registered file, you must also rename its master -file correspondingly to get proper results. Use `vc-rename-file' to -rename the source file as you specify, and rename its master file -accordingly. It also updates any snapshots (*note Snapshots::.) that -mention the file, so that they use the new name; despite this, the -snapshot thus modified may not completely work (*note Snapshot -Caveats::.). +`M-x delete-non-matching-lines' + Delete each line that follows point and does not contain a match + for the specified regexp. - You cannot use `vc-rename-file' on a file that is locked by someone -else. +`M-x delete-matching-lines' + Delete each line that follows point and contains a match for the + specified regexp.  -File: xemacs.info, Node: Snapshots, Next: Version Headers, Prev: Renaming and VC, Up: Version Control +File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top -Snapshots ---------- +Commands for Fixing Typos +************************* - A "snapshot" is a named set of file versions (one for each -registered file) that you can treat as a unit. One important kind of -snapshot is a "release", a (theoretically) stable version of the system -that is ready for distribution to users. + 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. * Menu: -* Making Snapshots:: The snapshot facilities. -* Snapshot Caveats:: Things to be careful of when using snapshots. +* 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.  -File: xemacs.info, Node: Making Snapshots, Next: Snapshot Caveats, Prev: Snapshots, Up: Snapshots +File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit -Making and Using Snapshots -.......................... +Killing Your Mistakes +===================== - There are two basic commands for snapshots; one makes a snapshot -with a given name, the other retrieves a named snapshot. +`' + Delete last character (`delete-backward-char'). -`C-x v s NAME ' - Define the last saved versions of every registered file in or - under the current directory as a snapshot named NAME - (`vc-create-snapshot'). +`M-' + Kill last word (`backward-kill-word'). -`C-x v r NAME ' - Check out all registered files at or below the current directory - level using whatever versions correspond to the snapshot NAME - (`vc-retrieve-snapshot'). +`C-x ' + Kill to beginning of sentence (`backward-kill-sentence'). - This command reports an error if any files are locked at or below - the current directory, without changing anything; this is to avoid - overwriting work in progress. + 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. - A snapshot uses a very small amount of resources--just enough to -record the list of file names and which version belongs to the -snapshot. Thus, you need not hesitate to create snapshots whenever -they are useful. + 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::. - You can give a snapshot name as an argument to `C-x v =' or `C-x v -~' (*note Old Versions::.). Thus, you can use it to compare a snapshot -against the current files, or two snapshots against each other, or a -snapshot against a named version. + `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.  -File: xemacs.info, Node: Snapshot Caveats, Prev: Making Snapshots, Up: Snapshots - -Snapshot Caveats -................ - - VC's snapshot facilities are modeled on RCS's named-configuration -support. They use RCS's native facilities for this, so under VC -snapshots made using RCS are visible even when you bypass VC. - - For SCCS, VC implements snapshots itself. The files it uses contain -name/file/version-number triples. These snapshots are visible only -through VC. - - A snapshot is a set of checked-in versions. So make sure that all -the files are checked in and not locked when you make a snapshot. - - File renaming and deletion can create some difficulties with -snapshots. This is not a VC-specific problem, but a general design -issue in version control systems that no one has solved very well yet. - - If you rename a registered file, you need to rename its master along -with it (the command `vc-rename-file' does this automatically). If you -are using SCCS, you must also update the records of the snapshot, to -mention the file by its new name (`vc-rename-file' does this, too). An -old snapshot that refers to a master file that no longer exists under -the recorded name is invalid; VC can no longer retrieve it. It would -be beyond the scope of this manual to explain enough about RCS and SCCS -to explain how to update the snapshots by hand. - - Using `vc-rename-file' makes the snapshot remain valid for -retrieval, but it does not solve all problems. For example, some of the -files in the program probably refer to others by name. At the very -least, the makefile probably mentions the file that you renamed. If you -retrieve an old snapshot, the renamed file is retrieved under its new -name, which is not the name that the makefile expects. So the program -won't really work as retrieved. +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: Version Headers, Prev: Snapshots, Up: Version Control - -Inserting Version Control Headers ---------------------------------- - - Sometimes it is convenient to put version identification strings -directly into working files. Certain special strings called "version -headers" are replaced in each successive version by the number of that -version. - - You can use the `C-x v h' command (`vc-insert-headers') to insert a -suitable header string. - -`C-x v h' - Insert headers in a file for use with your version-control system. - - The default header string is `\$Id\$' for RCS and `\%W\%' for SCCS. -(The actual strings inserted do not have the backslashes in them. They -were placed in the Info source file so that the strings don't get -interpreted as version-control headers when the Info source files are -maintained under version control.) You can specify other headers to -insert by setting the variable `vc-header-alist'. Its value is a list -of elements of the form `(PROGRAM . STRING)' where PROGRAM is `RCS' or -`SCCS' and STRING is the string to use. - - Instead of a single string, you can specify a list of strings; then -each string in the list is inserted as a separate header on a line of -its own. - - It is often necessary to use "superfluous" backslashes when writing -the strings that you put in this variable. This is to prevent the -string in the constant from being interpreted as a header itself if the -Emacs Lisp file containing it is maintained with version control. - - Each header is inserted surrounded by tabs, inside comment -delimiters, on a new line at the start of the buffer. Normally the -ordinary comment start and comment end strings of the current mode are -used, but for certain modes, there are special comment delimiters for -this purpose; the variable `vc-comment-alist' specifies them. Each -element of this list has the form `(MODE STARTER ENDER)'. - - The variable `vc-static-header-alist' specifies further strings to -add based on the name of the buffer. Its value should be a list of -elements of the form `(REGEXP . FORMAT)'. Whenever REGEXP matches the -buffer name, FORMAT is inserted as part of the header. A header line -is inserted for each element that matches the buffer name, and for each -string specified by `vc-header-alist'. The header line is made by -processing the string from `vc-header-alist' with the format taken from -the element. The default value for `vc-static-header-alist' is: - - (("\\.c$" . - "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ - #endif /* lint */\n")) - -which specifies insertion of a string of this form: - - - #ifndef lint - static char vcid[] = "STRING"; - #endif /* lint */ +File: xemacs.info, Node: Fixing Case, Next: Spelling, Prev: Transpose, Up: Fixit - -File: xemacs.info, Node: ListDir, Next: Comparing Files, Prev: Version Control, Up: Files +Case Conversion +=============== -Listing a File Directory -======================== +`M-- M-l' + Convert last word to lower case. Note that `Meta--' is + "Meta-minus." - Files are organized by Unix into "directories". A "directory -listing" is a list of all the files in a directory. Emacs provides -directory listings in brief format (file names only) and verbose format -(sizes, dates, and authors included). +`M-- M-u' + Convert last word to all upper case. -`C-x C-d DIR-OR-PATTERN' - Print a brief directory listing (`list-directory'). +`M-- M-c' + Convert last word to lower case with capital initial. -`C-u C-x C-d DIR-OR-PATTERN' - Print a verbose directory listing. + 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::. - To print a directory listing, use `C-x C-d' (`list-directory'). -This command prompts in the minibuffer for a file name which is either -a directory to be listed or pattern containing wildcards for the files -to be listed. For example, + +File: xemacs.info, Node: Spelling, Prev: Fixing Case, Up: Fixit - C-x C-d /u2/emacs/etc +Checking and Correcting Spelling +================================ -lists all the files in directory `/u2/emacs/etc'. An example of -specifying a file name pattern is: +`M-$' + Check and correct spelling of word (`spell-word'). - C-x C-d /u2/emacs/src/*.c +`M-x spell-buffer' + Check and correct spelling of each word in the buffer. - Normally, `C-x C-d' prints a brief directory listing containing just -file names. A numeric argument (regardless of value) tells it to print -a verbose listing (like `ls -l'). +`M-x spell-region' + Check and correct spelling of each word in the region. - Emacs obtains the text of a directory listing by running `ls' in an -inferior process. Two Emacs variables control the switches passed to -`ls': `list-directory-brief-switches' is a string giving the switches -to use in brief listings (`"-CF"' by default). -`list-directory-verbose-switches' is a string giving the switches to -use in a verbose listing (`"-l"' by default). +`M-x spell-string' + Check spelling of specified word. - The variable `directory-abbrev-alist' is an alist of abbreviations -for file directories. The list consists of elements of the form `(FROM -. TO)', each meaning to replace `FROM' with `TO' when it appears in a -directory name. This replacement is done when setting up the default -directory of a newly visited file. Every `FROM' string should start -with ``^''. + 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. - Use this feature when you have directories which you normally refer -to via absolute symbolic links. Make `TO' the name of the link, and -`FROM' the name it is linked to. + 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. - -File: xemacs.info, Node: Comparing Files, Next: Dired, Prev: ListDir, Up: Files + `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. -Comparing Files -=============== + `M-x spell-region' is similar to `spell-buffer' but operates only on +the region, not the entire buffer. - The command `M-x diff' compares two files, displaying the -differences in an Emacs buffer named `*Diff*'. It works by running the -`diff' program, using options taken from the variable `diff-switches', -whose value should be a string. - - The buffer `*Diff*' has Compilation mode as its major mode, so you -can use `C-x `' to visit successive changed locations in the two source -files. You can also move to a particular hunk of changes and type `C-c -C-c' to find the corresponding source location. You can also use the -other special commands of Compilation mode: and for -scrolling, and `M-p' and `M-n' for cursor motion. *Note Compilation::. - - The command `M-x diff-backup' compares a specified file with its most -recent backup. If you specify the name of a backup file, `diff-backup' -compares it with the source file that it is a backup of. - - The command `M-x compare-windows' compares the text in the current -window with that in the next window. Comparison starts at point in each -window. Point moves forward in each window, a character at a time in -each window, until the next characters in the two windows are -different. Then the command is finished. For more information about -windows in Emacs, *Note Windows::. - - With a numeric argument, `compare-windows' ignores changes in -whitespace. If the variable `compare-ignore-case' is non-`nil', it -ignores differences in case as well. + `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.  -File: xemacs.info, Node: Dired, Next: Misc File Ops, Prev: Comparing Files, Up: Files +File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top + +File Handling +************* -Dired, the Directory Editor -=========================== + 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. - Dired makes it easy to delete or visit many of the files in a single -directory at once. It creates an Emacs buffer containing a listing of -the directory. You can use the normal Emacs commands to move around in -this buffer and special Dired commands to operate on the files. + In addition to visiting and saving files, Emacs can delete, copy, +rename, and append to files, and operate on file directories. * Menu: -* Enter: Dired Enter. How to invoke Dired. -* Edit: Dired Edit. Editing the Dired buffer. -* Deletion: Dired Deletion. Deleting files with Dired. -* Immed: Dired Immed. Other file operations through Dired. +* 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.  -File: xemacs.info, Node: Dired Enter, Next: Dired Edit, Prev: Dired, Up: Dired +File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files + +File Names +========== + + 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. -Entering Dired --------------- + +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 symbolic link to a file that is already in a +buffer, the existing buffer will be found instead of a newly created +one. This works if any component of the pathname (including a +non-terminal component) is a symbolic link as well, but doesn't work +with hard links (nothing does). + + 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. - To invoke dired, type `C-x d' or `M-x dired'. The command reads a -directory name or wildcard file name pattern as a minibuffer argument -just like the `list-directory' command, `C-x C-d'. Where `dired' -differs from `list-directory' is in naming the buffer after the -directory name or the wildcard pattern used for the listing, and putting -the buffer into Dired mode so that the special commands of Dired are -available in it. The variable `dired-listing-switches' is a string -used as an argument to `ls' in making the directory; this string must -contain `-l'. + +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. - To display the Dired buffer in another window rather than in the -selected window, use `C-x 4 d' (`dired-other-window)' instead of `C-x -d'. +* Menu: + +* Backup:: How Emacs saves the old version of your file. +* Interlocking:: How Emacs protects against simultaneous editing + of one file by two users.  -File: xemacs.info, Node: Dired Edit, Next: Dired Deletion, Prev: Dired Enter, Up: Dired - -Editing in Dired ----------------- - - Once the Dired buffer exists, you can switch freely between it and -other Emacs buffers. Whenever the Dired buffer is selected, certain -special commands are provided that operate on files that are listed. -The Dired buffer is "read-only", and inserting text in it is not -useful, so ordinary printing characters such as `d' and `x' are used -for Dired commands. Most Dired commands operate on the file described -by the line that point is on. Some commands perform operations -immediately; others "flag" a file to be operated on later. - - Most Dired commands that operate on the current line's file also -treat a numeric argument as a repeat count, meaning to act on the files -of the next few lines. A negative argument means to operate on the -files of the preceding lines, and leave point on the first of those -lines. - - All the usual Emacs cursor motion commands are available in Dired -buffers. Some special purpose commands are also provided. The keys -`C-n' and `C-p' are redefined so that they try to position the cursor -at the beginning of the filename on the line, rather than at the -beginning of the line. - - For extra convenience, and `n' in Dired are equivalent to -`C-n'. `p' is equivalent to `C-p'. Moving by lines is done so often -in Dired that it deserves to be easy to type. (move up and -unflag) is often useful simply for moving up. - - The `g' command in Dired runs `revert-buffer' to reinitialize the -buffer from the actual disk directory and show any changes made in the -directory by programs other than Dired. All deletion flags in the Dired -buffer are lost when this is done. +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. + +* Menu: + +* 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.  -File: xemacs.info, Node: Dired Deletion, Next: Dired Immed, Prev: Dired Edit, Up: Dired +File: xemacs.info, Node: Backup Names, Next: Backup Deletion, Prev: Backup, Up: Backup -Deleting Files With Dired -------------------------- +Single or Numbered Backups +.......................... - The primary use of Dired is to flag files for deletion and then -delete them. + 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~'. -`d' - Flag this file for deletion. + 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. -`u' - Remove deletion-flag on this line. + 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. -`' - Remove deletion-flag on previous line, moving point to that line. + The choice of single backup or numbered backups is controlled by the +variable `version-control'. Its possible values are: -`x' - Delete the files that are flagged for deletion. +`t' + Make numbered backups. -`#' - Flag all auto-save files (files whose names start and end with `#') - for deletion (*note Auto Save::.). +`nil' + Make numbered backups for files that have numbered backups already. + Otherwise, make single backups. -`~' - Flag all backup files (files whose names end with `~') for deletion - (*note Backup::.). +`never' + Never make numbered backups; always make single backups. -`. (Period)' - Flag excess numeric backup files for deletion. The oldest and - newest few backup files of any one file are exempt; the middle - ones are flagged. - - You can flag a file for deletion by moving to the line describing the -file and typing `d' or `C-d'. The deletion flag is visible as a `D' at -the beginning of the line. Point is moved to the beginning of the next -line, so that repeated `d' commands flag successive files. - - The files are flagged for deletion rather than deleted immediately to -avoid the danger of deleting a file accidentally. Until you direct -Dired to delete the flagged files, you can remove deletion flags using -the commands `u' and . `u' works just like `d', but removes flags -rather than making flags. moves upward, removing flags; it is -like `u' with numeric argument automatically negated. - - To delete the flagged files, type `x'. This command first displays a -list of all the file names flagged for deletion, and requests -confirmation with `yes'. Once you confirm, all the flagged files are -deleted, and their lines are deleted from the text of the Dired buffer. -The shortened Dired buffer remains selected. If you answer `no' or -quit with `C-g', you return immediately to Dired, with the deletion -flags still present and no files actually deleted. - - The `#', `~', and `.' commands flag many files for deletion, based -on their names. These commands are useful precisely because they do -not actually delete any files; you can remove the deletion flags from -any flagged files that you really wish to keep. - - `#' flags for deletion all files that appear to have been made by -auto-saving (that is, files whose names begin and end with `#'). `~' -flags for deletion all files that appear to have been made as backups -for files that were edited (that is, files whose names end with `~'). - - `.' (Period) flags just some of the backup files for deletion: only -numeric backups that are not among the oldest few nor the newest few -backups of any one file. Normally `dired-kept-versions' (not -`kept-new-versions'; that applies only when saving) specifies the -number of newest versions of each file to keep, and `kept-old-versions' -specifies the number of oldest versions to keep. Period with a -positive numeric argument, as in `C-u 3 .', specifies the number of -newest versions to keep, overriding `dired-kept-versions'. A negative -numeric argument overrides `kept-old-versions', using minus the value -of the argument to specify the number of oldest versions of each file -to keep. +`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::.