[Emacs-diffs] /srv/bzr/emacs/trunk r106691: More updates for VC documentation.

[Chong Yidong]

------------------------------------------------------------
revno: 106691
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-12-17 15:50:08 +0800
message:
  More updates for VC documentation.
  
  * doc/emacs/maintaining.texi (VCS Concepts): Make "revision" terminology
  less CVS-specific.
  (VC With A Merging VCS, VC With A Locking VCS): Add xref to
  Registering node.
  (Secondary VC Commands): Deleted.  Promote subnodes.
  (Log Buffer): Add command name for C-c C-c.  Fix the name of the
  log buffer.  Add index entries.
  (VCS Changesets, Types of Log File, VC With A Merging VCS): Use
  "commit" terminology.
  (Old Revisions): Move it to just before VC Change Log.  "Tag" here
  doesn't refer to tags tables.  Note other possible forms of the
  revision ID.  C-x v = does not save.
  (Registering): Note similarity to C-x v v action.  Fix description
  of how backends are chosen.  De-document vc-default-init-revision.
  (VC Change Log): Document C-x v l in VC-Dir buffer.  Document RET
  in root log buffers.
  
  * lisp/vc/vc.el (vc-deduce-fileset): Minor doc fix.
modified:
  doc/emacs/ChangeLog
  doc/emacs/emacs.texi
  doc/emacs/maintaining.texi
  etc/NEWS
  lisp/ChangeLog
  lisp/vc/vc.el

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-12-16 16:05:59 +0000
+++ b/doc/emacs/ChangeLog       2011-12-17 07:50:08 +0000
@@ -1,3 +1,22 @@
+2011-12-17  Chong Yidong  <address@hidden>
+
+       * maintaining.texi (VCS Concepts): Make "revision" terminology
+       less CVS-specific.
+       (VC With A Merging VCS, VC With A Locking VCS): Add xref to
+       Registering node.
+       (Secondary VC Commands): Deleted.  Promote subnodes.
+       (Log Buffer): Add command name for C-c C-c.  Fix the name of the
+       log buffer.  Add index entries.
+       (VCS Changesets, Types of Log File, VC With A Merging VCS): Use
+       "commit" terminology.
+       (Old Revisions): Move it to just before VC Change Log.  "Tag" here
+       doesn't refer to tags tables.  Note other possible forms of the
+       revision ID.  C-x v = does not save.
+       (Registering): Note similarity to C-x v v action.  Fix description
+       of how backends are chosen.  De-document vc-default-init-revision.
+       (VC Change Log): Document C-x v l in VC-Dir buffer.  Document RET
+       in root log buffers.
+
 2011-12-16  Chong Yidong  <address@hidden>
 
        * maintaining.texi (Version Control Systems): Drop Meta-CVS.

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-12-12 07:25:58 +0000
+++ b/doc/emacs/emacs.texi      2011-12-17 07:50:08 +0000
@@ -741,15 +741,17 @@
 * VC Mode Line::        How the mode line shows version control status.
 * Basic VC Editing::    How to edit a file under version control.
 * Log Buffer::          Features available in log entry buffers.
+* Registering::         Putting a file under version control.
 * Old Revisions::       Examining and comparing old versions.
-* Secondary VC Commands:: The commands used a little less frequently.
+* VC Change Log::       Viewing the VC Change Log.
+* VC Undo::             Canceling changes before or after committing.
 * VC Directory Mode::   Listing files managed by version control.
 * Branches::            Multiple lines of development.
 * Remote Repositories:: Efficient access to remote CVS servers.
 * Revision Tags::       Symbolic names for revisions.
 * Miscellaneous VC::    Various other commands and features of VC.
 * Customizing VC::      Variables that change VC's behavior.
-  
+
 Introduction to Version Control
 
 * Why Version Control?::    Understanding the problems it addresses.
@@ -766,12 +768,6 @@
 * VC With A Locking VCS::  RCS in its default mode, SCCS, and optionally CVS.
 * Advanced C-x v v::       Advanced features available with a prefix argument.
 
-The Secondary Commands of VC
-
-* Registering::         Putting a file under version control.
-* VC Change Log::       Viewing the VC Change Log.
-* VC Undo::             Canceling changes before or after check-in.
-
 VC Directory Mode
 
 * VC Directory Buffer::   What the buffer looks like and means.

=== modified file 'doc/emacs/maintaining.texi'
--- a/doc/emacs/maintaining.texi        2011-12-17 06:51:13 +0000
+++ b/doc/emacs/maintaining.texi        2011-12-17 07:50:08 +0000
@@ -49,8 +49,10 @@
 * VC Mode Line::        How the mode line shows version control status.
 * Basic VC Editing::    How to edit a file under version control.
 * Log Buffer::          Features available in log entry buffers.
+* Registering::         Putting a file under version control.
 * Old Revisions::       Examining and comparing old versions.
-* Secondary VC Commands::    The commands used a little less frequently.
+* VC Change Log::       Viewing the VC Change Log.
+* VC Undo::             Canceling changes before or after committing.
 * VC Directory Mode::   Listing files managed by version control.
 * Branches::            Multiple lines of development.
 @ifnottex
