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
> > -...@emph{with 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
