doc: Mention effect of 'autoreconf -fi' on INSTALL

Several projects have a bootstrap script that invokes
'autoreconf -fi' as part of a fresh version control checkout,
in order to avoid storing common files in version control,
while also allowing contributors to rerun bootstrap to pick
up the benefits of any upgrade of one of the autotools.

However, the documentation did not make it obvious that such
a setup will overwrite any customizations to files like
INSTALL, if those files are stored in version control, when
automake still considers that file to be standard based on
AM_INIT_AUTOMAKE settings.  In such a case, a mere
'autoreconf -i' is good for the bootstrap script, while a
separate 'autoreconf -f' is good for picking up on an upgrade
of any autotools.

* bin/autoreconf.in (help): Mention standard files.
* doc/autoconf.texi (autoreconf Invocation): Add more text, including
warning that mixing --force and --install may undo customizations,
and that the set of files impacted is controlled by automake.
Reported by Emil Laine <laine.emil@gmail.com>
Signed-off-by: Eric Blake <eblake@redhat.com>

diff --git a/bin/autoreconf.in b/bin/autoreconf.in
index da5b3ea81e1f567da7d239146640ffeefa6324a2..b401d01f36239da6feae6f2008d4fab0a975b13a 100644 (file)
--- a/bin/autoreconf.in
+++ b/bin/autoreconf.in
@@ -69,8 +69,8 @@ Operation modes:
   -V, --version            print version number, then exit
   -v, --verbose            verbosely report processing
   -d, --debug              don't remove temporary files
-  -f, --force              consider all files obsolete
-  -i, --install            copy missing auxiliary files
+  -f, --force              consider all generated and standard files obsolete
+  -i, --install            copy missing standard auxiliary files
       --no-recursive       don't rebuild sub-packages
   -s, --symlink            with -i, install symbolic links instead of copies
   -m, --make               when applicable, re-run ./configure && make

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 01a8313629990e0c07f7e9c2c1777dd18b0de073..9cc0e98d1badc4819180715746d0d3ae61b61384 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -1739,14 +1739,21 @@ Don't remove the temporary files.
 
 @item --force
 @itemx -f
-Remake even @file{configure} scripts and configuration headers that are
-newer than their input files (@file{configure.ac} and, if present,
-@file{aclocal.m4}).
+Consider all generated and standard auxiliary files to be obsolete.
+This remakes even @file{configure} scripts and configuration headers
+that are newer than their input files (@file{configure.ac} and, if
+present, @file{aclocal.m4}).
+
+If deemed appropriate, this option triggers calls to @samp{automake
+--force-missing}.  Passing both @option{--force} and @option{--install}
+to @command{autoreconf} will in turn undo any customizations to standard
+files.  Note that the macro @code{AM_INIT_AUTOMAKE} has some options
+which change the set of files considered to be standard.
 
 @item --install
 @itemx -i
-Install the missing auxiliary files in the package.  By default, files
-are copied; this can be changed with @option{--symlink}.
+Install any missing standard auxiliary files in the package.  By
+default, files are copied; this can be changed with @option{--symlink}.
 
 If deemed appropriate, this option triggers calls to
 @samp{automake --add-missing},