@@ -171,14 +173,14 @@
 @item
 Git is a distributed version control system originally invented by
 Linus Torvalds to support development of Linux (his kernel).  VC
-supports many common git operations, but others, such as repository
+supports many common Git operations, but others, such as repository
 syncing, must be done from the command line.
 
 @cindex hg
 @cindex Mercurial
 @item
 Mercurial (hg) is a distributed version control system broadly
-resembling git.  VC supports most Mercurial commands, with the
+resembling Git.  VC supports most Mercurial commands, with the
 exception of repository sync operations.
 
 @cindex bzr
@@ -206,16 +208,16 @@
   The copy of a version-controlled file that you actually edit is
 called the @dfn{work file}.  You can change each work file as you
 would an ordinary file.  After you are done with a set of changes, you
address@hidden (or @dfn{check in}) the changes; this records the changes
-in the repository, along with a descriptive log entry.
+may @dfn{commit} (or @dfn{check in}) the changes; this records the
+changes in the repository, along with a descriptive log entry.
 
 @cindex revision
 @cindex revision ID
-  A copy of a file stored in a repository is called a @dfn{revision}.
-The history of a file is a sequence of revisions.  Each revision is
-named by a @dfn{revision ID}.  The format of the revision ID depends
-on the version control system; in the simplest case, it is just an
-integer.
+  Each commit creates a new @dfn{revision} in the repository.  The
+version control system keeps track of all past revisions and the
+changes that were made in each revision.  Each revision is named by a
address@hidden ID}, whose format depends on the version control system;
+in the simplest case, it is just an integer.
 
   To go beyond these basic concepts, you will need to understand three
 aspects in which version control systems differ.  As explained in the
@@ -231,10 +233,10 @@
 between users who want to change the same file.  There are two ways to
 do this: merging and locking.
 
-  In a version control system that uses merging, each user may check
-out and modify a work file at any time.  The system lets you
address@hidden your work file, which may contain changes that have not
-been committed, with the latest changes that others have committed.
+  In a version control system that uses merging, each user may modify
+a work file at any time.  The system lets you @dfn{merge} your work
+file, which may contain changes that have not been committed, with the
+latest changes that others have committed.
 
   Older version control systems use a @dfn{locking} scheme instead.
 Here, work files are normally read-only.  To edit a file, you ask the
@@ -277,7 +279,7 @@
 control operations are @dfn{file-based}: each file has its own comment
 and revision history separate from that of all other files.  Newer
 systems, beginning with Subversion, are @dfn{changeset-based}: a
-checkin may include changes to several files, and the entire set of
+commit may include changes to several files, and the entire set of
 changes is handled as a unit.  Any comment associated with the change
 does not belong to a single file, but to the changeset itself.
 
@@ -342,10 +344,9 @@
   When the policy is to use both, you typically want to write an entry
 for each change just once, then put it into both logs.  You can write
 the entry in @file{ChangeLog}, then copy it to the log buffer with
address@hidden C-a} when checking in the change (@pxref{Log Buffer}).  Or
-you can write the entry in the log buffer while checking in the
-change, and later use the @kbd{C-x v a} command to copy it to
address@hidden
address@hidden C-a} when committing the change (@pxref{Log Buffer}).  Or you
+can write the entry in the log buffer while committing the change, and
+later use the @kbd{C-x v a} command to copy it to @file{ChangeLog}
 @iftex
 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
 @end iftex
@@ -450,23 +451,25 @@
 @itemize @bullet
 @item
 If there is more than one file in the VC fileset and the files have
-inconsistent version control states, signal an error.
-
address@hidden
-If each file in the VC fileset is not registered with a version
-control system, register the VC fileset.  If the fileset is in a
-directory controlled by a version control system, register it with
-that system; otherwise, prompt for a repository type, create a new
-repository, and register the VC fileset with it.
-
address@hidden
-If each work file in the VC fileset is unchanged, do nothing.
-
address@hidden
-If each work file in the VC fileset has been modified, commit the
+inconsistent version control states, signal an error.  (Note, however,
+that a fileset is allowed to include both ``newly-added'' files and
+``modified'' files; @pxref{Registering}.)
+
address@hidden
+If none of the files in the VC fileset are registered with a version
+control system, register the VC fileset, i.e.@: place it under version
+control.  @xref{Registering}.  If Emacs cannot find a system to
+register under, it prompts for a repository type, creates a new
+repository, and registers the VC fileset with it.
+
address@hidden
+If every work file in the VC fileset is unchanged, do nothing.
+
address@hidden
+If every work file in the VC fileset has been modified, commit the
 changes.  To do this, Emacs pops up a @samp{*vc-log*} buffer; type the
 desired log entry for the new revision, followed by @kbd{C-c C-c} to
-commit (@pxref{Log Buffer}).
+commit.  @xref{Log Buffer}.
 
 If committing to a shared repository, the commit may fail if the
 repository that has been changed since your last update.  In that
@@ -487,7 +490,7 @@
 file since you began editing it; when you commit your revision, his
 changes are removed (however, they remain in the repository and are
 thus not irrevocably lost).  Therefore, you must verify that the
