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

* 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.

1 files changed, 26 insertions, 32 deletions

diff --git a/doc/automake.texi b/doc/automake.texi
index c9e149df6..8dcbc1895 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])
-@itemx 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}):
+@code{AM_INIT_AUTOMAKE(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
-@command{autoupdate} should adjust your @file{configure.ac}
-automatically (@pxref{autoupdate Invocation, , Using
-@command{autoupdate} 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
+@file{configure.ac}, autoconf, The Autoconf Manual}).
+@emph{Do 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
-@code{AM_PROG_MKDIR_P} has been rewritten as a thin wrapper around
-@code{AC_PROG_MKDIR_P} to define @code{mkdir_p} to the same value as
-@code{MKDIR_P} 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
-@code{$(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