Snapshot primitives globally renamed to refer to tags, documentation updated.

5 files changed, 82 insertions, 80 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index e66e7f2c5bc..1d5328a606b 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,10 @@
+2008-05-15  Eric S. Raymond  <esr@snark.thyrsus.com>
+
+        * vc2-xtra.texi, emacs.texi, files.texi: Snapshots node renamed to
+        Revision Tags and rewritten. Section now uses modern terminology
+        (tags rather than snapshots) and describes post-SCCS systems more 
+        accurately.
+
 2008-05-10  Eli Zaretskii  <eliz@gnu.org>
 
         * msdog.texi (Windows Files): Update documentation of
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 28b72eb5c13..b9d2a0993c6 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -119,7 +119,7 @@ and to avoid conflicts.
 Completion
 Backup Files
 Auto-Saving: Protection Against Disasters
-Snapshots
+Tags
 Text Mode
 Outline Mode
 @TeX{} Mode
@@ -462,7 +462,7 @@ Version Control
 * Secondary VC Commands:: The commands used a little less frequently.
 * Branches::            Multiple lines of development.
 * Remote Repositories:: Efficient access to remote CVS servers.
-* Snapshots::           Sets of file versions treated as a unit.
+* Revision Tags::       Symbolic names for revisions
 * Miscellaneous VC::    Various other commands and features of VC.
 * Customizing VC::      Variables that change VC's behavior.
 
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 9d525393004..0d6808d9e45 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1238,7 +1238,7 @@ customizable variable @code{vc-handled-backends} to @code{nil}
 * Branches::            Multiple lines of development.
 @ifnottex
 * Remote Repositories:: Efficient access to remote CVS servers.
-* Snapshots::           Sets of file versions treated as a unit.
+* Revision Tags::       Symbolic names for revisions
 * Miscellaneous VC::    Various other commands and features of VC.
 * Customizing VC::      Variables that change VC's behavior.
 @end ifnottex
@@ -1300,8 +1300,8 @@ git, and Mercurial.
   SCCS was the first version-control system ever built, and was long ago
 superseded by later and more advanced ones; Emacs supports it only for
 backward compatibility and historical reasons.  VC compensates for
-certain features missing in SCCS (snapshots, for example) by
-implementing them itself, but some other VC features, such as multiple
+certain features missing in SCCS (tag names for releases, for example) by
+implementing them itself. Some other VC features, such as multiple
 branches, are not available with SCCS.  Since SCCS is non-free you
 should not use it; use its free replacement CSSC instead.  But you
 should use CSSC only if for some reason you cannot use a more 
@@ -1895,19 +1895,19 @@ buffer in another window.
 
   You can specify a checked-in revision by its ID; an empty input
 specifies the current contents of the work file (which may be different
-from all the checked-in revisions).  You can also specify a snapshot name
+from all the checked-in revisions).  You can also specify a tag or branch name
 @iftex
-(@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features})
+(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features})
 @end iftex
 @ifnottex
-(@pxref{Snapshots})
+(@pxref{Tags})
 @end ifnottex
 instead of one or both revision ID.
 
   Note that if your version-control system is file-oriented (SCCS,
 RCS, CVS) rather than fileset-oriented (Subversion, GNU Arch, git,
 Mercurial) specifying a revision of a multiple-file fileset by
-revision ID (as opposed to a snapshot name or RSCCS/RCS tag) is
+revision ID (as opposed to a symbolic tag name) is
 unlikely to return diffs that are connected in any meaningful way.
 
   If you invoke @kbd{C-u C-x v =} or @kbd{C-u C-x v =} from a buffer
diff --git a/doc/emacs/vc-xtra.texi b/doc/emacs/vc-xtra.texi
index d08f6b29bf3..f1977d2adb6 100644
--- a/doc/emacs/vc-xtra.texi
+++ b/doc/emacs/vc-xtra.texi
@@ -14,9 +14,9 @@ the Emacs Manual}).  This chapter describes more advanced VC usage.
 
 @menu
 * VC Directory Mode::       Listing files managed by version control.
-* VC Directory Commands::   Commands to use in a VC Dired buffer.
+* VC Directory Commands:: Commands to use in a VC Dired buffer.
 * Remote Repositories::     Efficient access to remote VCS servers.
-* Snapshots::               Sets of file versions treated as a unit.
+* Revision Tags::           Symbolic names for revisions
 * Miscellaneous VC::        Various other commands and features of VC.
 * Customizing VC::          Variables that change VC's behavior.
 @end menu