-current revision is unchanged before checking in your changes.  In
+current revision is unchanged before committing your changes.  In
 addition, locking is possible with RCS even in this mode: @kbd{C-x v
 v} with an unmodified file locks the file, just as it does with RCS in
 its normal locking mode (@pxref{VC With A Locking VCS}).
@@ -505,10 +508,10 @@
 
 @item
 If each file in the VC fileset is not registered with a version
-control system, register the VC fileset.  If the fileset is in a
-directory controlled by a version control system, register it with
-that system; otherwise, prompt for a repository type, create a new
-repository, and register the VC fileset with it.
+control system, register the VC fileset.  @xref{Registering}.  If
+Emacs cannot find a system to register under, it prompts for a
+repository type, creates a new repository, and registers the VC
+fileset with it.
 
 @item
 If each file is registered and unlocked, lock it and make it writable,
@@ -575,13 +578,23 @@
 @node Log Buffer
 @subsection Features of the Log Entry Buffer
 
-  When you tell VC to commit a change, it pops up a buffer called
address@hidden  In this buffer, you should write a @dfn{log entry}
address@hidden C-c C-c @r{(Log Edit mode)}
address@hidden log-edit-done
+  When you tell VC to commit a change, it pops up a buffer named
address@hidden  In this buffer, you should write a @dfn{log entry}
 describing the changes you have made (@pxref{Why Version Control?}).
-After you are done, type @kbd{C-c C-c}; this exits the buffer and
-commits the change, together with your log entry.
-
-  While in the @samp{*VC-Log*} buffer, you can write one or more
+After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
+the buffer and commit the change, together with your log entry.
+
address@hidden Log Edit mode
address@hidden mode, Log Edit
address@hidden vc-log-mode-hook
+  The major mode for the @samp{*vc-log*} buffer is Log Edit mode, a
+variant of Text mode (@pxref{Text Mode}).  On entering Log Edit mode,
+Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
+(@pxref{Hooks}).
+
+  While in the @samp{*vc-log*} buffer, you can write one or more
 @dfn{header lines}, specifying additional information to be supplied
 to the version control system.  Each header line must occupy a single
 line at the top of the buffer; the first line that is not a header
@@ -598,196 +611,224 @@
 @samp{Date} (a manually-specified commit time) and @samp{Fixes} (a
 reference to a bug fixed by the change).  Not all version control
 systems recognize all headers: Bazaar recognizes all three headers,
-while git, Mercurial, and Monotone recognizes only @samp{Author} and
address@hidden  If you specify a header for a version control that
-does not support it, the header is treated as part of the log entry.
+while Git, Mercurial, and Monotone recognize only @samp{Author} and
address@hidden  If you specify a header for a version control that does
+not support it, the header is treated as part of the log entry.
 
address@hidden C-c C-f @r{(Log Edit mode)}
 @findex log-edit-show-files
+  Type @kbd{C-c C-f} (@code{log-edit-show-files}) in the
address@hidden buffer to view a list of files for the VC fileset that
+is to be committed.  If you called @kbd{C-x v v} directly from a work
+file, the fileset consists of that single file.  If you called
address@hidden v v} from a VC directory buffer (@pxref{VC Directory Mode}),
+the fileset may consist of multiple files; in that case, @kbd{C-c C-c}
+will commit those files together, as a single revision, if that is
+supported by the version control system (on older version control
+systems, such as CVS, each file in a multi-file VC fileset is
+committed as an individual revision).
+
address@hidden C-c C-d @r{(Log Edit mode)}
 @findex log-edit-show-diff
-  Type @kbd{C-c C-f} (@code{log-edit-show-files}) to display a list of
-files in the current VC fileset.  If you called @kbd{C-x v v} directly
-from a work file, the fileset consists of that single file; if you
-called @kbd{C-x v v} from a VC directory buffer (@pxref{VC Directory
-Mode}), the fileset may consist of multiple files.
+  Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a @dfn{diff}
+of the changes between the current VC fileset and the repository
+revision from which you started editing.  @xref{Old Revisions}.
 
address@hidden C-c C-a @r{(Log Edit mode)}
 @findex log-edit-insert-changelog
-  Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a @dfn{diff}
-of the changes you have made (i.e., the differences between the work
-file and the repository revision from which you started editing).
address@hidden Revisions}.
-
-  If the current VC fileset includes one or more @file{ChangeLog}
-files (@pxref{Change Log}), type @kbd{C-c C-a}
+  If the VC fileset that is to be committed includes one or more
address@hidden files (@pxref{Change Log}), type @kbd{C-c C-a}
 (@code{log-edit-insert-changelog}) to pull the relevant entries into
-the @samp{*VC-Log*} buffer.  If the topmost item in each
+the @samp{*vc-log*} buffer.  If the topmost item in each
 @file{ChangeLog} was made under your user name on the current date,
-this command searches that item for entries that match the file(s) to
-be committed; if found, these entries are inserted.
address@hidden
address@hidden Logs and VC,,,emacs-xtra, Specialized Emacs Features},
address@hidden iftex
+this command searches that item for entries matching the file(s) to be
+committed, and inserts them.
 @ifnottex
address@hidden Logs and VC},
address@hidden Logs and VC}, for the opposite way of
+working---generating ChangeLog entries from the revision control log.
 @end ifnottex
