doc: document most of the files outside of modules

[Bruno Haible]

I'm adding two new documentation chapters.


2019-08-24  Bruno Haible  <address@hidden>

        doc: Document most of the files outside of modules.
        * doc/gnulib.texi (Build Infrastructure Files,
        Release Management Files): New chapters.

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 051c077..8812957 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -73,6 +73,8 @@ Documentation License''.
 * Particular Modules::              Documentation of individual modules.
 * Regular expressions::             The regex module.
 * Build Infrastructure Modules::    Modules that extend the GNU Build System.
+* Build Infrastructure Files::      Non-modules files for the build system.
+* Release Management Files::        Non-modules files for preparing releases.
 * GNU Free Documentation License::  Copying and sharing this manual.
 * Index::
 @end menu
@@ -6755,6 +6757,237 @@ for use with GNU Automake (in particular).
 @include manywarnings.texi
 
 
+@node Build Infrastructure Files
+@chapter Build Infrastructure Files
+
+Gnulib contains also a small number of files that are not part of
+modules.  They are meant to be imported into packages by means of
+@samp{gnulib-tool --copy-file}, not @samp{gnulib-tool --import}.  For
+example, the commands to import the files @code{config.guess} and
+@code{config.sub} are
+@smallexample
+for file in config.guess config.sub; do
+  $GNULIB_TOOL --copy-file build-aux/$file \
+    && chmod a+x build-aux/$file \
+    || exit $?
+done
+@end smallexample
+
+Packages that don't use Gnulib can get hold of these files through
+direct download from Gnulib's git repository.  The commands to do this
+look as follows:
+@smallexample
+for file in config.guess config.sub; do
+  echo "$0: getting $file..."
+  wget -q --timeout=5 -O build-aux/$file.tmp 
"https://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob_plain;f=build-aux/$@{file@};hb=HEAD";
 \