diff --git a/doc/emacs/vc2-xtra.texi b/doc/emacs/vc2-xtra.texi
index c4d6eac0c46..bbb7a9980bd 100644
--- a/doc/emacs/vc2-xtra.texi
+++ b/doc/emacs/vc2-xtra.texi
@@ -204,51 +204,57 @@ 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}}.
 
-@node Snapshots
-@subsection Snapshots
-@cindex snapshots and version control
+@node Revision Tags
+@subsection Revision Tags
+@cindex tags 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.
+  In a VCS with per-file revision numbers (such as SCCS, RCS, or CVS)
+@dfn{tag} is a named set of file versions (one for each registered
+file) that you can treat as a unit.  In a VCS with per-repository
+version numbers (Subversion and most later ones) a tag is simply
+a symbolic name for a revsion.
+
+   One important kind of tag is a @dfn{release}, a (theoretically)
+stable version of the system that is ready for distribution to users.
 
 @menu
-* Making Snapshots::            The snapshot facilities.
-* Snapshot Caveats::            Things to be careful of when using snapshots.
+* Making Revision Tags::                The tag facilities.
+* Revision Tag Caveats::                Things to be careful of when using tags.
 @end menu
 
-@node Making Snapshots
-@subsubsection Making and Using Snapshots
+@node Making Revision Tags
+@subsubsection Making and Using Revision Tags
 
-  There are two basic commands for snapshots; one makes a
-snapshot with a given name, the other retrieves a named snapshot.
+  There are two basic commands for tags; one makes a
+tag with a given name, the other retrieves a named tag.
 
 @table @code
 @kindex C-x v s
-@findex vc-create-snapshot
+@findex vc-create-tag
 @item 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}).
+Define the working revision of every registered file in or under the
+current directory as a tag named @var{name}
+(@code{vc-create-tag}).
 
 @kindex C-x v r
-@findex vc-retrieve-snapshot
+@findex vc-retrieve-tag
 @item 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}).
+For all registered files at or below the current directory level,
+retrieve the tagged revision @var{name}. This command will 
+switch to a branch if @var{name} is a branch name and your VCS
+distinguishes branches from tags. 
+(@code{vc-retrieve-tag}).
 
 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.
 @end 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.
+Tags are inexpensive, so you need not hesitate to create them whenever
+they are useful.  Branches vary in cost depending on your VCS; in
+older ones they may be expensive.
 
-  You can give a snapshot name as an argument to @kbd{C-x v =} or
+  You can give a tag or branch name as an argument to @kbd{C-x v =} or
 @kbd{C-x v ~}
 @iftex
 (@pxref{Old Revisions,,,emacs, the Emacs Manual}).
@@ -256,50 +262,40 @@ you need not hesitate to create snapshots whenever they are useful.
 @ifnottex
 (@pxref{Old Revisions}).
 @end ifnottex
-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.
-
-@node Snapshot Caveats
-@subsubsection Snapshot Caveats
-
-@cindex 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).
-
-@c 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
+Thus, you can use it to compare a tagged version against the current files,
+or two tagged versions against each other.
+
+@node Revision Tag Caveats
+@subsubsection Revision Tag Caveats
+
+  For SCCS, VC implements tags itself; these tags are visible only
+through VC.  Most later systems (including CVS, Subversion, bzr, git,
+and hg) have a native tag facility, and VC uses it where
+available; those tags will be visible even when you bypass VC.
+
+  There is no support for VC tags using GNU Arch yet.
+
+  Under older VCSes (SCCS, RCS, CVS, early versions of Subversion),
+renaming and deletion could create some difficulties with tags.  This is
+not a VC-specific problem, but a general design issue in version
+control systems that was not solved effectively until the earliest
+third-generation systems.
+
+  In a file-oriented VCS, when you rename a registered file you need
+to rename its master along with it; the command @code{vc-rename-file}
+will do this automatically.  If you are using SCCS, you must also
+update the records of the tag, to mention the file by its new name
+(@code{vc-rename-file} does this, too).  An old tag 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 tags by hand.
+
+  Using @code{vc-rename-file} makes the tag 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
+retrieve an old tag, 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.
 
@@ -473,10 +469,9 @@ to avoid putting such trivia into @file{ChangeLog}.
   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
+accordingly.  It also updates any tags (@pxref{Revision Tags}) that
 mention the file, so that they use the new name; despite this, the
-snapshot thus modified may not completely work (@pxref{Snapshot
-Caveats}).
+tag thus modified may not completely work (@pxref{Revision Tag 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}