-for the opposite way of working---generating ChangeLog entries from
-the revision control log.
 
-  To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that
+  To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that
 buffer.  You can switch buffers and do other editing.  As long as you
-don't try to commit another file, the entry you were editing remains
-in the @samp{*VC-Log*} buffer, and you can go back to that buffer at
-any time to complete the check-in.
-
-  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.  (This
-is the normal way to do things on a changeset-oriented system, where
-comments are attached to changesets rather than the history of
-individual files.)  The most convenient way to do this is to mark all
-the files in VC Directory Mode and commit from there; the log buffer
-will carry the fileset information with it and do a group commit when
-you type @kbd{C-c C-c}.
-
+don't try to make another commit, the entry you were editing remains
+in the @samp{*vc-log*} buffer, and you can go back to that buffer at
+any time to complete the commit.
+
address@hidden M-n @r{(Log Edit mode)}
address@hidden M-p @r{(Log Edit mode)}
address@hidden M-s @r{(Log Edit mode)}
address@hidden M-r @r{(Log Edit mode)}
   You can also browse the history of previous log entries to duplicate
-a checkin comment. This can be useful when you want several files to
-have checkin comments that vary only slightly from each other. The
-commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this
-work just like the minibuffer history commands (except that these
-versions are used outside the minibuffer).
-
address@hidden vc-log-mode-hook
-  Each time you commit a change, the log entry buffer is put into VC
-Log Edit mode, which involves running two hooks: @code{text-mode-hook}
-and @code{vc-log-mode-hook}.  @xref{Hooks}.
+a commit comment.  This can be useful when you want to make several
+commits with similar comments.  The commands @kbd{M-n}, @kbd{M-p},
address@hidden and @kbd{M-r} for doing this work just like the minibuffer
+history commands (@pxref{Minibuffer History}), except that they are
+used outside the minibuffer.
+
address@hidden Registering
address@hidden Registering a File for Version Control
+
address@hidden @kbd
address@hidden C-x v i
+Register the visited file for version control.
address@hidden table
+
address@hidden C-x v i
address@hidden vc-register
+  The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each
+file in the current VC fileset, placing it under version control.
+This is essentially equivalent to the action of @kbd{C-x v v} on an
+unregistered VC fileset (@pxref{Basic VC Editing}), except that if the
+VC fileset is already registered, @kbd{C-x v i} signals an error
+whereas @kbd{C-x v v} performs some other action.
+
+  To register a file, Emacs must choose a version control system.  For
+a multi-file VC fileset, the VC Directory buffer specifies the system
+to use (@pxref{VC Directory Mode}).  For a single-file VC fileset, if
+the file's directory already contains files registered in a version
+control system, or if the directory is part of a directory tree
+controlled by a version control system, Emacs chooses that system.  In
+the event that more than one version control system is applicable,
+Emacs uses the one that appears first in the variable
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden (@pxref{Customizing VC}).
address@hidden ifnottex
+If Emacs cannot find a version control system to register the file
+under, it prompts for a repository type, creates a new repository, and
+registers the file into that repository.
+
+  On most version control systems, registering a file with @kbd{C-x v
+i} or @kbd{C-x v v} adds it to the ``working tree'' but not to the
+repository.  Such files are labeled as @samp{added} in the VC
+Directory buffer, and show a revision ID of @samp{@@@@} in the mode
+line.  To make the registration take effect in the repository, you
+must perform a commit (@pxref{Basic VC Editing}).  Note that on
+changeset-based version control systems, commits can consist of both
+file additions and modifications.
+
+  On a locking-based version control system (@pxref{VCS Merging}),
+registering a file leaves it unlocked and read-only.  Type @kbd{C-x v
+v} if you wish to start editing it.
 
 @node Old Revisions
 @subsection Examining And Comparing Old Revisions
 
-  One of the convenient features of version control is the ability
-to examine any revision of a file, or compare two revisions.
-
 @table @kbd
address@hidden C-x v ~
-Prompt for a revision of the current file, and visit it in a buffer of
-its own (@code{vc-revision-other-window}).
-
 @item C-x v =
-Compare the files in the current fileset with the working revision(s)
-you started from (@code{vc-diff}).  With a prefix argument, prompt for
-two revisions of the current fileset and compare them.  You can call
-this command from a Dired buffer (@pxref{Dired}).
+Compare the work files in the current VC fileset with the versions you
+started from (@code{vc-diff}).  With a prefix argument, prompt for two
+revisions of the current VC fileset and compare them.  You can also
+call this command from a Dired buffer (@pxref{Dired}).
+
address@hidden
address@hidden M-x vc-ediff
+Like @kbd{C-x v =}, but using an Ediff session.  @xref{Top, Ediff,
+ediff, The Ediff Manual}.
address@hidden ifnottex
 
 @item C-x v D
-Compare the entire tree corresponding to the current fileset with the
-tree you started from (@code{vc-root-diff}).  With a prefix argument,
-prompt for two revisions and compare their trees.
+Compare all work files in the current version controlled directory
+tree to the tree you started from (@code{vc-root-diff}).  With a
+prefix argument, prompt for two revisions and compare their trees.
+
address@hidden C-x v ~
+Prompt for a revision of the current file, and visit it in a separate
+buffer (@code{vc-revision-other-window}).
 
 @item C-x v g
