docs: re-introduce mention of two-args AM_INIT_AUTOMAKE invocation

Albeit obsolescent and raising warnings in the 'obsolete' category,
that usage is still supported, and will need to be until Autoconf
improves its handling of configure-time-generated package version
numbers.  So it's better to explicitly document it again, stating
that it is obsoleted but still working (and why), rather then leaving
it as Yet Another Undocumented Feature (that will mysteriously and
suddenly break some random day in the future).

It's worth giving some background about how we ended up in the
situation that this patch fixes.

We had originally removed support for the long-deprecated two-args
AM_INIT_AUTOMAKE invocation (see commit v1.12-67-ge186355).  Before
that removal could land in a released Automake version, Bob Friesenhahn
made a quite compelling point that the two-args AM_INIT_AUTOMAKE
invocation could still be useful for modern, maintained packages like
GraphicsMagick, at least until Autoconf is fixed to offer better support
for "dynamic" package versions (see commit v1.12.2-245-g2abe183 for more
in-depth rationales and references).  However, in that commit we didn't
revert the removal of the *documentation* for this two-arguments
AM_INIT_AUTOMAKE invocation (and no rationale for not doing so was given
in the commit message).  Time to remedy that.

Indirectly suggested by Diego Elio Pattenò:
<http://blog.flameeyes.eu/2013/01/autotools-mythbuster-automake-pains>

* doc/automake.texi: Adjust.
* NEWS: Update.
* THANKS: Likewise.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>

1 files changed, 41 insertions, 15 deletions

diff --git a/doc/automake.texi b/doc/automake.texi
index b4dad5c08..64bde411b 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3896,19 +3896,25 @@ Automake ships with several Autoconf macros that you can use from your
 Runs many macros required for proper operation of the generated Makefiles.
 
 @vindex AUTOMAKE_OPTIONS
-@code{AM_INIT_AUTOMAKE} is called with a single argument: a space-separated
-list of Automake options that should be applied to every @file{Makefile.am}
-in the tree.  The effect is as if each option were listed in
-@code{AUTOMAKE_OPTIONS} (@pxref{Options}).
-
-@c FIXME: Remove this "modernization advice" in Automake 1.14 (and adjust
-@c FIXME: the error message in m4/init.m4:AM_INIT_AUTOMAKE accordingly).
+Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
+space-separated list of Automake options that should be applied to
+every @file{Makefile.am} in the tree.  The effect is as if
+each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
 
 @acindex AC_INIT
-This macro could once (before Automake 1.13) also be called in the
-@emph{now obsolete and completely unsupported} form
+This macro can also be called in another, @emph{deprecated} form:
 @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}.  In this form,
-there were two required arguments: the package and the version number.
+there are two required arguments: the package and the version number.
+This usage is mostly obsolete because the @var{package} and @var{version}
+can be obtained from Autoconf's @code{AC_INIT} macro.  However,
+differently from what happens for @code{AC_INIT} invocations, this
+@code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions
+in the @code{PACKAGE} and @code{VERSION} arguments, and this can be
+still be useful in some selected situations.  Our hope is that future
+Autoconf versions will improve their support for package versions
+defined dynamically at configure runtime; when (and if) this happens,
+support for the two-args @code{AM_INIT_AUTOMAKE} invocation will likely
+be removed from Automake.
 
 @anchor{Modernize AM_INIT_AUTOMAKE invocation}
 If your @file{configure.ac} has:
@@ -3919,8 +3925,7 @@ AM_INIT_AUTOMAKE([mumble], [1.5])
 @end example
 
 @noindent
-you must modernize it as follows in order to make it work with Automake
-1.13 or later:
+you should modernize it as follows:
 
 @example
 AC_INIT([mumble], [1.5])
@@ -9924,8 +9929,27 @@ be read as a side effect of running @command{configure}, like @file{version.sh}
 in the example above.
 
 Speaking of @file{version.sh} scripts, we recommend against them
-today.  We recommend that @file{version.sh} be replaced by an M4 file
-that is included by @file{configure.ac}:
+today.  They are mainly used when the version of a package is updated
+automatically by a script (e.g., in daily builds).  Here is what some
+old-style @file{configure.ac}s may look like:
+
+@example
+AC_INIT
+. $srcdir/version.sh
+AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
+@dots{}
+@end example
+
+@noindent
+Here, @file{version.sh} is a shell fragment that sets
+@code{VERSION_NUMBER}.  The problem with this example is that
+@command{automake} cannot track dependencies (listing @file{version.sh}
+in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
+to the user), and that it uses the obsolete form of @code{AC_INIT} and
+@code{AM_INIT_AUTOMAKE}.  Upgrading to the new syntax is not
+straightforward, because shell variables are not allowed in
+@code{AC_INIT}'s arguments.  We recommend that @file{version.sh} be
+replaced by an M4 file that is included by @file{configure.ac}:
 
 @example
 m4_include([version.m4])
@@ -9939,7 +9963,9 @@ Here @file{version.m4} could contain something like
 @samp{m4_define([VERSION_NUMBER], [1.2])}.  The advantage of this
 second form is that @command{automake} will take care of the
 dependencies when defining the rebuild rule, and will also distribute
-the file automatically.
+the file automatically.  An inconvenience is that @command{autoconf}
+will now be rerun each time the version number is bumped, when only
+@file{configure} had to be rerun in the previous setup.
 
 
 @node Options