aclocal: deprecate ACLOCAL_AMFLAGS, trace AC_CONFIG_MACRO_DIR instead

aclocal: deprecate ACLOCAL_AMFLAGS, trace AC_CONFIG_MACRO_DIR instead

Maintaining ACLOCAL_AMFLAGS in the Makefile.am to pass extra flags
to aclocal is (and have always been) quite of an hack.  For example,
autoreconf is forced to grep Makefile.am to honour those flags.  But
this is a bad obsolescent behaviour; in fact, the autotools have moved
consistently in the past years from custom grepping of Makefile.am and
configure.ac to tracing of m4 macro calls, which is more consistent,
more reliable and more flexible.

And when autoreconf is not used, the developer is forced to add *by hand*
the flags specified by ACLOCAL_AMFLAGS to the aclocal calls not triggered
by make rebuild rules; here lie again more duplication and more chances
for errors.

Moreover, ACLOCAL_AMFLAGS has only two typical use cases:

  - to instruct aclocal to look for extra macro definition in a local
    directory (as with "ACLOCAL_AMFLAGS = -I m4"); and

  - to further instruct aclocal to copy in that local directory the
    required third-party .m4 files found in the system-wide directory
    (as with "ACLOCAL_AMFLAGS = -I m4 --install").

The first use case can be better covered if aclocal can instead trace and
honours call to the AC_CONFIG_MACRO_DIR autoconf macro; and the second
use case shouldn't be considered really legitimate, as it is quite (and
subtly) brittle (see automake bug#9037).

Thus we now make aclocal trace AC_CONFIG_MACRO_DIR macro, and act
accordingly.  For backward compatibility, we continue to support the
ACLOCAL_AMFLAGS special variable (although removing any mention of it
from the documentation).  Future Automake releases will likely start
to warn about the use of that variable, and eventually remove support
for it altogether.

From a suggestion by Eric Blake.

This is a much simplified (and IMHO saner) version of the patch series
discussed in the threads:
<http://lists.gnu.org/archive/html/automake-patches/2010-10/msg00045.html>
<http://lists.gnu.org/archive/html/automake-patches/2010-12/msg00156.html>

* aclocal.in ($ac_config_macro_dir): New global variable.
(trace_used_macros): Also trace the macro 'AC_CONFIG_MACRO_DIR',
and set the '$ac_config_macro_dir' variable accordingly.
(parse_arguments): Code for diagnosis of '--install' used without
any user-specified include directory moved  ...
(while (1)): .. into the main loop.  Which now also updates the
list of user-specified include directories to include the directory
given as argument to the call (if any) of 'AC_CONFIG_MACRO_DIR'.
* lib/am/configure.am: Update comments.
* NEWS: Updated.
* doc/automake.texi: Likewise.  Also, stop advising the use of the
'--install' in ACLOCAL_AMFLAGS (see automake bug#9037 for a rationale),
and remove any reference to ACLOCAL_AMFLAGS (which is now considered
obsolescent).
* t/aclocal-path-install.sh: Adjust grepping check in the aclocal
error messages.
* t/subpkg.sh: Updated: add 'AC_CONFIG_MACRO_DIR' call to configure.ac,
remove setting of 'ACLOCAL_AMFLAGS' in Makefile.am and use of aclocal
command line arguments.
* t/subpkg2.sh: Likewise.
* t/subdir8.sh: Likewise.
* t/remake10c.sh: Likewise.
* t/remake8a.sh: Likewise.
* t/remake8b.sh: Likewise.
* t/aclocal4.sh: Likewise.
* t/aclocal6.sh: Likewise.
* t/acloca14.sh: Likewise.
* t/acloca22.sh: Likewise.
* t/aclocal5.sh: Likewise, and do not not invade the Automake
namespace (this avoids spurious failures).
* t/acloca14b.sh: New test, identical to the previous version of
'acloca14.test'; it is kept to verify backwards compatibility with
the use of ACLOCAL_AMFLAGS.
* t/acloca22b.sh: Likewise (but for 'acloca22.test').
* t/aclocal-amflags.sh: New test, check for backwards
compatibility that ACLOCAL_AMFLAGS still works.
* t/remake-macrodir.sh: New test, checking that aclocal's honoring of
AC_CONFIG_MACRO_DIR interacts nicely with automatic rebuild rules.
* t/list-of-tests.mk: Add the new tests.

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