[Emacs-diffs] Changes to emacs/man/emacs-xtra.texi

[Karl Berry]

Index: emacs/man/emacs-xtra.texi
diff -u emacs/man/emacs-xtra.texi:1.17 emacs/man/emacs-xtra.texi:1.18
--- emacs/man/emacs-xtra.texi:1.17      Sun Apr  9 22:40:34 2006
+++ emacs/man/emacs-xtra.texi   Wed Apr 12 00:27:50 2006
@@ -57,12 +57,14 @@
 @menu
 * Introduction::                  What documentation belongs here?
 * Autorevert::                    Auto Reverting non-file buffers.
-* Subdir switches::               Subdirectory switches in Dired.
+* Subdir Switches::               Subdirectory switches in Dired.
 * Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
 * Emerge::                        A convenient way of merging two versions
                                     of a program.
 * Picture Mode::                  Editing pictures made up of characters
                                     using the quarter-plane screen model.
+
+* Advanced VC Usage::             Advanced VC (version control) features.
 * Fortran::                       Fortran mode and its special features.
 * MS-DOG::                        
 * Index::
@@ -273,7 +275,7 @@
 completely up to date (or will be after @code{auto-revert-interval}
 seconds).
 
address@hidden Subdir switches
address@hidden Subdir Switches
 @chapter Subdirectory Switches in Dired
 
 You can insert subdirectories with specified @code{ls} switches in
@@ -1889,6 +1891,887 @@
 @kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does
 likewise for the rectangle found in a specified register.
 
