Re: [SIMPLE PATCH] {maint} Manual: be more agnostic w.r.t. version control system used.

[Stefano Lattarini]

On Wednesday 22 September 2010, Ralf Wildenhues wrote:
> Hello Stefano,
Hi Ralf, thanks for the quick review.
 
> * Stefano Lattarini wrote on Wed, Sep 22, 2010 at 10:34:46PM CEST:
> > * doc/automake.texi (Basics of Distribution): Also refer to
> > `.svn' directories as a type of probably-unwanted files that are
> > copied regardless when adding directories to EXTRA_DIST.
> > (The dist Hook): Show a dist-hook example which removes
> > Subversion `.svn' private directories from distdir, rather than
> > CVS private directories.
> > (missing and AM_MAINTAINER_MODE): Try to be more agnostic w.r.t.
> > the version control system used.
> > (Why doesn't Automake support wildcards): Use git rather than CVS
> > in the examples.
> 
> I have some nits below.
> 
> Thanks,
> Ralf
> 
> > --- a/doc/automake.texi
> > +++ b/doc/automake.texi
> > @@ -8246,8 +8246,8 @@ subdirectories in @code{EXTRA_DIST}.
> > 
> >  You can also mention a directory in @code{EXTRA_DIST}; in this
> >  case the entire directory will be recursively copied into the
> >  distribution. Please note that this will also copy
> >  @emph{everything} in the directory,
> > 
> > -including CVS/RCS version control files.  We recommend against
> > using -this feature.
> > +including e.g. Subversion's @file{.svn} private directories or
> > CVS/RCS
> 
> You need either a comma or a @: after `e.g.' to avoid an
> end-of-sentence space there.
I'd now do it the same way the rest of the manual does (way which I
hadn't noticed until now):
 "including, e.g., Subversion's @file{.svn} private directories or CVS/RCS"

> Generally, `e.g.' hampers read flow a bit, so it's good to not overuse it.
Should I just remove it then?  I don't have strong preferences about it
anyway here.
 
> > @@ -10534,9 +10534,10 @@ Besides the warning, when a tool is
> > missing, @command{missing} will
> > 
> >  attempt to fix timestamps in a way that allows the build to
> >  continue. For instance, @command{missing} will touch
> >  @file{configure} if @command{autoconf} is not installed.  When
> >  all distributed files are
> > 
> > -kept under CVS, this feature of @command{missing} allows a user
> > address@hidden no maintainer tools} to build a package off CVS, bypassing
> > -any timestamp inconsistency implied by @samp{cvs update}.
> > +kept under version control, this feature of @command{missing} allows a
> > +user @emph{with no maintainer tools} to build a package off the version
> 
> s/the/a/  (I think)
or better again, s/the/its/?

> 
> > +control repository, bypassing any timestamp inconsistency (implied by
> > +e.g. @samp{cvs update} or @samp{git clone}).
> 
> See above.
I'd go with `e.g.@:' here.  OK?
 
> > @@ -10608,13 +10609,13 @@ a file.
> > 
> >  There are several objections to this:
> >  @itemize
> >  @item
> > 
> > -When using CVS (or similar) developers need to remember they have to
> > -run @samp{cvs add} or @samp{cvs rm} anyway.  Updating
> > +When using git (or similar) developers need to remember they have to
> > +run @samp{git add} or @samp{git rm} anyway.  Updating
> 
> Ah, `git add' does not have the same semantics as `cvs add',
Yes, but you have (maybe not theoretically, but pratically) to use `git
add' anyway when introducing new files in the repository.  The fact that
you can use it to add the cahnges done to an already-controlled file to
the git index is irrelevant here, right?
> and the change very slightly distorts the meaning here: cvs add is
> needed only when introducing files to version control, not ever
> for files that are already under version control.  svn add is
> similar, so this example would work better with that.
So should I switch to `svn' in the example?  I'd prefer to stick to git,
as I see it as "the way to the future".

> More generally, I'm not quite sure why we would want to remove all
> traces of CVS from the sources though.
Well, there's still a whole "CVS and generated files" section in the
documenation ;-)

> Sure, it's not new, and sure it has its warts, but I'm guessing that
> its basic usage semantics are still widely known, no?
Even to "newer" developers?  All I can say is that I've never used
CVS once in my life (well, I have just once, to checkout a repository
lacking proper up-to-date tarballs - but I did that by blindly
copy-and-pasting from on-line instructions, happily forgetting them
right away).

> Or, more specifically, if we are to write one of `cvs add' or `svn add',
> we might just as well use the former, no?
I'm confident that, as the time goes by, more and more people will be
familiar with `git add' and `svn add', and less and less with `cvs add'.

Regards,
   Stefano