+    && mv build-aux/$file.tmp build-aux/$file \
+    && chmod a+x build-aux/$file
+  retval=$?
+  rm -f build-aux/$file.tmp
+  test $retval -eq 0 || exit $retval
+done
+@end smallexample
+
+@menu
+* Recognizing platforms::
+* Utilities for Makefiles::
+* Developer tools::
+* For building documentation::
+* For building libraries::
+* For running tests::
+@end menu
+
+@node Recognizing platforms
+@section Recognizing platforms
+
+@table @code
+@item build-aux/config.guess
+@itemx build-aux/config.sub
+These files are helper scripts, invoked by the @samp{configure} script.
+@code{config.guess} recognizes the platform on which the script is
+running, and produces a triplet of the form
+@code{@var{cpu-type}-@var{vendor}-@var{operating_system}}.
+@code{config.sub} receives a possibly abbreviated triplet and produces a
+canonical triplet for a platform.  For more information, see
+@ifinfo
+@ref{Configuration,,,standards}.
+@end ifinfo
+@ifnotinfo
+@url{https://www.gnu.org/prep/standards/html_node/Configuration.html}.
+@end ifnotinfo
+@end table
+
+It is important that you always include the newest versions of these two
+files in your tarball, because people who work on emerging platforms
+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
+of them are also described in
+@ifinfo
+@ref{Auxiliary Programs,,,automake}.
+@end ifinfo
+@ifnotinfo
+@url{https://www.gnu.org/software/automake/manual/html_node/Auxiliary-Programs.html}.
+@end ifnotinfo
+
+@table @code
+@item build-aux/ar-lib
+@itemx build-aux/compile
+These two scripts are necessary for supporting portability to native
+Windows with the MSVC compiler.  @code{compile} is a wrapper script that
+invokes the compiler and provides a command-line interface compatible
+with Unix compilers.  Similarly, @code{ar-lib} is a wrapper script that
+provides a command-line interface compatible with Unix @code{ar}.
+@item build-aux/depcomp
+This is a helper script, used by Makefile rules generated by GNU
+Automake.  It generates Makefile dependencies while compiling a file.
+@item build-aux/install-sh
+This is a helper script, used by Makefile rules generated by GNU
+Automake.  It installs files during the @code{make install} phase.  In
+the Makefile, don't use this file directly; always use
+@code{$(INSTALL_PROGRAM)} or @code{$(INSTALL_DATA)} instead.
+@item build-aux/mdate-sh
+This script determines the modification time of a file and pretty-prints
+it.  The typical use is to add a ``Last modified'' line to the
+documentation.
+@item build-aux/mkinstalldirs
+This is a helper script, used by Makefile rules generated by GNU
+Automake.  It creates directories during the @code{make install} phase.
+It is roughly equivalent to @samp{mkdir -p} (except that the latter is
+not portable).  In the Makefile, don't use this file directly; always
+use @code{$(MKDIR_P)} instead.
+@item build-aux/mktempd
+This script creates a temporary directory.  It is roughly equivalent to
+@samp{mktemp -d} (except that the latter is not portable).
+@item build-aux/move-if-change
+This script moves a freshly generated file to a destination file, with a
+special optimization for the case that both files are identical.  In
+this case the freshly generated file is deleted, and the time stamp of
+the destination file is @emph{not} changed.  This is useful when
+updating a file that rarely actually changes and which many Makefile
+targets depend upon.
+@end table
+
+@node Developer tools
+@section Programs for developing in Git checkouts
+
+These are a couple of programs that 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.
+
+@table @code
+@item top/gitsub.sh
+This program manages the subdirectories of a Git checkout that come from
+other packages, including Gnulib.
+@item build-aux/bootstrap
+This program manages the Git submodules, including Gnulib, and is also a
+wrapper around @code{gnulib-tool} and @code{automake}, that generates
+files from other files.@*
+Note: Because this program mixes version control management and
+generation of files in non-obvious ways, it has a number of usability
+issues for the advanced developer.
+@item build-aux/bootstrap.conf
+This is the template configuration file.  After copying it into your
+package, you need to customize it.
+@item build-aux/po/Makefile.in.in
+@itemx build-aux/po/remove-potcdate.sin
+These are auxiliary files used by @code{bootstrap}.  You don't have to
+copy them yourself; @code{bootstrap} will do that.
+@end table
+
+@node For building documentation
+@section Utilities for building documentation
+
+These are auxiliary files for building documentation.
+
+@table @code
+@item build-aux/texinfo.tex
+This file is needed for the conversion of Texinfo-format documentation
+to PDF, PostScript, or DVI formats.  It implements the GNU Texinfo
+commands on top of plain TeX.
+@item build-aux/x-to-1.in
+This file, once processed, gives a program @code{x-to-1}, that produces
+a manual page for a program, by combining a skeleton with the program's
+@code{--help} output.
+@end table
+
+@node For building libraries
+@section Utilities for building libraries
+
+@table @code
+@item build-aux/declared.sh
+This program extracts the declared global symbols of a C header file.
+It is useful when you want to control the set of symbols exported by a
+library.  See @ref{Exported Symbols of Shared Libraries}.
+@end table
+
+@node For running tests
+@section Utilities for running test suites
+
+@table @code
+@item build-aux/run-test
+This file is a test driver that supports running a test under
+@code{valgrind}.
+@item build-aux/test-driver.diff
+This is a patch, against Automake's test driver, that support running a
+test suite on Android.
+@end table
+
+
+@node Release Management Files
+@chapter Release Management Files
+
+Gnulib also contain a few scripts that are useful for the release
+management of a package.  They can be used directly off the Gnulib
+checkout; they don't need to copied first.
+
+@menu
+* For building shared libraries::
+* For uploading releases::
+@end menu
+
+@node For building shared libraries
+@section Tools for releasing packages with shared libraries
+
+@table @code
+@item build-aux/libtool-next-version
+This program is a wizard that helps a maintainer update the libtool
+version of a shared library, without making mistakes in this process.
+For background documentation, see
+@ifinfo
+@ref{Updating version info,,,libtool}.
+@end ifinfo
+@ifnotinfo
+@url{https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html}.
+@end ifnotinfo
+@end table
+
+@node For uploading releases
+@section Tools for uploading release tarballs
+
+@table @code
+@item build-aux/gnupload
+This program is a user-friendly way to upload a release tarball to one of
+the GNU servers (@code{ftp.gnu.org} or @code{alpha.gnu.org}).  It
+implements the interface described in
+@ifinfo
+@ref{Automated FTP Uploads,,,maintain}.
+@end ifinfo
+@ifnotinfo
+@url{https://www.gnu.org/prep/maintain/html_node/Automated-FTP-Uploads.html}.
+@end ifnotinfo
+@item build-aux/ncftpput-ftp
+This is a helper program that mimics the @code{ncftpput} program used by
+@code{gnupload}.  If you want to use @code{gnupload} but don't have
+@code{ncftp} installed, copy this file into your $PATH, renaming it to
+@code{ncftpput}.
+@end table
+
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License