[Emacs-diffs] /srv/bzr/emacs/trunk r106687: Fixes for Maintaining chapter of Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106687
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-12-17 00:05:59 +0800
message:
  Fixes for Maintaining chapter of Emacs manual.
  
  * doc/emacs/maintaining.texi (Version Control Systems): Drop Meta-CVS.
  (Basic VC Editing): Remove redundant descriptions.
  (VC With A Merging VCS): Make description more general instead of
  CVS-specific.
  (VC With A Locking VCS): Use VC fileset terminology.
modified:
  doc/emacs/ChangeLog
  doc/emacs/building.texi
  doc/emacs/maintaining.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-12-12 07:25:58 +0000
+++ b/doc/emacs/ChangeLog       2011-12-16 16:05:59 +0000
@@ -1,3 +1,11 @@
+2011-12-16  Chong Yidong  <address@hidden>
+
+       * maintaining.texi (Version Control Systems): Drop Meta-CVS.
+       (Basic VC Editing): Remove redundant descriptions.
+       (VC With A Merging VCS): Make description more general instead of
+       CVS-specific.
+       (VC With A Locking VCS): Use VC fileset terminology.
+
 2011-12-12  Chong Yidong  <address@hidden>
 
        * building.texi (Executing Lisp): Fix xref for C-M-x.

=== modified file 'doc/emacs/building.texi'
--- a/doc/emacs/building.texi   2011-12-12 07:25:58 +0000
+++ b/doc/emacs/building.texi   2011-12-16 16:05:59 +0000
@@ -24,9 +24,9 @@
 * Executing Lisp::      Various modes for editing Lisp programs,
                           with different facilities for running
                           the Lisp programs.
-* Lisp Libraries::      How Lisp programs are loaded into Emacs.
-* Lisp Eval::           Executing a single Lisp expression in Emacs.
-* Lisp Interaction::    Executing Lisp in an Emacs buffer.
+* Libraries: Lisp Libraries.      How Lisp programs are loaded into Emacs.
+* Eval: Lisp Eval.      Executing a single Lisp expression in Emacs.
+* Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
 * External Lisp::       Communicating through Emacs with a separate Lisp.
 @end menu
 

=== modified file 'doc/emacs/maintaining.texi'
--- a/doc/emacs/maintaining.texi        2011-10-18 06:52:32 +0000
+++ b/doc/emacs/maintaining.texi        2011-12-16 16:05:59 +0000
@@ -71,7 +71,7 @@
 
   Some uncommon or intricate version control operations, such as
 altering repository settings, are not supported in VC.  You should
-perform such tasks outside Emacs, e.g. via the command line.
+perform such tasks outside Emacs, e.g.@: via the command line.
 
   This section provides a general overview of version control, and
 describes the version control systems that VC supports.  You can skip
@@ -125,7 +125,7 @@
 @item
 SCCS was the first version control system ever built, and was long ago
 superseded by more advanced ones.  VC compensates for certain features
-missing in SCCS (e.g., tag names for releases) by implementing them
+missing in SCCS (e.g.@: tag names for releases) by implementing them
 itself.  Other VC features, such as multiple branches, are simply
 unavailable.  Since SCCS is non-free, we recommend avoiding it.
 
@@ -154,7 +154,7 @@
 @cindex SVN
 @cindex Subversion
 @item
-Subversion (SVN) is a free version control system designed to be
+Subversion (svn) is a free version control system designed to be
 similar to CVS but without its problems (e.g., it supports atomic
 commits of filesets, and versioning of directories, symbolic links,
 meta-data, renames, copies, and deletes).
@@ -189,10 +189,6 @@
 basic editing operations under Bazaar.
 @end itemize
 
-  Previous versions of VC supported a version control system known as
-Meta-CVS.  This support was dropped due to limited interest from users
-and developers.
-
 @node VCS Concepts
 @subsubsection Concepts of Version Control
 
@@ -264,7 +260,7 @@
   SCCS always uses locking.  RCS is lock-based by default but can be
 told to operate in a merging style.  CVS and Subversion are
 merge-based by default but can be told to operate in a locking mode.
-Distributed version control systems, such as GNU Arch, git, and
+Distributed version control systems, such as GNU Arch, Git, and
 Mercurial, are exclusively merging-based.
 
   VC mode supports both locking and merging version control.  The
@@ -302,7 +298,7 @@
 point for reliability and efficiency.
 
   GNU Arch pioneered the concept of @dfn{decentralized} version
-control, later implemented in git, Mercurial, and Bazaar.  A project
+control, later implemented in Git, Mercurial, and Bazaar.  A project
 may have several different repositories, and these systems support a
 sort of super-merge between repositories that tries to reconcile their
 change histories.  In effect, there is one repository for each
@@ -409,37 +405,35 @@
 Directory buffer, and some files in it are marked, the VC fileset
 consists of the marked files (@pxref{VC Directory Mode}).
 
-  The principal VC command is an all-purpose command, @kbd{C-x v v}
-(@code{vc-next-action}), that performs either registration, locking,
-merging or a check-in (depending on the situation) on the current VC
-fileset.  You can use @kbd{C-x v v} in a file-visiting buffer or in a
-VC Directory buffer.
+  On Subversion and on decentralized version control systems,
+multi-file VC filesets are handled as a single group by the relevant
+version control commands.  For example, committing a multi-file VC
+fileset generates a single revision, consisting of all the changes to
+those files.  But on older version control systems which lack support
+for group operations, such as CVS, the files in a multi-file VC
+fileset are passed individually to version control commands (e.g.@: a
+commit generates one revision for each changed file).
 
 @table @kbd
 @itemx C-x v v
