docs: improve description of ${PACKAGE}, ${VERSION}, and similar variables

In particular, suggesting that $PACKAGE and $VERSION should be aliases of
the $PACKAGE_TARNAME and $PACKAGE_VERSION definitions coming from AC_INIT,
and not be defined via an obsolete 2-argument invocation of AM_INIT_AUTOMAKE;
and why that is the best default, given all our historical baggage.

See discussion in http://debbugs.gnu.org/16623 for more information and
background.

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

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

2 files changed, 22 insertions, 10 deletions

diff --git a/THANKS b/THANKS
index 6be803e16..7f8485070 100644
--- a/THANKS
+++ b/THANKS
@@ -156,6 +156,7 @@ Ian Lance Taylor                ian@cygnus.com
 Ignacy Gawedzki                 i@lri.fr
 Илья Н. Голубев                 gin@mo.msk.ru
 Imacat                          imacat@mail.imacat.idv.tw
+Infirit                         infirit@gmail.com
 Inoue                           inoue@ainet.or.jp
 Jack Kelly                      jack@jackkelly.name
 James Amundson                  amundson@users.sourceforge.net
diff --git a/doc/automake.texi b/doc/automake.texi
index 736d61dc6..913dee4f0 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3914,12 +3914,15 @@ 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.
+in the @code{PACKAGE} and @code{VERSION} arguments (which otherwise
+defaults, respectively, to the @code{PACKAGE_TARNAME} and
+@code{PACKAGE_VERSION} defined via the @code{AC_INIT} invocation;
+@pxref{AC_INIT, , The @code{AC_INIT} macro, autoconf, The Autoconf Manual});
+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:
@@ -8381,9 +8384,13 @@ We recommend that you follow this same set of heuristics in your
 The @code{dist} rule in the generated @file{Makefile.in} can be used
 to generate a gzipped @code{tar} file and other flavors of archive for
 distribution.  The file is named based on the @code{PACKAGE} and
-@code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
-(@pxref{Macros}); more precisely the gzipped @code{tar} file is named
-@samp{@var{package}-@var{version}.tar.gz}.
+@code{VERSION} variables automatically defined by either the
+@code{AC_INIT} invocation or by a @emph{deprecated} two-arguments
+invocation of the @code{AM_INIT_AUTOMAKE} macro (see @ref{Public Macros}
+for how these variables get their values, from either defaults or explicit
+values -- it's slightly trickier than one would expect).
+More precisely the gzipped @code{tar} file is named
+@samp{$@{PACKAGE@}-$@{VERSION@}.tar.gz}.
 @vindex GZIP_ENV
 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
 is run.  The default setting is @option{--best}.
@@ -10151,7 +10158,11 @@ brittle.
 @opindex no-define
 This option is meaningful only when passed as an argument to
 @code{AM_INIT_AUTOMAKE}.  It will prevent the @code{PACKAGE} and
-@code{VERSION} variables from being @code{AC_DEFINE}d.
+@code{VERSION} variables from being @code{AC_DEFINE}d.  But notice
+that they will remain defined as shell variables in the generated
+@code{configure}, and as make variables in the generated
+@code{Makefile}; this is deliberate, and required for backward
+compatibility.
 
 @item @option{no-dependencies}
 @cindex Option, @option{no-dependencies}