-Display an annotated version of the file: for each line, show the
-latest revision in which it was modified (@code{vc-annotate}).
+Display an annotated version of the current file: for each line, show
+the latest revision in which it was modified (@code{vc-annotate}).
 @end table
 
address@hidden vc-revision-other-window
address@hidden C-x v ~
-  To examine an old revision, visit the work file and type @kbd{C-x v
-~ @var{revision} @key{RET}} (@code{vc-revision-other-window}).  Here,
address@hidden is either the desired revision ID (@pxref{VCS
-Concepts}), or the name of a tag or branch
address@hidden
-(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Tags}).
address@hidden ifnottex
-This command puts the text of the old revision in a file named
address@hidden@address@hidden, and visits it in its own
-buffer in a separate window.
-
 @findex vc-diff
 @kindex C-x v =
-  @kbd{C-x v =} (@code{vc-diff}) compares each file in the current VC
-fileset (saving them if necessary) with the repository revision(s)
-from which you started editing.  Note that the latter may or may not
-be the latest revision of the file(s).
-
-  The diff is displayed in another window, in a Diff mode buffer
-(@pxref{Diff Mode}) named @file{*vc-diff*}.  In this buffer, the
address@hidden (@code{revert-buffer}) command performs the file comparison
-again, generating a new diff.
-
address@hidden vc-diff
+  @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares
+each work file in the current VC fileset to the version(s) from which
+you started editing.  The diff is displayed in another window, in a
+Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}.  The
+usual Diff mode commands are available in this buffer.  In particular,
+the @kbd{g} (@code{revert-buffer}) command performs the file
+comparison again, generating a new diff.
+
 @kindex C-u C-x v =
   To compare two arbitrary revisions of the current VC fileset, call
 @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}.  This
-prompts for two revision IDs, using the minibuffer, and displays the
-diff in a special buffer in another window.  Instead of providing a
-revision ID, you can give an empty input, which specifies the current
-contents of the work file; or a tag or branch name
address@hidden
-(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
+prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
+diff between those versions of the fileset.  This will not work
+reliably for multi-file VC filesets, if the version control system is
+file-based rather than changeset-based (e.g.@: CVS), since then
+revision IDs for different files would not be related in any
+meaningful way.
+
+  Instead of the revision ID, some version control systems let you
+specify revisions in other formats.  For instance, under Bazaar you
+can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =}
+(and related commands) to specify the first revision committed after
+yesterday.  See the documentation of the version control system for
+details.
+
+  If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
+(@pxref{Dired}), the file listed on the current line is treated as the
+current VC fileset.
+
 @ifnottex
-(@pxref{Tags}).
address@hidden ifnottex
-If your version control system is file-based (e.g. CVS) rather than
-changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a
-revision ID for a multi-file fileset (as opposed to a symbolic tag
-name) is unlikely to return diffs that are connected in any meaningful
-way.
-
-  The command @kbd{C-x v D} (@code{vc-root-diff}) is similar to
address@hidden v =}, but it compares the entire tree associated with the
-current VC fileset with the tree you started with.  This means all the
-files controlled by the current version control repository, even those
-that are not part of the current VC fileset.
-
-  If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that
-is neither visiting a version-controlled file nor a VC directory
-buffer, these commands generate a diff of all registered files in the
-current directory and its subdirectories.
-
 @findex vc-ediff
-The function @code{vc-ediff} works like @code{vc-diff} and provides a way to
-visually compare two revisions of a file in an Ediff session, @pxref{Top,
-Ediff, ediff, The Ediff Manual}.  It compares the file associated with the
-current buffer with the last repository revision.  To compare two arbitrary
-revisions of the current file, call @code{vc-ediff} with a prefix argument.
+  @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
+Ediff session.  @xref{Top, Ediff, ediff, The Ediff Manual}.
address@hidden ifnottex
+
address@hidden vc-root-diff
address@hidden C-x v D
+  @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
+it displays a comparison between the entire current version controlled
+tree (i.e.@: the tree controlled by the version control system
+associated with the current VC fileset, which may include files that
+are not part of that fileset) and the tree you started with.  If you
+invoke this command from a Dired buffer, it applies to the entire
+version controlled tree containing the directory.
 
 @vindex vc-diff-switches
address@hidden vc-rcs-diff-switches
-  @kbd{C-x v =} works by running a variant of the @code{diff} utility
-designed to work with the version control system in use.  The options
-to pass to the @code{diff} command are taken from the first address@hidden
-value of @address@hidden, @code{vc-diff-switches},
-and @code{diff-switches} (@pxref{Comparing Files}), in that order.
-Since @code{nil} means to check the next variable in the sequence,
-either of the first two may use the value @code{t} to mean no switches at all.
-Most of the @address@hidden variables default to
address@hidden, but some default to @code{t}.  These are for those version
-control systems (e.g. SVN) whose @code{diff} implementations do not
-accept common options (e.g. @samp{-c}) likely to be in
address@hidden
+  You can customize the @command{diff} options that @kbd{C-x v =} and
address@hidden v D} use for generating diffs.  The options used are taken
+from the first address@hidden value amongst the variables
address@hidden@var{backend}-diff-switches}, @code{vc-diff-switches}, and
address@hidden (@pxref{Comparing Files}), in that order.  Here,
address@hidden stands for the current version control system,
+e.g.@: @code{bzr} for Bazaar.  Since @code{nil} means to check the
+next variable in the sequence, either of the first two may use the
+value @code{t} to mean no switches at all.  Most of the
address@hidden@var{backend}-diff-switches} variables default to @code{nil},
+but some default to @code{t}; these are for version control systems,
+such as Subversion, whose @code{diff} implementations do not accept
+common diff options.
 
