[FYI] {maint} docs: re-introduce mention of two-args AM_INIT_AUTOMAKE invocation

[Stefano Lattarini]

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 <address@hidden>
---
 NEWS              | 10 ++++++++++
 THANKS            |  1 +
 doc/automake.texi | 56 ++++++++++++++++++++++++++++++++++++++++---------------
 3 files changed, 52 insertions(+), 15 deletions(-)

diff --git a/NEWS b/NEWS
index c9ad88a..277141d 100644
--- a/NEWS
+++ b/NEWS
@@ -60,6 +60,16 @@ New in 1.13.2:
     category.  You are advised to simply use the '.texi' extension
     instead.
 
+* Documentation fixes:
+
+  - The long-deprecated but still supported two-arguments invocation form
+    of AM_INIT_AUTOMAKE is documented once again.  This seems the sanest
+    thing to do, given that support for such an usage might need to remain
+    in place for a unspecified amount of time in order to cater for people
+    who want to define the version number for their package dynamically at
+    configure runtime (unfortunately, Autoconf does not yet support this
+    scenario, so we cannot delegate the work to it).
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 New in 1.13.1:
diff --git a/THANKS b/THANKS
index 5fa307d..58745e7 100644
--- a/THANKS
+++ b/THANKS
@@ -91,6 +91,7 @@ Dennis Schridde                 address@hidden
 Derek R. Price                  address@hidden
 Diab Jerius                     address@hidden
 Didier Cassirame                address@hidden
+Diego Elio Pettenò              address@hidden
 Dieter Baron                    address@hidden
 Dieter Jurzitza                 address@hidden
 Дилян Палаузов                  address@hidden
diff --git a/doc/automake.texi b/doc/automake.texi
index b4dad5c..64bde41 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
address@hidden 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
address@hidden (@pxref{Options}).
-
address@hidden FIXME: Remove this "modernization advice" in Automake 1.14 (and 
adjust
address@hidden 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
address@hidden 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
address@hidden 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:
+
address@hidden
+AC_INIT
+. $srcdir/version.sh
+AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
address@hidden
address@hidden example
+
address@hidden
+Here, @file{version.sh} is a shell fragment that sets
address@hidden  The problem with this example is that
address@hidden 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
address@hidden  Upgrading to the new syntax is not
+straightforward, because shell variables are not allowed in
address@hidden'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
address@hidden had to be rerun in the previous setup.
 
 
 @node Options
-- 
1.8.1.rc3.27.g3b73c7d