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

[Ralf Wildenhues]

Hello Stefano,

* 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.  Generally, `e.g.' hampers read flow a bit, so it's good to
not overuse it.

> +version control files.  We recommend against using this feature.
>  
>  @vindex SUBDIRS
>  @vindex DIST_SUBDIRS
> @@ -8308,7 +8308,7 @@ recursively included by specifying a directory in 
> EXTRA_DIST:
>  EXTRA_DIST = doc
>  
>  dist-hook:
> -        rm -rf `find $(distdir)/doc -name CVS`
> +        rm -rf `find $(distdir)/doc -type d -name .svn`
>  @end example
>  
>  @vindex distdir
> @@ -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)

> +control repository, bypassing any timestamp inconsistency (implied by
> +e.g. @samp{cvs update} or @samp{git clone}).

See above.

>  If the required tool is installed, @command{missing} will run it and
>  won't attempt to continue after failures.  This is correct during
> @@ -10591,9 +10592,9 @@ swayed by Fran@,{c}ois's arguments, and got rid of
>  @code{AM_MAINTAINER_MODE} in all of his packages.
>  
>  Still many people continue to use @code{AM_MAINTAINER_MODE}, because
> -it helps them working on projects where all files are kept under CVS,
> -and because @command{missing} isn't enough if you have the wrong
> -version of the tools.
> +it helps them working on projects where all files are kept under version
> +control, and because @command{missing} isn't enough if you have the
> +wrong version of the tools.
>  
>  
>  @node Wildcards
> @@ -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', 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.

More generally, I'm not quite sure why we would want to remove all
traces of CVS from the sources though.  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?  Or, more specifically, if we are to write one of
`cvs add' or `svn add', we might just as well use the former, no?

>  @file{Makefile.am} accordingly quickly becomes a reflex.
>  
>  Conversely, if your application doesn't compile
>  because you forgot to add a file in @file{Makefile.am}, it will help
> -you remember to @samp{cvs add} it.
> +you remember to @samp{git add} it.

See above.

>  
>  @item
>  Using wildcards makes it easy to distribute files by mistake.  For