-  The buffer produced by @kbd{C-x v =} supports the commands of
-Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and
address@hidden C-c}, in both the ``old'' and ``new'' text, and they always
-find the corresponding locations in the current work file.  (Older
-revisions are not, in general, present as files on your disk.)
address@hidden vc-revision-other-window
address@hidden C-x v ~
+  To directly examine an older version of a file, visit the work file
+and type @kbd{C-x v ~ @var{revision} @key{RET}}
+(@code{vc-revision-other-window}).  This retrieves the file version
+corresponding to @var{revision}, saves it to
address@hidden@address@hidden, and visits it in a separate
+window.
 
 @findex vc-annotate
 @kindex C-x v g
-  For some back ends, you can display the file @dfn{annotated} with
-per-line revision information, by typing @kbd{C-x v g}
+  Many version control systems allow you to view files @dfn{annotated}
+with per-line revision information, by typing @kbd{C-x v g}
 (@code{vc-annotate}).  This creates a new buffer (the ``annotate
-buffer'') displaying the file's text, with each part colored to show
-how old it is.  Text colored red is new, blue means old, and
-intermediate colors indicate intermediate ages.  By default, the color
-is scaled over the full range of ages, such that the oldest changes
-are blue, and the newest changes are red.
+buffer'') displaying the file's text, with each line colored to show
+how old it is.  Red text is new, blue is old, and intermediate colors
+indicate intermediate ages.  By default, the color is scaled over the
+full range of ages, such that the oldest changes are blue, and the
+newest changes are red.
 
   When you give a prefix argument to this command, Emacs reads two
-arguments using the minibuffer: the ID of which revision to display and
-annotate (instead of the current file contents), and the time span in
-days the color range should cover.
+arguments using the minibuffer: the revision to display and annotate
+(instead of the current file contents), and the time span in days the
+color range should cover.
 
   From the annotate buffer, these and other color scaling options are
 available from the @samp{VC-Annotate} menu.  In this buffer, you can
@@ -796,13 +837,13 @@
 
 @table @kbd
 @item p
-Annotate the previous revision, that is to say, the revision before
-the one currently annotated.  A numeric prefix argument is a repeat
-count, so @kbd{C-u 10 p} would take you back 10 revisions.
+Annotate the previous revision, i.e.@: the revision before the one
+currently annotated.  A numeric prefix argument is a repeat count, so
address@hidden 10 p} would take you back 10 revisions.
 
 @item n
-Annotate the next revision---the one after the revision currently
-annotated.  A numeric prefix argument is a repeat count.
+Annotate the next revision, i.e.@: the revision after the one
+currently annotated.  A numeric prefix argument is a repeat count.
 
 @item j
 Annotate the revision indicated by the current line.
@@ -841,72 +882,8 @@
 the file contents without distraction from the annotations.
 @end table
 
address@hidden Secondary VC Commands
address@hidden The Secondary Commands of VC
-
-  This section explains the secondary commands of VC.
-
address@hidden
-* Registering::         Putting a file under version control.
-* VC Change Log::       Viewing the VC Change Log.
-* VC Undo::             Canceling changes before or after check-in.
address@hidden menu
-
address@hidden Registering
address@hidden Registering a File for Version Control
-
address@hidden C-x v i
address@hidden vc-register
-  You can put any file under version control by simply visiting it, and
-then typing @address@hidden v i}} (@code{vc-register}).
-
address@hidden @kbd
address@hidden C-x v i
-Register the visited file for version control.
address@hidden table
-
-  To register the file, Emacs must choose which version control system
-to use for it.  If the file's directory already contains files
-registered in a version control system, Emacs uses that system.  If
-there is more than one system in use for a directory, Emacs uses the
-one that appears first in @code{vc-handled-backends}
address@hidden
-(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Customizing VC}).
address@hidden ifnottex
-On the other hand, if there are no files already registered, Emacs uses
-the first system from @code{vc-handled-backends} that could register
-the file (for example, you cannot register a file under CVS if its
-directory is not already part of a CVS tree); with the default value
-of @code{vc-handled-backends}, this means that Emacs uses RCS in this
-situation.
-
-  If locking is in use, @kbd{C-x v i} leaves the file unlocked and
-read-only.  Type @kbd{C-x v v} if you wish to start editing it.  After
-registering a file with CVS, you must subsequently commit the initial
-revision by typing @kbd{C-x v v}.  Until you do that, the revision ID
-appears as @samp{@@@@} in the mode line.
-
address@hidden vc-default-init-revision
address@hidden initial revision ID to register
-  The default initial revision ID for a newly registered file
-varies by what VCS you are using; normally it will be 1.1 on VCSes
-that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs.
-You can specify a different default by setting the variable
address@hidden, or you can give @kbd{C-x v i} a
-numeric argument; then it reads the initial revision ID for this
-particular file using the minibuffer.
-
address@hidden See http://debbugs.gnu.org/9745
address@hidden @vindex vc-initial-comment
address@hidden   If @code{vc-initial-comment} is address@hidden, @kbd{C-x v i} 
reads an
address@hidden initial comment to describe the purpose of this source file.  
Reading
address@hidden the initial comment works like reading a log entry (@pxref{Log 
Buffer}).
-
 @node VC Change Log
