X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-8;h=81ad49cac2522225809eccdc43137e3d77dc7741;hb=16d0840d3eada757f529c34fddc0c2fb8f17b9de;hp=7f8258ba200119daa42d957073fabda623a1a446;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git diff --git a/info/xemacs.info-8 b/info/xemacs.info-8 index 7f8258b..81ad49c 100644 --- a/info/xemacs.info-8 +++ b/info/xemacs.info-8 @@ -1,4 +1,4 @@ -This is ../info/xemacs.info, produced by makeinfo version 3.12s from +This is ../info/xemacs.info, produced by makeinfo version 4.0b from xemacs/xemacs.texi. INFO-DIR-SECTION XEmacs Editor @@ -30,1039 +30,1057 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -File: xemacs.info, Node: Dired Immed, Prev: Dired Deletion, Up: Dired +File: xemacs.info, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup -Immediate File Operations in Dired ----------------------------------- +Automatic Deletion of Backups +............................. - Some file operations in Dired take place immediately when they are -requested. + To prevent unlimited consumption of disk space, Emacs can delete +numbered backup versions automatically. Generally Emacs keeps the +first few backups and the latest few backups, deleting any in between. +This happens every time a new backup is made. The two variables that +control the deletion are `kept-old-versions' and `kept-new-versions'. +Their values are, respectively the number of oldest (lowest-numbered) +backups to keep and the number of newest (highest-numbered) ones to +keep, each time a new backup is made. The values are used just after a +new backup version is made; that newly made backup is included in the +count in `kept-new-versions'. By default, both variables are 2. -`C' - Copies the file described on the current line. You must supply a - file name to copy to, using the minibuffer. + If `delete-old-versions' is non-`nil', excess middle versions are +deleted without notification. If it is `nil', the default, you are +asked whether the excess middle versions should really be deleted. -`f' - Visits the file described on the current line. It is just like - typing `C-x C-f' and supplying that file name. If the file on - this line is a subdirectory, `f' actually causes Dired to be - invoked on that subdirectory. *Note Visiting::. + You can also use Dired's `.' (Period) command to delete old versions. +*Note Dired::. -`o' - Like `f', but uses another window to display the file's buffer. - The Dired buffer remains visible in the first window. This is - like using `C-x 4 C-f' to visit the file. *Note Windows::. + +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: 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: -`R' - Renames the file described on the current line. You must supply a - file name to rename to, using the minibuffer. +`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. -`v' - Views the file described on this line using `M-x view-file'. - Viewing a file is like visiting it, but is slanted toward moving - around in the file conveniently and does not allow changing the - file. *Note View File: Misc File Ops. Viewing a file that is a - directory runs Dired on that directory. +`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.  -File: xemacs.info, Node: Misc File Ops, Prev: Dired, Up: Files - -Miscellaneous File Operations -============================= - - Emacs has commands for performing many other operations on files. -All operate on one file; they do not accept wildcard file names. - - You can use the command `M-x add-name-to-file' to add a name to an -existing file without removing the old name. The new name must belong -on the file system that the file is on. - - `M-x append-to-file' adds the text of the region to the end of the -specified file. - - `M-x copy-file' reads the file OLD and writes a new file named NEW -with the same contents. Confirmation is required if a file named NEW -already exists, because copying overwrites the old contents of the file -NEW. - - `M-x delete-file' deletes a specified file, like the `rm' command in -the shell. If you are deleting many files in one directory, it may be -more convenient to use Dired (*note Dired::). - - `M-x insert-file' inserts a copy of the contents of a specified file -into the current buffer at point, leaving point unchanged before the -contents and the mark after them. *Note Mark::. - - `M-x make-symbolic-link' reads two file names OLD and LINKNAME, and -then creates a symbolic link named LINKNAME and pointing at OLD. -Future attempts to open file LINKNAME will then refer to the file named -OLD at the time the opening is done, or will result in an error if the -name OLD is not in use at that time. Confirmation is required if you -create the link while LINKNAME is in use. Note that not all systems -support symbolic links. - - `M-x rename-file' reads two file names OLD and NEW using the -minibuffer, then renames file OLD as NEW. If a file named NEW already -exists, you must confirm with `yes' or renaming is not done; this is -because renaming causes the previous meaning of the name NEW to be -lost. If OLD and NEW are on different file systems, the file OLD is -copied and deleted. - - `M-x view-file' allows you to scan or read a file by sequential -screenfuls. It reads a file name argument using the minibuffer. After -reading the file into an Emacs buffer, `view-file' reads and displays -one windowful. You can then type to scroll forward one window, -or to scroll backward. Various other commands are provided for -moving around in the file, but none for changing it; type `C-h' while -viewing a file for a list of them. Most commands are the default Emacs -cursor motion commands. To exit from viewing, type `C-c'. +File: xemacs.info, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files + +Reverting a Buffer +================== + + 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.  -File: xemacs.info, Node: Buffers, Next: Windows, Prev: Files, Up: Top - -Using Multiple Buffers -********************** - - Text you are editing in Emacs resides in an object called a -"buffer". Each time you visit a file, Emacs creates a buffer to hold -the file's text. Each time you invoke Dired, Emacs creates a buffer to -hold the directory listing. If you send a message with `C-x m', a -buffer named `*mail*' is used to hold the text of the message. When -you ask for a command's documentation, it appears in a buffer called -`*Help*'. - - At any time, one and only one buffer is "selected". It is also -called the "current buffer". Saying a command operates on "the buffer" -really means that the command operates on the selected buffer, as most -commands do. - - When Emacs creates multiple windows, each window has a chosen buffer -which is displayed there, but at any time only one of the windows is -selected and its chosen buffer is the selected buffer. Each window's -mode line displays the name of the buffer the window is displaying -(*note Windows::). - - Each buffer has a name which can be of any length but is -case-sensitive. You can select a buffer using its name. Most buffers -are created when you visit files; their names are derived from the -files' names. You can also create an empty buffer with any name you -want. A newly started Emacs has a buffer named `*scratch*' which you -can use for evaluating Lisp expressions in Emacs. - - Each buffer records what file it is visiting, whether it is -modified, and what major mode and minor modes are in effect in it -(*note Major Modes::). Any Emacs variable can be made "local to" a -particular buffer, meaning its value in that buffer can be different -from the value in other buffers. *Note Locals::. +File: xemacs.info, Node: Auto Save, Next: Version Control, Prev: Reverting, Up: Files -* Menu: +Auto-Saving: Protection Against Disasters +========================================= -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onliness; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. + 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. - -File: xemacs.info, Node: Select Buffer, Next: List Buffers, Prev: Buffers, Up: Buffers + 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. + +* Menu: -Creating and Selecting Buffers -============================== +* Files: Auto Save Files. +* Control: Auto Save Control. +* Recover:: Recovering text from auto-save files. -`C-x b BUFFER ' - Select or create a buffer named BUFFER (`switch-to-buffer'). + +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. -`C-x 4 b BUFFER ' - Similar, but select a buffer named BUFFER in another window - (`switch-to-buffer-other-window'). + +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)'. -`M-x switch-to-other-buffer N' - Switch to the previous buffer. + +File: xemacs.info, Node: Recover, Prev: Auto Save Control, Up: Auto Save - To select a buffer named BUFNAME, type `C-x b BUFNAME '. This -is the command `switch-to-buffer' with argument BUFNAME. You can use -completion on an abbreviation for the buffer name you want (*note -Completion::). An empty argument to `C-x b' specifies the most -recently selected buffer that is not displayed in any window. +Recovering Data from Auto-Saves +------------------------------- - Most buffers are created when you visit files, or use Emacs commands -that display text. You can also create a buffer explicitly by typing -`C-x b BUFNAME ', which creates a new, empty buffer that is not -visiting any file, and selects it for editing. The new buffer's major -mode is determined by the value of `default-major-mode' (*note Major -Modes::). Buffers not visiting files are usually used for making notes -to yourself. If you try to save one, you are asked for the file name -to use. + 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: - The function `switch-to-buffer-other-frame' is similar to -`switch-to-buffer' except that it creates a new frame in which to -display the selected buffer. + M-x recover-file foo.c + C-x C-s - Use `M-x switch-to-other-buffer' to visit the previous buffer. If -you supply a positive integer N, the Nth most recent buffer is -displayed. If you supply an argument of 0, the current buffer is moved -to the bottom of the buffer stack. + 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. - Note that you can also use `C-x C-f' and any other command for -visiting a file to switch buffers. *Note Visiting::. + 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'.  -File: xemacs.info, Node: List Buffers, Next: Misc Buffer, Prev: Select Buffer, Up: Buffers +File: xemacs.info, Node: Version Control, Next: ListDir, Prev: Auto Save, Up: Files -Listing Existing Buffers -======================== +Version Control +=============== -`C-x C-b' - List the existing buffers (`list-buffers'). - - To print a list of all existing buffers, type `C-x C-b'. Each line -in the list shows one buffer's name, major mode, and visited file. A -`*' at the beginning of a line indicates the buffer has been -"modified". If several buffers are modified, it may be time to save -some with `C-x s' (*note Saving::). A `%' indicates a read-only -buffer. A `.' marks the selected buffer. Here is an example of a -buffer list: - - MR Buffer Size Mode File - -- ------ ---- ---- ---- - .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex - *Help* 1287 Fundamental - files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el - % RMAIL 64042 RMAIL /u/rms/RMAIL - *% man 747 Dired /u2/emacs/man/ - net.emacs 343885 Fundamental /u/rms/net.emacs - fileio.c 27691 C /u2/emacs/src/fileio.c - NEWS 67340 Text /u2/emacs/etc/NEWS - *scratch* 0 Lisp Interaction - -Note that the buffer `*Help*' was made by a help request; it is not -visiting any file. The buffer `man' was made by Dired on the directory -`/u2/emacs/man/'. - - As you move the mouse over the `*Buffer List*' buffer, the lines are -highlighted. This visual cue indicates that clicking the right mouse -button (`button3') will pop up a menu of commands on the buffer -represented by this line. This menu duplicates most of those commands -which are bound to keys in the `*Buffer List*' buffer. + "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. - -File: xemacs.info, Node: Misc Buffer, Next: Kill Buffer, Prev: List Buffers, Up: Buffers + 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. -Miscellaneous Buffer Operations -=============================== +* Menu: -`C-x C-q' - Toggle read-only status of buffer (`toggle-read-only'). - -`M-x rename-buffer' - Change the name of the current buffer. - -`M-x view-buffer' - Scroll through a buffer. - - A buffer can be "read-only", which means that commands to change its -text are not allowed. Normally, read-only buffers are created by -subsystems such as Dired and Rmail that have special commands to operate -on the text. Emacs also creates a read-only buffer if you visit a file -that is protected. To make changes in a read-only buffer, use the -command `C-x C-q' (`toggle-read-only'). It makes a read-only buffer -writable, and makes a writable buffer read-only. This works by setting -the variable `buffer-read-only', which has a local value in each buffer -and makes a buffer read-only if its value is non-`nil'. - - `M-x rename-buffer' changes the name of the current buffer, -prompting for the new name in the minibuffer. There is no default. If -you specify a name that is used by a different buffer, an error is -signalled and renaming is not done. - - `M-x view-buffer' is similar to `M-x view-file' (*note Misc File -Ops::), but it examines an already existing Emacs buffer. View mode -provides convenient commands for scrolling through the buffer but not -for changing it. When you exit View mode, the resulting value of point -remains in effect. - - To copy text from one buffer to another, use the commands `M-x -append-to-buffer' and `M-x insert-buffer'. *Note Accumulating Text::. +* 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.  -File: xemacs.info, Node: Kill Buffer, Next: Several Buffers, Prev: Misc Buffer, Up: Buffers +File: xemacs.info, Node: Concepts of VC, Next: Editing with VC, Prev: Version Control, Up: Version Control -Killing Buffers -=============== +Concepts of Version Control +--------------------------- + + 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. - After using Emacs for a while, you may accumulate a large number of -buffers and may want to eliminate the ones you no longer need. There -are several commands for doing this. + The file that is maintained under version control is sometimes called +the "work file" corresponding to its master file. -`C-x k' - Kill a buffer, specified by name (`kill-buffer'). + 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.) -`M-x kill-some-buffers' - Offer to kill each buffer, one by one. + 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. - `C-x k' (`kill-buffer') kills one buffer, whose name you specify in -the minibuffer. If you type just in the minibuffer, the default, -killing the current buffer, is used. If the current buffer is killed, -the buffer that has been selected recently but does not appear in any -window now is selected. If the buffer being killed contains unsaved -changes, you are asked to confirm with `yes' before the buffer is -killed. + 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'). - The command `M-x kill-some-buffers' asks about each buffer, one by -one. An answer of `y' means to kill the buffer. Killing the current -buffer or a buffer containing unsaved changes selects a new buffer or -asks for confirmation just like `kill-buffer'. + A "snapshot" is a coherent collection of versions of the various +files that make up a program. *Note Snapshots::.  -File: xemacs.info, Node: Several Buffers, Prev: Kill Buffer, Up: Buffers +File: xemacs.info, Node: Editing with VC, Next: Variables for Check-in/out, Prev: Concepts of VC, Up: Version Control -Operating on Several Buffers -============================ +Editing with Version Control +---------------------------- - The "buffer-menu" facility is like a "Dired for buffers"; it allows -you to request operations on various Emacs buffers by editing a buffer -containing a list of them. You can save buffers, kill them (here -called "deleting" them, for consistency with Dired), or display them. + 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. -`M-x buffer-menu' - Begin editing a buffer listing all Emacs buffers. + These are the commands for editing a file maintained with version +control: - The command `buffer-menu' writes a list of all Emacs buffers into -the buffer `*Buffer List*', and selects that buffer in Buffer Menu -mode. The buffer is read-only. You can only change it using the -special commands described in this section. Most of the commands are -graphic characters. You can use Emacs cursor motion commands in the -`*Buffer List*' buffer. If the cursor is on a line describing a -buffer, the following special commands apply to that buffer: +`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. -`d' - Request to delete (kill) the buffer, then move down. A `D' before - the buffer name on a line indicates a deletion request. Requested - deletions actually take place when you use the `x' command. + +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. -`k' - Synonym for `d'. + +File: xemacs.info, Node: Log Entries, Next: Change Logs and VC, Prev: Variables for Check-in/out, Up: Version Control -`C-d' - Like `d' but move up afterwards instead of down. +Log Entries +----------- -`s' - Request to save the buffer. An `S' befor the buffer name on a line - indicates the request. Requested saves actually take place when - you use the `x' command. You can request both saving and deletion - for the same buffer. + 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'. -`~' - Mark buffer "unmodified". The command `~' does this immediately - when typed. +`C-c C-c' + Finish the comment edit normally (`vc-finish-logentry'). This + finishes check-in. -`x' - Perform previously requested deletions and saves. + 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. -`u' - Remove any request made for the current line, and move down. + 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). -`' - Move to previous line and remove any request made for that line. + 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'. - All commands that add or remove flags to request later operations -also move down a line. They accept a numeric argument as a repeat -count, unless otherwise specified. + +File: xemacs.info, Node: Change Logs and VC, Next: Old Versions, Prev: Log Entries, Up: Version Control + +Change Logs and VC +------------------ + + 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'. - There are also special commands to use the buffer list to select -another buffer, and to specify one or more other buffers for display in -additional windows. + +File: xemacs.info, Node: Old Versions, Next: VC Status, Prev: Change Logs and VC, Up: Version Control -`1' - Select the buffer in a full-frame window. This command takes - effect immediately. +Examining And Comparing Old Versions +------------------------------------ -`2' - Immediately set up two windows, with this buffer in one and the - buffer selected before `*Buffer List*' in the other. +`C-x v ~ VERSION ' + Examine version VERSION of the visited file, in a buffer of its + own (`vc-version-other-window'). -`f' - Immediately select the buffer in place of the `*Buffer List*' - buffer. +`C-x v =' + Compare the current buffer contents with the latest checked-in + version of the file. -`o' - Immediately select the buffer in another window as if by `C-x 4 b', - leaving `*Buffer List*' visible. +`C-u C-x v = FILE OLDVERS NEWVERS ' + Compare the specified two versions of FILE. -`q' - Immediately select this buffer, and display any buffers previously - flagged with the `m' command in other windows. If there are no - buffers flagged with `m', this command is equivalent to `1'. - -`m' - Flag this buffer to be displayed in another window if the `q' - command is used. The request shows as a `>' at the beginning of - the line. The same buffer may not have both a delete request and a - display request. - - Going back between a `buffer-menu' buffer and other Emacs buffers is -easy. You can, for example, switch from the `*Buffer List*' buffer to -another Emacs buffer, and edit there. You can then reselect the -`buffer-menu' buffer and perform operations already requested, or you -can kill that buffer or pay no further attention to it. All that -`buffer-menu' does directly is create and select a suitable buffer, and -turn on Buffer Menu mode. All the other capabilities of the buffer -menu are implemented by special commands provided in Buffer Menu mode. - - The only difference between `buffer-menu' and `list-buffers' is that -`buffer-menu' selects the `*Buffer List*' buffer and `list-buffers' -does not. If you run `list-buffers' (that is, type `C-x C-b') and -select the buffer list manually, you can use all the commands described -here. + 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. - -File: xemacs.info, Node: Windows, Next: Mule, Prev: Buffers, Up: Top + To compare two versions of a file, use the command `C-x v =' +(`vc-diff'). -Multiple Windows -**************** + 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. - Emacs can split the frame into two or many windows, which can display -parts of different buffers or different parts of one buffer. If you are -running XEmacs under X, that means you can have the X window that -contains the Emacs frame have multiple subwindows. + 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. -* Menu: + You can specify a checked-in version by its number; you can specify +the most recent checked-in version with an empty version number. -* Basic Window:: Introduction to Emacs windows. -* Split Window:: New windows are made by splitting existing windows. -* Other Window:: Moving to another window or doing something to it. -* Pop Up Window:: Finding a file or buffer in another window. -* Change Window:: Deleting windows and changing their sizes. + 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'.  -File: xemacs.info, Node: Basic Window, Next: Split Window, Prev: Windows, Up: Windows - -Concepts of Emacs Windows -========================= - - When Emacs displays multiple windows, each window has one Emacs -buffer designated for display. The same buffer may appear in more than -one window; if it does, any changes in its text are displayed in all -the windows that display it. Windows showing the same buffer can show -different parts of it, because each window has its own value of point. - - At any time, one window is the "selected window"; the buffer -displayed by that window is the current buffer. The cursor shows the -location of point in that window. Each other window has a location of -point as well, but since the terminal has only one cursor, it cannot -show the location of point in the other windows. - - Commands to move point affect the value of point for the selected -Emacs window only. They do not change the value of point in any other -Emacs window, including those showing the same buffer. The same is -true for commands such as `C-x b' to change the selected buffer in the -selected window; they do not affect other windows at all. However, -there are other commands such as `C-x 4 b' that select a different -window and switch buffers in it. Also, all commands that display -information in a window, including (for example) `C-h f' -(`describe-function') and `C-x C-b' (`list-buffers'), work by switching -buffers in a non-selected window without affecting the selected window. - - Each window has its own mode line, which displays the buffer name, -modification status, and major and minor modes of the buffer that is -displayed in the window. *Note Mode Line::, for details on the mode -line. +File: xemacs.info, Node: VC Status, Next: Renaming and VC, Prev: Old Versions, Up: Version Control + +VC Status Commands +------------------ + + 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.  -File: xemacs.info, Node: Split Window, Next: Other Window, Prev: Basic Window, Up: Windows - -Splitting Windows -================= - -`C-x 2' - Split the selected window into two windows, one above the other - (`split-window-vertically'). - -`C-x 3' - Split the selected window into two windows positioned side by side - (`split-window-horizontally'). - -`C-x 6' - Save the current window configuration in register REG (a letter). - -`C-x 7' - Restore (make current) the window configuration in register REG (a - letter). Use with a register previously set with `C-x 6'. - - The command `C-x 2' (`split-window-vertically') breaks the selected -window into two windows, one above the other. Both windows start out -displaying the same buffer, with the same value of point. By default -each of the two windows gets half the height of the window that was -split. A numeric argument specifies how many lines to give to the top -window. - - `C-x 3' (`split-window-horizontally') breaks the selected window -into two side-by-side windows. A numeric argument specifies how many -columns to give the one on the left. A line of vertical bars separates -the two windows. Windows that are not the full width of the frame have -truncated mode lines which do not always appear in inverse video, -because Emacs display routines cannot display a region of inverse video -that is only part of a line on the screen. - - When a window is less than the full width, many text lines are too -long to fit. Continuing all those lines might be confusing. Set the -variable `truncate-partial-width-windows' to non-`nil' to force -truncation in all windows less than the full width of the frame, -independent of the buffer and its value for `truncate-lines'. *Note -Continuation Lines::. - - Horizontal scrolling is often used in side-by-side windows. *Note -Display::. - - You can resize a window and store that configuration in a register by -supplying a REGISTER argument to `window-configuration-to-register' -(`C-x 6'). To return to the window configuration established with -`window-configuration-to-register', use `jump-to-register' (`C-x j'). +File: xemacs.info, Node: Renaming and VC, Next: Snapshots, Prev: VC Status, Up: Version Control + +Renaming VC Work Files and Master Files +--------------------------------------- + + 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::). + + You cannot use `vc-rename-file' on a file that is locked by someone +else.  -File: xemacs.info, Node: Other Window, Next: Pop Up Window, Prev: Split Window, Up: Windows - -Using Other Windows -=================== - -`C-x o' - Select another window (`other-window'). That is the letter `o', - not zero. - -`M-C-v' - Scroll the next window (`scroll-other-window'). - -`M-x compare-windows' - Find the next place where the text in the selected window does not - match the text in the next window. - -`M-x other-window-any-frame N' - Select the Nth different window on any frame. - - To select a different window, use `C-x o' (`other-window'). That is -an `o', for `other', not a zero. When there are more than two windows, -the command moves through all the windows in a cyclic order, generally -top to bottom and left to right. From the rightmost and bottommost -window, it goes back to the one at the upper left corner. A numeric -argument, N, moves several steps in the cyclic order of windows. A -negative numeric argument moves around the cycle in the opposite order. -If the optional second argument ALL-FRAMES is non-`nil', the function -cycles through all frames. When the minibuffer is active, the -minibuffer is the last window in the cycle; you can switch from the -minibuffer window to one of the other windows, and later switch back -and finish supplying the minibuffer argument that is requested. *Note -Minibuffer Edit::. - - The command `M-x other-window-any-frame' also selects the window N -steps away in the cyclic order. However, unlike `other-window', this -command selects a window on the next or previous frame instead of -wrapping around to the top or bottom of the current frame, when there -are no more windows. - - The usual scrolling commands (*note Display::) apply to the selected -window only. `M-C-v' (`scroll-other-window') scrolls the window that -`C-x o' would select. Like `C-v', it takes positive and negative -arguments. +File: xemacs.info, Node: Snapshots, Next: Version Headers, Prev: Renaming and VC, Up: Version Control - The command `M-x compare-windows' compares the text in the current -window with the text in the next window. Comparison starts at point in -each window. Point moves forward in each window, a character at a time, -until the next set of characters in the two windows are different. -Then the command is finished. +Snapshots +--------- - A prefix argument IGNORE-WHITESPACE means ignore changes in -whitespace. The variable `compare-windows-whitespace' controls how -whitespace is skipped. + 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. - If `compare-ignore-case' is non-`nil', changes in case are also -ignored. +* Menu: + +* Making Snapshots:: The snapshot facilities. +* Snapshot Caveats:: Things to be careful of when using snapshots.  -File: xemacs.info, Node: Pop Up Window, Next: Change Window, Prev: Other Window, Up: Windows +File: xemacs.info, Node: Making Snapshots, Next: Snapshot Caveats, Prev: Snapshots, Up: Snapshots -Displaying in Another Window -============================ +Making and Using Snapshots +.......................... - `C-x 4' is a prefix key for commands that select another window -(splitting the window if there is only one) and select a buffer in that -window. Different `C-x 4' commands have different ways of finding the -buffer to select. + There are two basic commands for snapshots; one makes a snapshot +with a given name, the other retrieves a named snapshot. -`C-x 4 b BUFNAME ' - Select buffer BUFNAME in another window. This runs - `switch-to-buffer-other-window'. +`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'). -`C-x 4 f FILENAME ' - Visit file FILENAME and select its buffer in another window. This - runs `find-file-other-window'. *Note Visiting::. +`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 4 d DIRECTORY ' - Select a Dired buffer for directory DIRECTORY in another window. - This runs `dired-other-window'. *Note Dired::. + 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. -`C-x 4 m' - Start composing a mail message in another window. This runs - `mail-other-window', and its same-window version is `C-x m' (*note - Sending Mail::). + 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. -`C-x 4 .' - Find a tag in the current tag table in another window. This runs - `find-tag-other-window', the multiple-window variant of `M-.' - (*note Tags::). + 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. - If the variable `display-buffer-function' is non-`nil', its value is -the function to call to handle `display-buffer'. It receives two -arguments, the buffer and a flag that if non-`nil' means that the -currently selected window is not acceptable. Commands such as -`switch-to-buffer-other-window' and `find-file-other-window' work using -this function. + +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: Change Window, Prev: Pop Up Window, Up: Windows - -Deleting and Rearranging Windows -================================ - -`C-x 0' - Get rid of the selected window (`delete-window'). That is a zero. - If there is more than one Emacs frame, deleting the sole remaining - window on that frame deletes the frame as well. If the current - frame is the only frame, it is not deleted. - -`C-x 1' - Get rid of all windows except the selected one - (`delete-other-windows'). - -`C-x ^' - Make the selected window taller, at the expense of the other(s) - (`enlarge-window'). - -`C-x }' - Make the selected window wider (`enlarge-window-horizontally'). - - To delete a window, type `C-x 0' (`delete-window'). (That is a -zero.) The space occupied by the deleted window is distributed among -the other active windows (but not the minibuffer window, even if that -is active at the time). Once a window is deleted, its attributes are -forgotten; there is no automatic way to make another window of the same -shape or showing the same buffer. The buffer continues to exist, and -you can select it in any window with `C-x b'. - - `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it -deletes all the windows except the selected one (and the minibuffer). -The selected window expands to use the whole frame except for the echo -area. - - To readjust the division of space among existing windows, use `C-x -^' (`enlarge-window'). It makes the currently selected window longer -by one line or as many lines as a numeric argument specifies. With a -negative argument, it makes the selected window smaller. `C-x }' -(`enlarge-window-horizontally') makes the selected window wider by the -specified number of columns. The extra screen space given to a window -comes from one of its neighbors, if that is possible; otherwise, all -the competing windows are shrunk in the same proportion. If this makes -some windows too small, those windows are deleted and their space is -divided up. Minimum window size is specified by the variables -`window-min-height' and `window-min-width'. - - You can also resize windows within a frame by clicking the left mouse -button on a modeline, and dragging. - - Clicking the right button on a mode line pops up a menu of common -window manager operations. This menu contains the following options: - -Delete Window - Remove the window above this modeline from the frame. - -Delete Other Windows - Delete all windows on the frame except for the one above this - modeline. - -Split Window - Split the window above the mode line in half, creating another - window. - -Split Window Horizontally - Split the window above the mode line in half horizontally, so that - there will be two windows side-by-side. - -Balance Windows - Readjust the sizes of all windows on the frame until all windows - have roughly the same number of lines. +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: Mule, Next: Major Modes, Prev: Windows, Up: Top +File: xemacs.info, Node: ListDir, Next: Comparing Files, Prev: Version Control, Up: Files -World Scripts Support -********************* +Listing a File Directory +======================== - If you compile XEmacs with mule option, it supports a wide variety of -world scripts, including Latin script, as well as Arabic script, -Simplified Chinese script (for mainland of China), Traditional Chinese -script (for Taiwan and Hong-Kong), Greek script, Hebrew script, IPA -symbols, Japanese scripts (Hiragana, Katakana and Kanji), Korean scripts -(Hangul and Hanja) and Cyrillic script (for Beylorussian, Bulgarian, -Russian, Serbian and Ukrainian). These features have been merged from -the modified version of Emacs known as MULE (for "MULti-lingual -Enhancement to GNU Emacs"). + 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). -* Menu: +`C-x C-d DIR-OR-PATTERN' + Print a brief directory listing (`list-directory'). -* Mule Intro:: Basic concepts of Mule. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How XEmacs figures out which conversion to use. -* Specify Coding:: Various ways to choose which conversion to use. +`C-u C-x C-d DIR-OR-PATTERN' + Print a verbose directory listing. - -File: xemacs.info, Node: Mule Intro, Next: Language Environments, Prev: Mule, Up: Mule + 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, -Introduction to world scripts -============================= + C-x C-d /u2/emacs/etc - The users of these scripts have established many more-or-less -standard coding systems for storing files. XEmacs translates between -the internal character encoding and various other coding systems when -reading and writing files, when exchanging data with subprocesses, and -(in some cases) in the `C-q' command (see below). +lists all the files in directory `/u2/emacs/etc'. An example of +specifying a file name pattern is: - The command `C-h h' (`view-hello-file') displays the file -`etc/HELLO', which shows how to say "hello" in many languages. This -illustrates various scripts. + C-x C-d /u2/emacs/src/*.c - Keyboards, even in the countries where these character sets are used, -generally don't have keys for all the characters in them. So XEmacs -supports various "input methods", typically one for each script or -language, to make it convenient to type them. + 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'). - The prefix key `C-x ' is used for commands that pertain to -world scripts, coding systems, and input methods. + 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). - -File: xemacs.info, Node: Language Environments, Next: Input Methods, Prev: Mule Intro, Up: Mule - -Language Environments -===================== - - All supported character sets are supported in XEmacs buffers if it is -compile with mule; there is no need to select a particular language in -order to display its characters in an XEmacs buffer. However, it is -important to select a "language environment" in order to set various -defaults. The language environment really represents a choice of -preferred script (more or less) rather that a choice of language. - - The language environment controls which coding systems to recognize -when reading text (*note Recognize Coding::). This applies to files, -incoming mail, netnews, and any other text you read into XEmacs. It may -also specify the default coding system to use when you create a file. -Each language environment also specifies a default input method. - - The command to select a language environment is `M-x -set-language-environment'. It makes no difference which buffer is -current when you use this command, because the effects apply globally to -the XEmacs session. The supported language environments include: - - Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-ISO, English, - Ethiopic, Greek, Japanese, Korean, Latin-1, Latin-2, Latin-3, - Latin-4, Latin-5. - - Some operating systems let you specify the language you are using by -setting locale environment variables. XEmacs handles one common special -case of this: if your locale name for character types contains the -string `8859-N', XEmacs automatically selects the corresponding -language environment. - - To display information about the effects of a certain language -environment LANG-ENV, use the command `C-h L LANG-ENV ' -(`describe-language-environment'). This tells you which languages this -language environment is useful for, and lists the character sets, -coding systems, and input methods that go with it. It also shows some -sample text to illustrate scripts used in this language environment. -By default, this command describes the chosen language environment. + 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 ``^''. - -File: xemacs.info, Node: Input Methods, Next: Select Input Method, Prev: Language Environments, Up: Mule - -Input Methods -============= - - An "input method" is a kind of character conversion designed -specifically for interactive input. In XEmacs, typically each language -has its own input method; sometimes several languages which use the same -characters can share one input method. A few languages support several -input methods. - - The simplest kind of input method works by mapping ASCII letters into -another alphabet. This is how the Greek and Russian input methods work. - - A more powerful technique is composition: converting sequences of -characters into one letter. Many European input methods use composition -to produce a single non-ASCII letter from a sequence that consists of a -letter followed by accent characters. For example, some methods convert -the sequence `'a' into a single accented letter. - - The input methods for syllabic scripts typically use mapping followed -by composition. The input methods for Thai and Korean work this way. -First, letters are mapped into symbols for particular sounds or tone -marks; then, sequences of these which make up a whole syllable are -mapped into one syllable sign. - - Chinese and Japanese require more complex methods. In Chinese input -methods, first you enter the phonetic spelling of a Chinese word (in -input method `chinese-py', among others), or a sequence of portions of -the character (input methods `chinese-4corner' and `chinese-sw', and -others). Since one phonetic spelling typically corresponds to many -different Chinese characters, you must select one of the alternatives -using special XEmacs commands. Keys such as `C-f', `C-b', `C-n', -`C-p', and digits have special definitions in this situation, used for -selecting among the alternatives. displays a buffer showing all -the possibilities. - - In Japanese input methods, first you input a whole word using -phonetic spelling; then, after the word is in the buffer, XEmacs -converts it into one or more characters using a large dictionary. One -phonetic spelling corresponds to many differently written Japanese -words, so you must select one of them; use `C-n' and `C-p' to cycle -through the alternatives. - - Sometimes it is useful to cut off input method processing so that the -characters you have just entered will not combine with subsequent -characters. For example, in input method `latin-1-postfix', the -sequence `e '' combines to form an `e' with an accent. What if you -want to enter them as separate characters? - - One way is to type the accent twice; that is a special feature for -entering the separate letter and accent. For example, `e ' '' gives -you the two characters `e''. Another way is to type another letter -after the `e'--something that won't combine with that--and immediately -delete it. For example, you could type `e e '' to get separate -`e' and `''. - - Another method, more general but not quite as easy to type, is to use -`C-\ C-\' between two characters to stop them from combining. This is -the command `C-\' (`toggle-input-method') used twice. *Note Select -Input Method::. - - `C-\ C-\' is especially useful inside an incremental search, because -stops waiting for more characters to combine, and starts searching for -what you have already entered. - - The variables `input-method-highlight-flag' and -`input-method-verbose-flag' control how input methods explain what is -happening. If `input-method-highlight-flag' is non-`nil', the partial -sequence is highlighted in the buffer. If `input-method-verbose-flag' -is non-`nil', the list of possible characters to type next is displayed -in the echo area (but not when you are in the minibuffer). + 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.  -File: xemacs.info, Node: Select Input Method, Next: Coding Systems, Prev: Input Methods, Up: Mule +File: xemacs.info, Node: Comparing Files, Next: Dired, Prev: ListDir, Up: Files -Selecting an Input Method -========================= +Comparing Files +=============== -`C-\' - Enable or disable use of the selected input method. + 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. -`C-x C-\ METHOD ' - Select a new input method for the current buffer. + 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::. -`C-h I METHOD ' -`C-h C-\ METHOD ' - Describe the input method METHOD (`describe-input-method'). By - default, it describes the current input method (if any). + 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. -`M-x list-input-methods' - Display a list of all the supported input methods. + 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::. - To choose an input method for the current buffer, use `C-x -C-\' (`select-input-method'). This command reads the input method name -with the minibuffer; the name normally starts with the language -environment that it is meant to be used with. The variable -`current-input-method' records which input method is selected. + 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. - Input methods use various sequences of ASCII characters to stand for -non-ASCII characters. Sometimes it is useful to turn off the input -method temporarily. To do this, type `C-\' (`toggle-input-method'). -To reenable the input method, type `C-\' again. + +File: xemacs.info, Node: Dired, Next: Misc File Ops, Prev: Comparing Files, Up: Files - If you type `C-\' and you have not yet selected an input method, it -prompts for you to specify one. This has the same effect as using `C-x - C-\' to specify an input method. +Dired, the Directory Editor +=========================== - Selecting a language environment specifies a default input method for -use in various buffers. When you have a default input method, you can -select it in the current buffer by typing `C-\'. The variable -`default-input-method' specifies the default input method (`nil' means -there is none). + 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. - Some input methods for alphabetic scripts work by (in effect) -remapping the keyboard to emulate various keyboard layouts commonly used -for those scripts. How to do this remapping properly depends on your -actual keyboard layout. To specify which layout your keyboard has, use -the command `M-x quail-set-keyboard-layout'. +* Menu: - To display a list of all the supported input methods, type `M-x -list-input-methods'. The list gives information about each input -method, including the string that stands for it in the mode line. +* 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: xemacs.info, Node: Coding Systems, Next: Recognize Coding, Prev: Select Input Method, Up: Mule - -Coding Systems -============== - - Users of various languages have established many more-or-less -standard coding systems for representing them. XEmacs does not use -these coding systems internally; instead, it converts from various -coding systems to its own system when reading data, and converts the -internal coding system to other coding systems when writing data. -Conversion is possible in reading or writing files, in sending or -receiving from the terminal, and in exchanging data with subprocesses. - - XEmacs assigns a name to each coding system. Most coding systems are -used for one language, and the name of the coding system starts with the -language name. Some coding systems are used for several languages; -their names usually start with `iso'. There are also special coding -systems `binary' and `no-conversion' which do not convert printing -characters at all. - - In addition to converting various representations of non-ASCII -characters, a coding system can perform end-of-line conversion. XEmacs -handles three different conventions for how to separate lines in a file: -newline, carriage-return linefeed, and just carriage-return. - -`C-h C CODING ' - Describe coding system CODING. - -`C-h C ' - Describe the coding systems currently in use. - -`M-x list-coding-systems' - Display a list of all the supported coding systems. - - The command `C-h C' (`describe-coding-system') displays information -about particular coding systems. You can specify a coding system name -as argument; alternatively, with an empty argument, it describes the -coding systems currently selected for various purposes, both in the -current buffer and as the defaults, and the priority list for -recognizing coding systems (*note Recognize Coding::). - - To display a list of all the supported coding systems, type `M-x -list-coding-systems'. The list gives information about each coding -system, including the letter that stands for it in the mode line (*note -Mode Line::). - - Each of the coding systems that appear in this list--except for -`binary', which means no conversion of any kind--specifies how and -whether to convert printing characters, but leaves the choice of -end-of-line conversion to be decided based on the contents of each file. -For example, if the file appears to use carriage-return linefeed between -lines, that end-of-line conversion will be used. - - Each of the listed coding systems has three variants which specify -exactly what to do for end-of-line conversion: - -`...-unix' - Don't do any end-of-line conversion; assume the file uses newline - to separate lines. (This is the convention normally used on Unix - and GNU systems.) - -`...-dos' - Assume the file uses carriage-return linefeed to separate lines, - and do the appropriate conversion. (This is the convention - normally used on Microsoft systems.) - -`...-mac' - Assume the file uses carriage-return to separate lines, and do the - appropriate conversion. (This is the convention normally used on - the Macintosh system.) - - These variant coding systems are omitted from the -`list-coding-systems' display for brevity, since they are entirely -predictable. For example, the coding system `iso-8859-1' has variants -`iso-8859-1-unix', `iso-8859-1-dos' and `iso-8859-1-mac'. - - In contrast, the coding system `binary' specifies no character code -conversion at all--none for non-Latin-1 byte values and none for end of -line. This is useful for reading or writing binary files, tar files, -and other files that must be examined verbatim. - - The easiest way to edit a file with no conversion of any kind is with -the `M-x find-file-literally' command. This uses `binary', and also -suppresses other XEmacs features that might convert the file contents -before you see them. *Note Visiting::. - - The coding system `no-conversion' means that the file contains -non-Latin-1 characters stored with the internal XEmacs encoding. It -handles end-of-line conversion based on the data encountered, and has -the usual three variants to specify the kind of end-of-line conversion. +File: xemacs.info, Node: Dired Enter, Next: Dired Edit, Prev: Dired, Up: Dired + +Entering Dired +-------------- + + 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'. + + 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'.  -File: xemacs.info, Node: Recognize Coding, Next: Specify Coding, Prev: Coding Systems, Up: Mule - -Recognizing Coding Systems -========================== - - Most of the time, XEmacs can recognize which coding system to use for -any given file-once you have specified your preferences. - - Some coding systems can be recognized or distinguished by which byte -sequences appear in the data. However, there are coding systems that -cannot be distinguished, not even potentially. For example, there is no -way to distinguish between Latin-1 and Latin-2; they use the same byte -values with different meanings. - - XEmacs handles this situation by means of a priority list of coding -systems. Whenever XEmacs reads a file, if you do not specify the coding -system to use, XEmacs checks the data against each coding system, -starting with the first in priority and working down the list, until it -finds a coding system that fits the data. Then it converts the file -contents assuming that they are represented in this coding system. - - The priority list of coding systems depends on the selected language -environment (*note Language Environments::). For example, if you use -French, you probably want XEmacs to prefer Latin-1 to Latin-2; if you -use Czech, you probably want Latin-2 to be preferred. This is one of -the reasons to specify a language environment. - - However, you can alter the priority list in detail with the command -`M-x prefer-coding-system'. This command reads the name of a coding -system from the minibuffer, and adds it to the front of the priority -list, so that it is preferred to all others. If you use this command -several times, each use adds one element to the front of the priority -list. - - Sometimes a file name indicates which coding system to use for the -file. The variable `file-coding-system-alist' specifies this -correspondence. There is a special function -`modify-coding-system-alist' for adding elements to this list. For -example, to read and write all `.txt' using the coding system -`china-iso-8bit', you can execute this Lisp expression: - - (modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit) - -The first argument should be `file', the second argument should be a -regular expression that determines which files this applies to, and the -third argument says which coding system to use for these files. - - You can specify the coding system for a particular file using the -`-*-...-*-' construct at the beginning of a file, or a local variables -list at the end (*note File Variables::). You do this by defining a -value for the "variable" named `coding'. XEmacs does not really have a -variable `coding'; instead of setting a variable, it uses the specified -coding system for the file. For example, `-*-mode: C; coding: -iso-8859-1;-*-' specifies use of the iso-8859-1 coding system, as well -as C mode. - - Once XEmacs has chosen a coding system for a buffer, it stores that -coding system in `buffer-file-coding-system' and uses that coding -system, by default, for operations that write from this buffer into a -file. This includes the commands `save-buffer' and `write-region'. If -you want to write files from this buffer using a different coding -system, you can specify a different coding system for the buffer using -`set-buffer-file-coding-system' (*note Specify Coding::). +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.