-Perform the appropriate next version control operation on the VC fileset.
+Perform the next appropriate version control operation on the current
+VC fileset.
 @end table
 
 @findex vc-next-action
 @kindex C-x v v
-  The precise action of @kbd{C-x v v} depends on the state of the VC
-fileset, and whether the version control system uses locking or
-merging.  This is described in detail in the subsequent sections.
-
-  VC filesets are the way that VC mode bridges the gap between
-file-based and changeset-based version control systems.  They are,
-essentially, a way to pass multiple file arguments as a group to
-version control commands.  For example, on Subversion, a checkin with
-a multi-file VC fileset becomes a joint commit, as though you had
-typed @command{svn commit} with those file arguments at the shell
-command line.  All files in a VC fileset must be under the same
-version control system; if they are not, Emacs signals an error when
-you attempt to execute a command on the fileset.
-
-  VC filesets are distinct from the ``named filesets'' used for
-viewing and visiting files in functional groups (@pxref{Filesets}).
-Unlike named filesets, VC filesets are not named and don't persist
-across sessions.
+  The principal VC command is an all-purpose command, @kbd{C-x v v}
+(@code{vc-next-action}), which performs the ``most appropriate''
+action on the current VC fileset: either registering it with a version
+control system, or committing it, or unlocking it, or merging changes
+into it.  The precise actions are described in detail in the following
+subsections.  You can use @kbd{C-x v v} either in a file-visiting
+buffer or in a VC Directory buffer.
+
+  Note that VC filesets are distinct from the ``named filesets'' used
+for viewing and visiting files in functional groups
+(@pxref{Filesets}).  Unlike named filesets, VC filesets are not named
+and don't persist across sessions.
 
 @menu
 * VC With A Merging VCS::  Without locking: default mode for CVS.
@@ -450,46 +444,41 @@
 @node VC With A Merging VCS
 @subsubsection Basic Version Control with Merging
 
-  When your version control system is merging-based (the default for
-CVS and all newer version control systems), work files are always
-writable; you need not do anything special to begin editing a file.
-The status indicator on the mode line is @samp{-} if the file is
-unmodified; it flips to @samp{:} as soon as you save any changes
-(@pxref{VC Mode Line}).
-
-  Here is what @kbd{C-x v v} does when using a merging-based system:
+  On a merging-based version control system (i.e.@: most modern ones;
address@hidden Merging}), @kbd{C-x v v} does the following:
 
 @itemize @bullet
 @item
-If the work file is in a directory that is not controlled by any
-version control system, prompt for a repository type.  Then, create a
-version control repository of that type and register the file with it.
-
address@hidden
-If the work file is in a directory that is controlled by a version
-control system but not registered with it, register the file.
-
address@hidden
-If the work file is the same as in the repository, do nothing.
-
address@hidden
-If you have not changed the work file, but some other user has checked
-in changes to the repository, merge those changes into the work file.
-
address@hidden
-If you have made modifications to the work file, attempt to commit
-the changes.  To do this, Emacs first reads the log entry for the new
-revision (@pxref{Log Buffer}).  If some other user has committed
-changes to the repository since you last checked it out, the checkin
-fails.  In that case, type @kbd{C-x v v} again to merge those changes
-into your own work file; this puts the work file into a ``conflicted''
-state.  Type @kbd{C-x v v} to clear the ``conflicted'' state; VC then
-regards the file as up-to-date and modified, and you can try to check
-it in again.
-
-To pick up any recent changes from the repository @emph{without}
-trying to commit your own changes, type @kbd{C-x v m @key{RET}}.
address@hidden
+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
+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}).
+
+If committing to a shared repository, the commit may fail if the
+repository that has been changed since your last update.  In that
+case, you must perform an update before trying again.  If using a
+decentralized version control system, use @kbd{C-x v +} or @kbd{C-x v
+m} (@pxref{Merging}).  If using a centralized version control system,
+type @kbd{C-x v v} again to merge in the repository changes.
+
address@hidden
+Finally, if you are using a centralized version control system, check
+if each work file in the VC fileset is up-to-date.  If any file has
+been changed in the repository, offer to update it.
 @end itemize
 
   These rules also apply when you use RCS in its ``non-locking'' mode,
@@ -506,32 +495,44 @@
 @node VC With A Locking VCS
 @subsubsection Basic Version Control with Locking
 
-  Under a locking-based version control system (such as SCCS, and RCS
-in its default mode), @kbd{C-x v v} does the following:
+  On a locking-based version control system (such as SCCS, and RCS in
+its default mode), @kbd{C-x v v} does the following:
 
 @itemize @bullet
 @item
-If the file is not locked, lock it and make it writable, so that you
-can change it.
-
address@hidden
-If the file is locked by you, and contains changes, commit the
-changes.  In order to do this, Emacs first reads the log entry for the
-new revision.  @xref{Log Buffer}.
-
address@hidden
-If the file is locked by you, but you have not changed it since you
-locked it, release the lock and makes the file read-only again.
-
address@hidden
-If the file is locked by some other user, ask whether you want to
-``steal the lock'' from that user.  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.
+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 file is registed and unlocked, lock it and make it writable,
+so that you can begin to edit it.
+
address@hidden
+If each file is locked by you and contains changes, 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}).
+
address@hidden
+If each file is locked by you, but you have not changed it, release
+the lock and make the file read-only again.
+
address@hidden
+If each file is locked by another user, ask whether you want to
+``steal the lock''.  If you say yes, the file becomes locked by you,
+and a warning message is sent to the user who had formerly locked the
+file.
 @end itemize
 
   These rules also apply when you use CVS in locking mode, except
-that CVS does not support stealing a lock.
+that CVS does not support stealing locks.
 
 @node Advanced C-x v v
 @subsubsection Advanced Control in @kbd{C-x v v}