address@hidden VC Change Log
address@hidden VC Change Log
 
 @table @kbd
 @item C-x v l
@@ -929,21 +906,31 @@
 @kindex C-x v l
 @findex vc-print-log
   The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer
-named @samp{*vc-change-log*} in a new window.  This buffer lists the
-changes to the current file, including the associated log entries.
-(These are the log entries associated with the version control system,
-i.e. the ones you enter via the @samp{*VC-Log*} buffer.  @xref{Log
-Buffer}.)  Point is centered at the revision of the file currently
-being visited.  With a prefix argument, the command prompts for the
-revision to center on, and the maximum number of revisions to display.
-You can call this command from a Dired buffer (@pxref{Dired}).
+named @samp{*vc-change-log*}, showing the history of changes made to
+the current file, including who made the changes, the dates, and the
+log entry for each change (these are the same log entries you would
+enter via the @samp{*vc-log*} buffer; @pxref{Log Buffer}).  Point is
+centered at the revision of the file currently being visited.  With a
+prefix argument, the command prompts for the revision to center on,
+and the maximum number of revisions to display.
+
+  If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
+Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
+file listed on the current line.
 
 @findex vc-print-root-log
-  Type @kbd{C-x v L} (@code{vc-print-root-log}) to display a
address@hidden buffer showing the history of the
-version-controlled directory tree as a whole.  With a prefix argument,
-the command prompts for the maximum number of revisions to display.
-RCS, SCCS, and CVS do not support this feature.
address@hidden log-view-toggle-entry-display
+  @kbd{C-x v L} (@code{vc-print-root-log}) displays a
address@hidden buffer showing the history of the entire
+version-controlled directory tree (RCS, SCCS, and CVS do not support
+this feature).  With a prefix argument, the command prompts for the
+maximum number of revisions to display.
+
+  The @kbd{C-x v L} history is shown in a compact form, usually
+omitting all but the first line of each log entry.  However, you can
+type @key{RET} (@code{log-view-toggle-entry-display}) in the
address@hidden buffer to reveal the entire log entry for the
+revision at point.  A second @key{RET} hides it again.
 
   On a distributed version control system, the @kbd{C-x v I}
 (@code{vc-log-incoming}) command displays a log buffer showing the
@@ -952,62 +939,58 @@
 repository.  This other repository is the default one from which
 changes are pulled, as defined by the version control system; with a
 prefix argument, @code{vc-log-incoming} prompts for a specific
-repository from which changes would be pulled, and lists the changes
-accordingly.  Similarly, @kbd{C-x v O} (@code{vc-log-outgoing}) shows
+repository.  Similarly, @kbd{C-x v O} (@code{vc-log-outgoing}) shows
 the changes that will be sent to another repository, the next time you
 run the ``push'' command; with a prefix argument, it prompts for a
-specific repository to which changes would be pushed.
+specific destination repository.
 
   In the @samp{*vc-change-log*} buffer, you can use the following keys
-to move between the logs of revisions and of files, to view past
-revisions, to modify change comments, to view annotations and to view
-diffs:
+to move between the logs of revisions and of files, and to examine and
+compare past revisions (@pxref{Old Revisions}):
 
 @table @kbd
 @item p
