Re: patch for documentation about version control

[Karl Fogel]

Alex Ott <address@hidden> writes:
> this patch add some docs about version control systems supported by vc.
> 
> Index: man/files.texi
> ===================================================================
> RCS file: /cvsroot/emacs/emacs/man/files.texi,v
> retrieving revision 1.91
> diff -u -w -b -B -r1.91 files.texi
> --- man/files.texi    9 Oct 2004 18:41:18 -0000       1.91
> +++ man/files.texi    9 Nov 2004 06:57:21 -0000
> @@ -1119,11 +1119,12 @@
>  description of what was changed in that version.
>  
>    The Emacs version control interface is called VC.  Its commands work
> -with three version control systems---RCS, CVS, and SCCS.  The GNU
> -project recommends RCS and CVS, which are free software and available
> -from the Free Software Foundation.  We also have free software to
> -replace SCCS, known as CSSC; if you are using SCCS and don't want to
> -make the incompatible change to RCS or CVS, you can switch to CSSC.
> +with different version control systems---RCS, CVS, SCCS, Meta-CVS, GNU
> +Arch and Subversion.  The GNU project recommends RCS, CVS, and GNU Arch
> +which are free software and available from the Free Software Foundation.
> +We also have free software to replace SCCS, known as CSSC; if you are
> +using SCCS and don't want to make the incompatible change to RCS or CVS,
> +you can switch to CSSC.

Minor nit: from this sentence

   "The GNU project recommends RCS, CVS, and GNU Arch which are
    free software...",

some readers could mistakenly infer that the other systems are *not*
free software.  And because of that lead-in, the next sentence about a
free replacement for SCCS only strengthens the misimpression.

Since Subversion and Meta-CVS are both free software, could this
paragraph be tweaked?  Here's one possible rewording:

     The Emacs version control interface is called VC.  Its commands work
   with different version control systems---RCS, CVS, SCCS, Meta-CVS, GNU
   Arch and Subversion.  The GNU project recommends and distributes
   RCS, CVS, and GNU Arch.  We also have free software to replace
   SCCS, known as CSSC; if you are using SCCS and don't want to make
   the incompatible change to RCS or CVS, you can switch to CSSC.

Also, I was looking at the rest of the patch, and saw a few grammar
problems:

> @@ -1190,6 +1192,33 @@
>  features, such as multiple branches, are not available with SCCS.  You
>  should use SCCS only if for some reason you cannot use RCS.
>  
> address@hidden MCVS
> address@hidden Meta-CVS
> +
> +Meta-CVS is another attempt to solve problems, arising in CVS.  It
> +supports directory structure versioning, improved branching and merging,
> +and use of symbolic links and meta-data in repositories.

s/solve problems, arising in/solve the problems of/

> address@hidden GNU Arch
> address@hidden Arch
> +  GNU Arch is new version control system that designed for distributed
> +work.  It differs in many ways from old well-known systems, such as CVS
> +and RCS.  It supports different transports for interoperating between
> +users, offline operations and have good branching and merging features.
> +It also supports atomic commits, and history of file renaming and
> +moving.  VC supports not all operations, provided by GNU Arch, so you
> +can call their from command line, or use specialized module.

This had a few problems, so here's a rewrite:

  +  GNU Arch is new version control system that is designed for distributed
  +work.  It differs in many ways from old well-known systems, such as CVS
  +and RCS.  It supports different transports for interoperating between
  +users, offline operations, and it has good branching and merging features.
  +It also supports atomic commits, and history of file renaming and
  +moving.  VC does not support all operations provided by GNU Arch, so you
  +can invoke it from the command line, or use a specialized module.

> address@hidden SVN
> address@hidden Subversion
> +  Subversion is version control system, that was designed for eliminate
> +problems, that arrive with CVS usage, such as nonatomic commits, and
> +losing history of file with renaming or moving file.  It also could be
> +used via http or other standard protocols.  SVN has almost same concepts
> +as CVS, but solve some problems.  Switching from CVS to SVN is very
> +easy---just use @command{svn} command instead @command{cvs}.

A few problems here too, both in grammar and content, so here's a
rewrite:

  +  Subversion is a version control system designed to be similar to CVS
  +but without CVS's problems.  Subversion supports atomic commits,
  +and versions directories, symbolic links, meta-data, renames, copies,
  +and deletes.  It can be used via http or via its own protocol.

By the way, is there any reason not to refer to the respective home
pages of these systems?  They are:

   Meta-CVS:    http://users.footprints.net/~kaz/mcvs.html
   GNU Arch:    http://www.gnu.org/software/gnu-arch/
   Subversion:  http://subversion.tigris.org/

Hope this helps, and thanks for writing the new content!

-Karl