[FYI] docs, news: document planned removal of obsolete macros and features

[Stefano Lattarini]

* NEWS (Future backward-incompatibilities): Document planned removal
of several superseded and/or obsoleted macros, of the $(mkdir_p)
variable and @mkdir_p@ substitution, and of the support for the
two- or three-arguments invocation forms of AM_INIT_AUTOMAKE.
* doc/automake.texi: Likewise.
---
 NEWS              |   27 ++++++++++++++++++++++++
 doc/automake.texi |   58 +++++++++++++++++++++++-----------------------------
 2 files changed, 53 insertions(+), 32 deletions(-)

diff --git a/NEWS b/NEWS
index b5b184e..e086423 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,32 @@
 * WARNING: Future backward-incompatibilities!
 
+  - The following long-obsolete m4 macros will be removed in the
+    next major Automake version (1.13):
+
+      AM_PROG_CC_STDC:    superseded by AC_PROG_CC since October 2002
+      fp_PROG_CC_STDC:    broken alias for AM_PROG_CC_STDC
+      fp_WITH_DMALLOC:    old alias for AM_WITH_DMALLOC
+      AM_CONFIG_HEADER:   superseded by AC_CONFIG_HEADERS since July 2002
+      ud_PATH_LISPDIR:    old alias for AM_PATH_LISPDIR
+      jm_MAINTAINER_MODE: old alias for AM_MAINTAINER_MODE
+      ud_GNU_GETTEXT:     old alias for AM_GNU_GETTEXT
+      gm_PROG_LIBTOOL:    old alias for AC_PROG_LIBTOOL
+      fp_C_PROTOTYPES:    old alias for AM_C_PROTOTYPES (which was part
+                          of the now-removed automatic de-ANSI-fication
+                          support of Automake)
+
+  - All the "old alias" macros in 'm4/obsolete.m4' will be removed in
+    the next major Automake version (1.13).
+
+  - Support for the two- and three-arguments invocation forms of the
+    AM_INIT_AUTOMAKE macro will be deprecated in the next minor version
+    of Automake (1.12.1) and removed in the next major version (1.13).
+
+  - The long-obsolete (since 1.10) automake-provided $(mkdir_p) make
+    variable, @mkdir_p@ substitution and AM_PROG_MKDIR m4 macro will
+    all be deprecated in the next minor version of Automake (1.12.1)
+    and removed in the next major version (1.13).
+
   - The '--acdir' option of aclocal is deprecated, and will probably
     be removed in the next major Automake release (1.13).  You should
     use the options '--automake-acdir' and '--system-acdir' instead
diff --git a/doc/automake.texi b/doc/automake.texi
index c9e149d..8dcbc18 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -190,7 +190,7 @@ Auto-generating aclocal.m4
 Autoconf macros supplied with Automake
 
 * Public Macros::               Macros that you can use.
-* Obsolete Macros::             Macros that you should stop using.
+* Obsolete Macros::             Macros that will soon be removed.
 * Private Macros::              Macros that you should not use.
 
 Directories
@@ -3918,7 +3918,7 @@ Automake ships with several Autoconf macros that you can 
use from your
 
 @menu
 * Public Macros::               Macros that you can use.
-* Obsolete Macros::             Macros that you should stop using.
+* Obsolete Macros::             Macros that will soon be removed.
 * Private Macros::              Macros that you should not use.
 @end menu
 
@@ -3930,23 +3930,23 @@ Automake ships with several Autoconf macros that you 
can use from your
 @table @code
 
 @item AM_INIT_AUTOMAKE([OPTIONS])
address@hidden AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
 @acindex AM_INIT_AUTOMAKE
 Runs many macros required for proper operation of the generated Makefiles.
 
 @vindex AUTOMAKE_OPTIONS
-This macro has two forms, the first of which is preferred.
-In this form, @code{AM_INIT_AUTOMAKE} is called with a
-single argument: a space-separated list of Automake options that should
+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
-The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
-arguments: the package and the version number.  This form is
-obsolete because the @var{package} and @var{version} can be obtained
-from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
-form).
+This macro can also be called in @emph{another, deprecated form} (support
+for which will be @emph{removed in the next major Automake release}):
address@hidden(PACKAGE, VERSION, [NO-DEFINE])}.  In this form,
+there are two required arguments: the package and the version number.
+This form is obsolete because the @var{package} and @var{version} can
+be obtained from Autoconf's @code{AC_INIT} macro (which itself has an
+old and a new form).
 
 If your @file{configure.ac} has:
 
@@ -3956,7 +3956,7 @@ AM_INIT_AUTOMAKE([mumble], [1.5])
 @end example
 
 @noindent
-you can modernize it as follows:
+you should modernize it as follows:
 
 @example
 AC_INIT([mumble], [1.5])
@@ -3981,11 +3981,10 @@ explicitly).
 @opindex no-define
 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
 @code{VERSION}.  This can be avoided by passing the @option{no-define}
-option, as in:
+option:
 @example
 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
 @end example
-or by passing a third non-empty argument to the obsolete form.
 
 @item AM_PATH_LISPDIR
 @acindex AM_PATH_LISPDIR
@@ -4079,11 +4078,13 @@ define @code{WITH_DMALLOC} and add @option{-ldmalloc} 
to @code{LIBS}.
 @cindex autoupdate
 
 Although using some of the following macros was required in past
-releases, you should not use any of them in new code.  Running
address@hidden should adjust your @file{configure.ac}
-automatically (@pxref{autoupdate Invocation, , Using
address@hidden to Modernize @file{configure.ac}, autoconf, The
-Autoconf Manual}).
+releases, you should not use any of them in new code.  @emph{All
+these macros will be removed in the next major Automake version};
+if you are still using them, running @command{autoupdate} should
+adjust your @file{configure.ac} automatically (@pxref{autoupdate
+Invocation, , Using @command{autoupdate} to Modernize
address@hidden, autoconf, The Autoconf Manual}).
address@hidden it NOW!}
 
 @table @code
 
@@ -4113,19 +4114,12 @@ variable @code{mkdir_p} to one of @code{mkdir -p}, 
@code{install-sh
 Nowadays Autoconf provides a similar functionality with
 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
 Program Checks, autoconf, The Autoconf Manual}), however this defines
-the output variable @code{MKDIR_P} instead.  Therefore
address@hidden has been rewritten as a thin wrapper around
address@hidden to define @code{mkdir_p} to the same value as
address@hidden for backward compatibility.
-
-If you are using Automake, there is normally no reason to call this
-macro, because @code{AM_INIT_AUTOMAKE} already does so.  However, make
-sure that the custom rules in your @file{Makefile}s use
address@hidden(MKDIR_P)} and not @code{$(mkdir_p)}.  Even if both variables
-still work, the latter should be considered obsolete.
-
-If you are not using Automake, please call @code{AC_PROG_MKDIR_P}
-instead of @code{AM_PROG_MKDIR_P}.
+the output variable @code{MKDIR_P} instead.  In case you are still
+using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
+or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
+you are advised to switch ASAP to the more modern Autoconf-provided
+interface instead; both the macro and the variable @emph{will be
+removed} in the next major Automake release.
 
 @item AM_SYS_POSIX_TERMIOS
 @acindex AM_SYS_POSIX_TERMIOS
-- 
1.7.9