address@hidden Advanced VC Usage
address@hidden Advanced VC Usage
+
+  Commonly used features of Emacs' version control (VC) support are
+described in the main Emacs manual (@pxref{Version Control,,,emacs,
+the Emacs Manual}).  This chapter describes more advanced VC usage.
+
address@hidden
+* VC Dired Mode::       Listing files managed by version control.
+* VC Dired Commands::   Commands to use in a VC Dired buffer.
+* Remote Repositories:: Efficient access to remote CVS servers.
+* Snapshots::           Sets of file versions treated as a unit.
+* Miscellaneous VC::    Various other commands and features of VC.
+* Customizing VC::      Variables that change VC's behavior.
address@hidden menu
+
address@hidden VC Dired Mode
address@hidden Dired under VC
+
address@hidden PCL-CVS
address@hidden cvs
address@hidden CVS Dired Mode
+  The VC Dired Mode described here works with all the version control
+systems that VC supports.  Another more powerful facility, designed
+specifically for CVS, is called PCL-CVS.  @xref{Top, , About PCL-CVS,
+pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
+
address@hidden C-x v d
address@hidden vc-directory
+  When you are working on a large program, it is often useful to find
+out which files have changed within an entire directory tree, or to view
+the status of all files under version control at once, and to perform
+version control operations on collections of files.  You can use the
+command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing
+that includes only files relevant for version control.
+
address@hidden vc-dired-terse-display
+  @kbd{C-x v d} creates a buffer which uses VC Dired Mode.  This looks
+much like an ordinary Dired buffer (@pxref{Dired,,,emacs, the
+Emacs Manual}); however, normally it shows only the noteworthy files
+(those locked or not up-to-date).  This is called @dfn{terse display}.
+If you set the variable @code{vc-dired-terse-display} to @code{nil},
+then VC Dired shows all relevant files---those managed under version
+control, plus all subdirectories (@dfn{full display}).  The command
address@hidden t} in a VC Dired buffer toggles between terse display and full
+display (@pxref{VC Dired Commands}).
+
address@hidden vc-dired-recurse
+  By default, VC Dired produces a recursive listing of noteworthy or
+relevant files at or below the given directory.  You can change this by
+setting the variable @code{vc-dired-recurse} to @code{nil}; then VC
+Dired shows only the files in the given directory.
+
+  The line for an individual file shows the version control state in the
+place of the hard link count, owner, group, and size of the file.  If
+the file is unmodified, in sync with the master file, the version
+control state shown is blank.  Otherwise it consists of text in
+parentheses.  Under RCS and SCCS, the name of the user locking the file
+is shown; under CVS, an abbreviated version of the @samp{cvs status}
+output is used.  Here is an example using RCS:
+
address@hidden
address@hidden
+  /home/jim/project:
+
+  -rw-r--r-- (jim)      Apr  2 23:39 file1
+  -r--r--r--            Apr  5 20:21 file2
address@hidden group
address@hidden smallexample
+
address@hidden
+The files @samp{file1} and @samp{file2} are under version control,
address@hidden is locked by user jim, and @samp{file2} is unlocked.
+
+  Here is an example using CVS:
+
address@hidden
address@hidden
+  /home/joe/develop:
+
+  -rw-r--r-- (modified) Aug  2  1997 file1.c
+  -rw-r--r--            Apr  4 20:09 file2.c
+  -rw-r--r-- (merge)    Sep 13  1996 file3.c
address@hidden group
address@hidden smallexample
+
+  Here @samp{file1.c} is modified with respect to the repository, and
address@hidden is not.  @samp{file3.c} is modified, but other changes
+have also been checked in to the repository---you need to merge them
+with the work file before you can check it in.
+
address@hidden vc-stay-local
address@hidden vc-cvs-stay-local
+  In the above, if the repository were on a remote machine, VC would
+only contact it when the variable @code{vc-stay-local} (or
address@hidden) is nil (@pxref{CVS Options}).  This is
+because access to the repository may be slow, or you may be working
+offline and not have access to the repository at all.  As a
+consequence, VC would not be able to tell you that @samp{file3.c} is
+in the ``merge'' state; you would learn that only when you try to
+check-in your modified copy of the file, or use a command such as
address@hidden v m}.
+
+  In practice, this is not a problem because CVS handles this case
+consistently whenever it arises.  In VC, you'll simply get prompted to
+merge the remote changes into your work file first.  The benefits of
+less network communication usually outweigh the disadvantage of not
+seeing remote changes immediately.
+
address@hidden vc-directory-exclusion-list
+  When VC Dired displays subdirectories (in the ``full'' display mode),
+it omits some that should never contain any files under version control.
+By default, this includes Version Control subdirectories such as
address@hidden and @samp{CVS}; you can customize this by setting the
+variable @code{vc-directory-exclusion-list}.
+
+  You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in
+ordinary Dired, that allows you to specify additional switches for the
address@hidden command.
+
address@hidden VC Dired Commands
address@hidden VC Dired Commands
+
+  All the usual Dired commands work normally in VC Dired mode, except
+for @kbd{v}, which is redefined as the version control prefix.  You can
+invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by
+typing @kbd{v =}, or @kbd{v l}, and so on.  Most of these commands apply
+to the file name on the current line.
+
+  The command @kbd{v v} (@code{vc-next-action}) operates on all the
+marked files, so that you can lock or check in several files at once.
+If it operates on more than one file, it handles each file according to
+its current state; thus, it might lock one file, but check in another
+file.  This could be confusing; it is up to you to avoid confusing
+behavior by marking a set of files that are in a similar state.  If no
+files are marked, @kbd{v v} operates on the file in the current line.
+
+  If any files call for check-in, @kbd{v v} reads a single log entry,
+then uses it for all the files being checked in.  This is convenient for
+registering or checking in several files at once, as part of the same
+change.
+
address@hidden vc-dired-toggle-terse-mode
address@hidden vc-dired-mark-locked
+  You can toggle between terse display (only locked files, or files not
+up-to-date) and full display at any time by typing @kbd{v t}
+(@code{vc-dired-toggle-terse-mode}).  There is also a special command
address@hidden l} (@code{vc-dired-mark-locked}), which marks all files currently
+locked (or, with CVS, all files not up-to-date).  Thus, typing @kbd{* l
+t k} is another way to delete from the buffer all files except those
+currently locked.
+
address@hidden Remote Repositories
address@hidden Remote Repositories
address@hidden remote repositories (CVS)
+
+  A common way of using CVS is to set up a central CVS repository on
+some Internet host, then have each developer check out a personal
+working copy of the files on his local machine.  Committing changes to
+the repository, and picking up changes from other users into one's own
+working area, then works by direct interactions with the CVS server.
+
+  One difficulty is that access to the CVS server is often slow, and
+that developers might need to work off-line as well.  VC is designed
+to reduce the amount of network interaction necessary.
+
address@hidden
+* Version Backups::        Keeping local copies of repository versions.
+* Local Version Control::  Using another version system for local editing.
address@hidden menu
+
address@hidden Version Backups
address@hidden Version Backups
address@hidden version backups
+
address@hidden automatic version backups
+  When VC sees that the CVS repository for a file is on a remote
+machine, it automatically makes local backups of unmodified versions
+of the address@hidden version backups}.  This means that you
+can compare the file to the repository version (@kbd{C-x v =}), or
+revert to that version (@kbd{C-x v u}), without any network
+interactions.
+
+  The local copy of the unmodified file is called a @dfn{version
+backup} to indicate that it corresponds exactly to a version that is
+stored in the repository.  Note that version backups are not the same
+as ordinary Emacs backup files (@pxref{Backup,,,emacs, the Emacs
+Manual}).  But they follow a similar naming convention.
+
+  For a file that comes from a remote CVS repository, VC makes a
+version backup whenever you save the first changes to the file, and
+removes it after you have committed your modified version to the
+repository. You can disable the making of automatic version backups by
+setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}).
+
address@hidden manual version backups
+  The name of the automatic version backup for version @var{version}
+of file @var{file} is @address@hidden@var{version}.~}.  This is
+almost the same as the name used by @kbd{C-x v ~} (@pxref{Old
+Versions,,,emacs, the Emacs Manual}), the only difference being
+the additional dot (@samp{.})  after the version number.  This
+similarity is intentional, because both kinds of files store the same
+kind of information.  The file made by @kbd{C-x v ~} acts as a
address@hidden version backup}.
+
+  All the VC commands that operate on old versions of a file can use
+both kinds of version backups.  For instance, @kbd{C-x v ~} uses
+either an automatic or a manual version backup, if possible, to get
+the contents of the version you request.  Likewise, @kbd{C-x v =} and
address@hidden v u} use either an automatic or a manual version backup, if
+one of them exists, to get the contents of a version to compare or
+revert to.  If you changed a file outside of Emacs, so that no
+automatic version backup was created for the previous text, you can
+create a manual backup of that version using @kbd{C-x v ~}, and thus
+obtain the benefit of the local copy for Emacs commands.
+
+  The only difference in Emacs's handling of manual and automatic
+version backups, once they exist, is that Emacs deletes automatic
+version backups when you commit to the repository.  By contrast,
+manual version backups remain until you delete them.
+
address@hidden Local Version Control
address@hidden Local Version Control
address@hidden local version control
address@hidden local back end (version control)
+
+When you make many changes to a file that comes from a remote
+repository, it can be convenient to have version control on your local
+machine as well.  You can then record intermediate versions, revert to
+a previous state, etc., before you actually commit your changes to the
+remote server.
+
+VC lets you do this by putting a file under a second, local version
+control system, so that the file is effectively registered in two
+systems at the same time.  For the description here, we will assume
+that the remote system is CVS, and you use RCS locally, although the
+mechanism works with any combination of version control systems
+(@dfn{back ends}).
+
+To make it work with other back ends, you must make sure that the
+``more local'' back end comes before the ``more remote'' back end in
+the setting of @code{vc-handled-backends} (@pxref{Customizing VC}).  By
+default, this variable is set up so that you can use remote CVS and
+local RCS as described here.
+
+To start using local RCS for a file that comes from a remote CVS
+server, you must @emph{register the file in RCS}, by typing @kbd{C-u
+C-x v v rcs @key{RET}}.  (In other words, use @code{vc-next-action} with a
+prefix argument, and specify RCS as the back end.)
+
+You can do this at any time; it does not matter whether you have
+already modified the file with respect to the version in the CVS
+repository.  If possible, VC tries to make the RCS master start with
+the unmodified repository version, then checks in any local changes
+as a new version.  This works if you have not made any changes yet, or
+if the unmodified repository version exists locally as a version
+backup (@pxref{Version Backups}).  If the unmodified version is not
+available locally, the RCS master starts with the modified version;
+the only drawback to this is that you cannot compare your changes
+locally to what is stored in the repository.
+
+The version number of the RCS master is derived from the current CVS
+version, starting a branch from it.  For example, if the current CVS
+version is 1.23, the local RCS branch will be 1.23.1.  Version 1.23 in
+the RCS master will be identical to version 1.23 under CVS; your first
+changes are checked in as 1.23.1.1.  (If the unmodified file is not
+available locally, VC will check in the modified file twice, both as
+1.23 and 1.23.1.1, to make the revision numbers consistent.)
+
+If you do not use locking under CVS (the default), locking is also
+disabled for RCS, so that editing under RCS works exactly as under
+CVS.
+
+When you are done with local editing, you can commit the final version
+back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}.
+This initializes the log entry buffer (@pxref{Log Buffer,,,emacs, the
+Emacs Manual}) to contain all the log entries you have recorded in the
+RCS master; you can edit them as you wish, and then commit in CVS by
+typing @kbd{C-c C-c}.  If the commit is successful, VC removes the RCS
+master, so that the file is once again registered under CVS only.
+(The RCS master is not actually deleted, just renamed by appending
address@hidden to the name, so that you can refer to it later if you wish.)
+
+While using local RCS, you can pick up recent changes from the CVS
+repository into your local file, or commit some of your changes back
+to CVS, without terminating local RCS version control.  To do this,
+switch to the CVS back end temporarily, with the @kbd{C-x v b} command:
+
address@hidden @kbd
address@hidden C-x v b
+Switch to another back end that the current file is registered
+under (@code{vc-switch-backend}).
+
address@hidden C-u C-x v b @var{backend} @key{RET}
+Switch to @var{backend} for the current file.
address@hidden table
+
address@hidden C-x v b
address@hidden vc-switch-backend
address@hidden v b} does not change the buffer contents, or any files; it
+only changes VC's perspective on how to handle the file.  Any
+subsequent VC commands for that file will operate on the back end that
+is currently selected.
+
+If the current file is registered in more than one back end, typing
address@hidden v b} ``cycles'' through all of these back ends.  With a
+prefix argument, it asks for the back end to use in the minibuffer.
+
+Thus, if you are using local RCS, and you want to pick up some recent
+changes in the file from remote CVS, first visit the file, then type
address@hidden v b} to switch to CVS, and finally use @kbd{C-x v m
address@hidden to merge the news (@pxref{Merging,,,emacs, the Emacs
+Manual}).  You can then switch back to RCS by typing @kbd{C-x v b}
+again, and continue to edit locally.
+
+But if you do this, the revision numbers in the RCS master no longer
+correspond to those of CVS.  Technically, this is not a problem, but
+it can become difficult to keep track of what is in the CVS repository
+and what is not.  So we suggest that you return from time to time to
+CVS-only operation, by committing your local changes back to the
+repository using @kbd{C-u C-x v v cvs @key{RET}}.
+
address@hidden Snapshots
address@hidden Snapshots
address@hidden snapshots and version control
+
+  A @dfn{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 @dfn{release}, a (theoretically) stable version of the
+system that is ready for distribution to users.
+
address@hidden
+* Making Snapshots::           The snapshot facilities.
+* Snapshot Caveats::           Things to be careful of when using snapshots.
address@hidden menu
+
address@hidden Making Snapshots
address@hidden Making and Using Snapshots
+
+  There are two basic commands for snapshots; one makes a
+snapshot with a given name, the other retrieves a named snapshot.
+
address@hidden @code
address@hidden C-x v s
address@hidden vc-create-snapshot
address@hidden C-x v s @var{name} @key{RET}
+Define the last saved versions of every registered file in or under the
+current directory as a snapshot named @var{name}
+(@code{vc-create-snapshot}).
+
address@hidden C-x v r
address@hidden vc-retrieve-snapshot
address@hidden C-x v r @var{name} @key{RET}
+For all registered files at or below the current directory level, select
+whatever versions correspond to the snapshot @var{name}
+(@code{vc-retrieve-snapshot}).
+
+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.
address@hidden table
+
+  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.
+
+  You can give a snapshot name as an argument to @kbd{C-x v =} or
address@hidden v ~} (@pxref{Old Versions,,,emacs, the Emacs Manual}).
+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.
+
address@hidden Snapshot Caveats
address@hidden Snapshot Caveats
+
address@hidden named configurations (RCS)
+  VC's snapshot facilities are modeled on RCS's named-configuration
+support.  They use RCS's native facilities for this, so
+snapshots made using RCS through VC are visible even when you bypass VC.
+
+  With CVS, Meta-CVS, and Subversion, VC also uses the native
+mechanism provided by that back end to make snapshots and retrieve them
+(@dfn{tags} for CVS and Meta-CVS, @dfn{copies} for Subversion).
+
address@hidden worded verbosely to avoid overfull hbox.
+  For SCCS, VC implements snapshots itself.  The files it uses contain
+name/file/version-number triples.  These snapshots are visible only
+through VC.
+
+  There is no support for VC snapshots using GNU Arch yet.
+
+  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 @code{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 (@code{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 @code{vc-rename-file} makes the snapshot remain valid for
+retrieval, but it does not solve all problems.  For example, some of the
+files in your 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.
+
address@hidden Miscellaneous VC
address@hidden Miscellaneous Commands and Features of VC
+
+  This section explains the less-frequently-used features of VC.
+
address@hidden
+* Change Logs and VC::  Generating a change log file from log entries.
+* Renaming and VC::     A command to rename both the source and master
+                          file correctly.
+* Version Headers::     Inserting version control headers into working files.
address@hidden menu
+
address@hidden Change Logs and VC
address@hidden Change Logs and VC
+
+  If you use RCS or CVS for a program and also maintain a change log
+file for it (@pxref{Change Log,,,emacs, the Emacs Manual}), you
+can generate change log entries automatically from the version control
+log entries:
+
address@hidden @kbd
address@hidden C-x v a
address@hidden C-x v a
address@hidden vc-update-change-log
+Visit the current directory's change log file and, for registered files
+in that directory, create new entries for versions checked in since the
+most recent entry in the change log file.
+(@code{vc-update-change-log}).
+
+This command works with RCS or CVS only, not with any of the other
+back ends.
+
address@hidden C-u C-x v a
+As above, but only find entries for the current buffer's file.
+
address@hidden M-1 C-x v a
+As above, but find entries for all the currently visited files that are
+maintained with version control.  This works only with RCS, and it puts
+all entries in the log for the default directory, which may not be
+appropriate.
address@hidden table
+
+  For example, suppose the first line of @file{ChangeLog} is dated
+1999-04-10, and that the only check-in since then was by Nathaniel
+Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log
+messages that start with `#'.}.  Then @kbd{C-x v a} visits
address@hidden and inserts text like this:
+
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
+1999-05-22  Nathaniel Bowditch  <nat@@apn.org>
+
+        * rcs2log: Ignore log messages that start with `#'.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden iftex
+
address@hidden
+You can then edit the new change log entry further as you wish.
+
+  Some of the new change log entries may duplicate what's already in
+ChangeLog.  You will have to remove these duplicates by hand.
+
+  Normally, the log entry for file @file{foo} is displayed as @samp{*
+foo: @var{text of log entry}}.  The @samp{:} after @file{foo} is omitted
+if the text of the log entry starts with @address@hidden(@var{functionname}):
+}}.  For example, if the log entry for @file{vc.el} is
address@hidden(vc-do-command): Check call-process status.}, then the text in
address@hidden looks like this:
+
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
+1999-05-06  Nathaniel Bowditch  <nat@@apn.org>
+
+        * vc.el (vc-do-command): Check call-process status.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden iftex
+
+  When @kbd{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 check-ins have the following log
+entries:
+
address@hidden
address@hidden For @file{vc.texinfo}: @samp{Fix expansion typos.}
address@hidden For @file{vc.el}: @samp{Don't call expand-file-name.}
address@hidden For @file{vc-hooks.el}: @samp{Don't call expand-file-name.}
address@hidden flushleft
+
address@hidden
+They appear like this in @file{ChangeLog}:
+
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
+1999-04-01  Nathaniel Bowditch  <nat@@apn.org>
+
+        * vc.texinfo: Fix expansion typos.
+
+        * vc.el, vc-hooks.el: Don't call expand-file-name.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden iftex
+
+  Normally, @kbd{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 @address@hidden@address@hidden@} }}.  The label
+itself is not copied to @file{ChangeLog}.  For example, suppose the log
+entries are:
+
address@hidden
address@hidden For @file{vc.texinfo}: @address@hidden@} Fix expansion typos.}
address@hidden For @file{vc.el}: @address@hidden@} Don't call expand-file-name.}
address@hidden For @file{vc-hooks.el}: @address@hidden@} Don't call 
expand-file-name.}
address@hidden flushleft
+
address@hidden
+Then the text in @file{ChangeLog} looks like this:
+
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
+1999-04-01  Nathaniel Bowditch  <nat@@apn.org>
+
+        * vc.texinfo: Fix expansion typos.
+        * vc.el, vc-hooks.el: Don't call expand-file-name.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden iftex
+
+  A log entry whose text begins with @samp{#} is not copied to
address@hidden  For example, if you merely fix some misspellings in
+comments, you can log the change with an entry beginning with @samp{#}
+to avoid putting such trivia into @file{ChangeLog}.
+
address@hidden Renaming and VC
address@hidden Renaming VC Work Files and Master Files
+
address@hidden vc-rename-file
+  When you rename a registered file, you must also rename its master
+file correspondingly to get proper results.  Use @code{vc-rename-file}
+to rename the source file as you specify, and rename its master file
+accordingly.  It also updates any snapshots (@pxref{Snapshots}) that
+mention the file, so that they use the new name; despite this, the
+snapshot thus modified may not completely work (@pxref{Snapshot
+Caveats}).
+
+  Some back ends do not provide an explicit rename operation to their
+repositories.  After issuing @code{vc-rename-file}, use @kbd{C-x v v}
+on the original and renamed buffers and provide the necessary edit
+log.
+
+  You cannot use @code{vc-rename-file} on a file that is locked by
+someone else.
+
address@hidden Version Headers
address@hidden Inserting Version Control Headers
+
+   Sometimes it is convenient to put version identification strings
+directly into working files.  Certain special strings called
address@hidden headers} are replaced in each successive version by the
+number of that version, the name of the user who created it, and other
+relevant information.  All of the back ends that VC supports have such
+a mechanism, except GNU Arch.
+
+  VC does not normally use the information contained in these headers.
+The exception is RCS---with RCS, version headers are sometimes more
+reliable than the master file to determine which version of the file
+you are editing.  Note that in a multi-branch environment, version
+headers are necessary to make VC behave correctly (@pxref{Multi-User
+Branching,,,emacs, the Emacs Manual}).
+
+  Searching for RCS version headers is controlled by the variable
address@hidden  If it is address@hidden (the default),
+Emacs searches for headers to determine the version number you are
+editing.  Setting it to @code{nil} disables this feature.
+
+  Note that although CVS uses the same kind of version headers as RCS
+does, VC never searches for these headers if you are using CVS,
+regardless of the above setting.
+
address@hidden C-x v h
address@hidden vc-insert-headers
+  You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
+insert a suitable header string.
+
address@hidden @kbd
address@hidden C-x v h
+Insert headers in a file for use with your version-control system.
address@hidden table
+
address@hidden address@hidden
+  The default header string is @address@hidden for RCS and
address@hidden@w{%}W%} for SCCS.  You can specify other headers to insert by
+setting the variables @address@hidden where
address@hidden is @code{rcs} or @code{sccs}.
+
+  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 may be necessary to use apparently-superfluous backslashes when
+writing the strings that you put in this variable.  For instance, you
+might write @code{"$Id\$"} rather than @code{"address@hidden"}.  The extra
+backslash prevents the string constant from being interpreted as a
+header, if the Emacs Lisp file containing it is maintained with
+version control.
+
address@hidden vc-comment-alist
+  Each header is inserted surrounded by tabs, inside comment delimiters,
+on a new line at point.  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 @code{vc-comment-alist} specifies them.  Each element of
+this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
+
address@hidden vc-static-header-alist
+  The variable @code{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 @code{(@var{regexp} . @var{format})}.  Whenever
address@hidden matches the buffer name, @var{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
address@hidden@var{backend}-header}.  The header line is made by processing the
+string from @address@hidden with the format taken from the
+element.  The default value for @code{vc-static-header-alist} is as follows:
+
address@hidden
address@hidden
+(("\\.c$" .
+  "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
+#endif /* lint */\n"))
address@hidden group
address@hidden example
+
address@hidden
+It specifies insertion of text of this form:
+
address@hidden
address@hidden
+
+#ifndef lint
+static char vcid[] = "@var{string}";
+#endif /* lint */
address@hidden group
address@hidden example
+
address@hidden
+Note that the text above starts with a blank line.
+
+  If you use more than one version header in a file, put them close
+together in the file.  The mechanism in @code{revert-buffer} that
+preserves markers may not handle markers positioned between two version
+headers.
+
address@hidden Customizing VC
address@hidden Customizing VC
+
address@hidden vc-handled-backends
+The variable @code{vc-handled-backends} determines which version
+control systems VC should handle.  The default value is @code{(RCS CVS
+SVN SCCS Arch MCVS)}, so it contains all six version systems that are
+currently supported.  If you want VC to ignore one or more of these
+systems, exclude its name from the list.  To disable VC entirely, set
+this variable to @code{nil}.
+
+The order of systems in the list is significant: when you visit a file
+registered in more than one system (@pxref{Local Version Control}), VC
+uses the system that comes first in @code{vc-handled-backends} by
+default.  The order is also significant when you register a file for
+the first time, @pxref{Registering,,,emacs, the Emacs Manual} for
+details.
+
address@hidden
+* General VC Options::  Options that apply to multiple back ends.
+* RCS and SCCS::        Options for RCS and SCCS.
+* CVS Options::         Options for CVS.
address@hidden menu
+
address@hidden General VC Options
address@hidden General Options
+
address@hidden vc-make-backup-files
+  Emacs normally does not save backup files for source files that are
+maintained with version control.  If you want to make backup files even
+for files that use version control, set the variable
address@hidden to a address@hidden value.
+
address@hidden vc-keep-workfiles
+  Normally the work file exists all the time, whether it is locked or
+not.  If you set @code{vc-keep-workfiles} to @code{nil}, then checking
+in a new version with @kbd{C-x v v} deletes the work file; but any
+attempt to visit the file with Emacs creates it again.  (With CVS, work
+files are always kept.)
+
address@hidden vc-follow-symlinks
+  Editing a version-controlled file through a symbolic link can be
+dangerous.  It bypasses the version control system---you can edit the
+file without locking it, and fail to check your changes in.  Also,
+your changes might overwrite those of another user.  To protect against
+this, VC checks each symbolic link that you visit, to see if it points
+to a file under version control.
+
+  The variable @code{vc-follow-symlinks} controls what to do when a
+symbolic link points to a version-controlled file.  If it is @code{nil},
+VC only displays a warning message.  If it is @code{t}, VC automatically
+follows the link, and visits the real file instead, telling you about
+this in the echo area.  If the value is @code{ask} (the default), VC
+asks you each time whether to follow the link.
+
address@hidden vc-suppress-confirm
+  If @code{vc-suppress-confirm} is address@hidden, then @kbd{C-x v v}
+and @kbd{C-x v i} can save the current buffer without asking, and
address@hidden v u} also operates without asking for confirmation.  (This
+variable does not affect @kbd{C-x v c}; that operation is so drastic
+that it should always ask for confirmation.)
+
address@hidden vc-command-messages
+  VC mode does much of its work by running the shell commands for RCS,
+CVS and SCCS.  If @code{vc-command-messages} is address@hidden, VC
+displays messages to indicate which shell commands it runs, and
+additional messages when the commands finish.
+
address@hidden vc-path
+  You can specify additional directories to search for version control
+programs by setting the variable @code{vc-path}.  These directories
+are searched before the usual search path.  It is rarely necessary to
+set this variable, because VC normally finds the proper files
+automatically.
+
address@hidden RCS and SCCS
address@hidden Options for RCS and SCCS
+
address@hidden non-strict locking (RCS)
address@hidden locking, non-strict (RCS)
+  By default, RCS uses locking to coordinate the activities of several
+users, but there is a mode called @dfn{non-strict locking} in which
+you can check-in changes without locking the file first.  Use
address@hidden -U} to switch to non-strict locking for a particular file,
+see the @code{rcs} manual page for details.
+
+  When deducing the version control state of an RCS file, VC first
+looks for an RCS version header string in the file (@pxref{Version
+Headers}).  If there is no header string, VC normally looks at the
+file permissions of the work file; this is fast.  But there might be
+situations when the file permissions cannot be trusted.  In this case
+the master file has to be consulted, which is rather expensive.  Also
+the master file can only tell you @emph{if} there's any lock on the
+file, but not whether your work file really contains that locked
+version.
+
address@hidden vc-consult-headers
+  You can tell VC not to use version headers to determine the file
+status by setting @code{vc-consult-headers} to @code{nil}.  VC then
+always uses the file permissions (if it is supposed to trust them), or
+else checks the master file.
+
address@hidden vc-mistrust-permissions
+  You can specify the criterion for whether to trust the file
+permissions by setting the variable @code{vc-mistrust-permissions}.
+Its value can be @code{t} (always mistrust the file permissions and
+check the master file), @code{nil} (always trust the file
+permissions), or a function of one argument which makes the decision.
+The argument is the directory name of the @file{RCS} subdirectory.  A
address@hidden value from the function says to mistrust the file
+permissions.  If you find that the file permissions of work files are
+changed erroneously, set @code{vc-mistrust-permissions} to @code{t}.
+Then VC always checks the master file to determine the file's status.
+
+  VC determines the version control state of files under SCCS much as
+with RCS.  It does not consider SCCS version headers, though.  Thus,
+the variable @code{vc-mistrust-permissions} affects SCCS use, but
address@hidden does not.
+
address@hidden CVS Options
address@hidden Options specific for CVS
+
address@hidden locking (CVS)
+  By default, CVS does not use locking to coordinate the activities of
+several users; anyone can change a work file at any time.  However,
+there are ways to restrict this, resulting in behavior that resembles
+locking.
+
address@hidden CVSREAD environment variable (CVS)
+  For one thing, you can set the @env{CVSREAD} environment variable
+(the value you use makes no difference).  If this variable is defined,
+CVS makes your work files read-only by default.  In Emacs, you must
+type @kbd{C-x v v} to make the file writable, so that editing works
+in fact similar as if locking was used.  Note however, that no actual
+locking is performed, so several users can make their files writable
+at the same time.  When setting @env{CVSREAD} for the first time, make
+sure to check out all your modules anew, so that the file protections
+are set correctly.
+
address@hidden cvs watch feature
address@hidden watching files (CVS)
+  Another way to achieve something similar to locking is to use the
address@hidden feature of CVS.  If a file is being watched, CVS makes it
+read-only by default, and you must also use @kbd{C-x v v} in Emacs to
+make it writable.  VC calls @code{cvs edit} to make the file writable,
+and CVS takes care to notify other developers of the fact that you
+intend to change the file.  See the CVS documentation for details on
+using the watch feature.
+
address@hidden vc-stay-local
address@hidden vc-cvs-stay-local
address@hidden remote repositories (CVS)
+  When a file's repository is on a remote machine, VC tries to keep
+network interactions to a minimum.  This is controlled by the variable
address@hidden  There is another variable,
address@hidden, which enables the feature also for other back
+ends that support it, including CVS.  In the following, we will talk
+only about @code{vc-cvs-stay-local}, but everything applies to
address@hidden as well.
+
+If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses
+only the entry in the local CVS subdirectory to determine the file's
+state (and possibly information returned by previous CVS commands).
+One consequence of this is that when you have modified a file, and
+somebody else has already checked in other changes to the file, you
+are not notified of it until you actually try to commit.  (But you can
+try to pick up any recent changes from the repository first, using
address@hidden v m @key{RET}}, @pxref{Merging,,,emacs, the Emacs Manual}).
+
+  When @code{vc-cvs-stay-local} is @code{t}, VC also makes local
+version backups, so that simple diff and revert operations are
+completely local (@pxref{Version Backups}).
+
+  On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil},
+then VC queries the remote repository @emph{before} it decides what to
+do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local
+repositories.  It also does not make any version backups.
+
+  You can also set @code{vc-cvs-stay-local} to a regular expression
+that is matched against the repository host name; VC then stays local
+only for repositories from hosts that match the pattern.
+
address@hidden vc-cvs-global-switches
+  You can specify additional command line options to pass to all CVS
+operations in the variable @code{vc-cvs-global-switches}.  These
+switches are inserted immediately after the @code{cvs} command, before
+the name of the operation to invoke.
+
+
 @node Fortran
 @chapter Fortran Mode
 @cindex Fortran mode