-Move to the previous revision-item in the buffer.  (Revision entries in the log
+Move to the previous revision entry.  (Revision entries in the log
 buffer are usually in reverse-chronological order, so the previous
 revision-item usually corresponds to a newer revision.)  A numeric
 prefix argument is a repeat count.
 
 @item n
-Move to the next revision-item (which most often corresponds to the
-previous revision of the file).  A numeric prefix argument is a repeat
-count.
+Move to the next revision entry.  A numeric prefix argument is a
+repeat count.
 
 @item P
-Move to the log of the previous file, when the logs of multiple files
-are in the log buffer (@pxref{VC Directory Mode}).  Otherwise, just
-move to the beginning of the log.  A numeric prefix argument is a
-repeat count, so @kbd{C-u 10 P} would move backward 10 files.
+Move to the log of the previous file, if showing logs for a multi-file
+VC fileset.  Otherwise, just move to the beginning of the log.  A
+numeric prefix argument is a repeat count.
 
 @item N
-Move to the log of the next file, when the logs of multiple files are
-in the log buffer (@pxref{VC Directory Mode}).  It also takes a
-numeric prefix argument as a repeat count.
+Move to the log of the next file, if showing logs for a multi-file VC
+fileset.  A numeric prefix argument is a repeat count.
 
 @item a
-Annotate the revision indicated by the current line.
+Annotate the revision on the current line (@pxref{Old Revisions}).
 
 @item e
 Modify the change comment displayed at point.  Note that not all VC
 systems support modifying change comments.
 
 @item f
-Visit the revision indicated at the current line, like typing @kbd{C-x
-v ~} and specifying this revision's ID (@pxref{Old Revisions}).
+Visit the revision indicated at the current line.
 
 @item d
-Display the diff (@pxref{Comparing Files}) between the revision
-indicated at the current line and the next earlier revision.  This is
-useful to see what actually changed in the file when the revision
-indicated on the current line was committed.
+Display a diff between the revision at point and the next earlier
+revision, for the specific file.
 
 @item D
-Display the changeset diff (@pxref{Comparing Files}) between the
-revision indicated at the current line and the next earlier revision.
-This is useful to see all the changes to all files that the revision
-indicated on the current line did when it was committed.
+Display the changeset diff between the revision at point and the next
+earlier revision.  This shows the changes to all files made in that
+revision.
+
address@hidden @key{RET}
+In a compact-style log buffer (e.g.@: the one created by @kbd{C-x v
+L}), toggle between showing and hiding the full log entry for the
+revision at point.
 @end table
 
 @vindex vc-log-show-limit
@@ -1021,7 +1004,7 @@
 buffer.  However, RCS, SCCS, and CVS do not support this feature.
 
 @node VC Undo
address@hidden Undoing Version Control Actions
address@hidden Undoing Version Control Actions
 
 @table @kbd
 @item C-x v u
@@ -1030,7 +1013,7 @@
 
 @item C-x v c
 Remove the last-entered change from the master for the visited file.
-This undoes your last check-in.
+This undoes your last commit.
 @end table
 
 @kindex C-x v u
@@ -1133,7 +1116,7 @@
 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
+commit your modified copy of the file, or use a command such as
 @kbd{C-x v m}.
 
   In practice, this is not a problem because CVS handles this case
@@ -1330,7 +1313,7 @@
 not the head of a branch.
 
   After the branch is created, you ``stay'' on it.  That means that
-subsequent check-ins create new revisions on that branch.  To leave the
+subsequent commits create new revisions on that branch.  To leave the
 branch, you must explicitly select a different revision with @kbd{C-u C-x
 v v}.  To transfer changes from one branch to another, use the merge
 command, described in the next section.
@@ -1379,7 +1362,7 @@
 revision 1.6 containing the changes from the branch.
 
   It is possible to do further editing after merging the branch, before
-the next check-in.  But it is usually wiser to commit the merged
+the next commit.  But it is usually wiser to commit the merged
 revision, then lock it and make the further changes.  This will keep
 a better record of the history of changes.
 

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-12-12 07:25:58 +0000
+++ b/etc/NEWS  2011-12-17 07:50:08 +0000
@@ -852,6 +852,7 @@
 *** New option `vc-revert-show-diff' controls whether `vc-revert'
 shows a diff while querying the user.  It defaults to t.
 
++++
 *** Log entries in some Log View buffers can be toggled to display a
 longer description by typing RET (log-view-toggle-entry-display).
 In the Log View buffers made by `C-x v L' (vc-print-root-log), you can
@@ -862,6 +863,7 @@
 **** Packages using Log View mode can enable this functionality by
 binding `log-view-expanded-log-entry-function' to a suitable function.
 
++++
 *** New command `vc-ediff' allows visual comparison of two revisions
 of a file similar to `vc-diff', but using ediff backend.
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2011-12-16 15:55:00 +0000
+++ b/lisp/ChangeLog    2011-12-17 07:50:08 +0000
@@ -1,6 +1,7 @@
-2011-12-16  Chong Yidong  <address@hidden>
+2011-12-17  Chong Yidong  <address@hidden>
 
        * vc/vc.el (vc-next-action): Doc fix; remove CVS-isms.
+       (vc-deduce-fileset): Doc fix.
 
 2011-12-16  Andreas Schwab  <address@hidden>
 

=== modified file 'lisp/vc/vc.el'
--- a/lisp/vc/vc.el     2011-12-16 15:55:00 +0000
+++ b/lisp/vc/vc.el     2011-12-17 07:50:08 +0000
@@ -951,13 +951,13 @@
 (defun vc-deduce-fileset (&optional observer allow-unregistered
                                    state-model-only-files)
   "Deduce a set of files and a backend to which to apply an operation.
-
 Return (BACKEND FILESET FILESET-ONLY-FILES STATE CHECKOUT-MODEL).
-If we're in VC-dir mode, the fileset is the list of marked files.
-Otherwise, if we're looking at a buffer visiting a version-controlled file,
-the fileset is a singleton containing this file.
-If none of these conditions is met, but ALLOW_UNREGISTERED is on and the
-visited file is not registered, return a singleton fileset containing it.
+
+If we're in VC-dir mode, FILESET is the list of marked files.
+Otherwise, if in a buffer visiting a version-controlled file,
+FILESET is a single-file fileset containing that file.
+Otherwise, if ALLOW-UNREGISTERED is non-nil and the visited file
+is unregistered, FILESET is a single-file fileset containing it.
 Otherwise, throw an error.
 
 STATE-MODEL-ONLY-FILES if non-nil, means that the caller needs