Add --pull, --gen options to build-aux/bootstrap

This supports a single bootstrap script with --pull and --gen
options, as an alternative to separate autogen.sh and autopull.sh
and bootstrap-funclib.sh auxiliary files.
* top/bootstrap: With --version, also output library version.
Support update of package that has only the bootstrap script,
and not the other three files.

2 files changed, 26 insertions, 10 deletions

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index ba1598fd9a..808e1e8279 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -987,7 +987,8 @@ time, three ways of handling version control have evolved.
 
 In the cases (A) and (B), a ``git submodule'' is used to reference
 the precise commit of the gnulib repository, so that each developer
-running @file{autopull.sh} will get the same version of all gnulib-provided
+running @samp{./bootstrap --pull} or @file{autopull.sh}
+will get the same version of all gnulib-provided
 files.
 
 The alternative is to always follow the newest Gnulib automatically.
@@ -1031,10 +1032,12 @@ $ git syncsub
 @end smallexample
 
 @item (B)
-In this approach, the @code{autopull.sh} program (see @ref{Developer tools})
-is used to aid a developer in using this setup.  You copy this program and
-its companion files into your package and place them under version control.
-It can be customized using @file{bootstrap.conf} which you also put under
+In this approach, the @code{build-aux/bootstrap} or @code{autopull.sh}
+program (see @ref{Developer tools}) is used to aid a developer in
+using this setup.  You copy this program (and if it's
+@code{autopull.sh}, its companion files) into your package and place
+the copy or copies under version control.  The program can be
+customized using @file{bootstrap.conf} which you also put under
 version control.
 
 @item (C)
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index eeb9b81f8a..816bf2a3f2 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -7055,7 +7055,7 @@ otherwise have a hard time building your package.
 @node Utilities for Makefiles
 @section Utilities for Makefiles
 
-These are a couple of programs that are often useful in Makefiles.  Some
+These programs can be used in Makefiles.  Some
 of them are also described in
 @ifinfo
 @ref{Auxiliary Programs,,,automake}.
@@ -7105,7 +7105,7 @@ targets depend upon.
 @node Developer tools
 @section Programs for developing in Git checkouts
 
-These are a couple of programs that help when developing in a Git
+These programs can help when developing in a Git
 checkout.  The maintainer of the package copies these programs into the
 version control of the package, so that co-developers can use these
 tools right away.
@@ -7134,9 +7134,12 @@ omitted from version control.  Usually this means that it invokes
 @code{gnulib-tool} and @code{automake}, that generate files from other
 files.
 
-@code{bootstrap} is a wrapper around both: It invokes @code{autopull.sh}
-and then immediately @code{autogen.sh}.@*
-Note: Because this program mixes version control management and
+@code{bootstrap} is a wrapper around both:
+@code{./bootstrap --pull} is equivalent to @code{./autopull.sh},
+@code{./bootstrap --gen} is equivalent to @code{./autogen.sh}.
+Plain @code{./bootstrap} is equivalent to @code{./autopull.sh}
+immediately followed by @code{./autogen.sh}; however, because plain
+@code{./bootstrap} mixes version control management and
 generation of files in non-obvious ways, it has a number of usability
 issues for the advanced developer.
 
@@ -7146,6 +7149,16 @@ programs.  It is not meant to be used directly.
 All three programs make use of a configuration file, called
 @code{bootstrap.conf}.
 
+@item build-aux/bootstrap
+This acts like @code{top/bootstrap}, except it does not
+need the companion files @code{autogen.sh},
+@code{autopull.sh}, and @code{bootstrap-funclib.sh}
+so it avoids some clutter in your project's top level directory.
+With this approach, you update via @code{./bootstrap --pull} and
+@code{./bootstrap --gen} instead of via @code{./autopull.sh} and
+@code{./autogen.sh}.  Otherwise this approach acts similarly, and
+uses the same @code{bootstrap.conf} file.
+
 @item build-aux/bootstrap.conf
 This is the template configuration file.  After copying it into the
 top-level directory of your package, you need to customize it.