docs: document planned precedence changes in aclocal search path

* doc/automake.texi (Macro Search Path): Explicitly state that the
lookup order for extra directories of `.m4' files will be changed
in the next major release.
* NEWS: Likewise.

diff --git a/ChangeLog b/ChangeLog
index 27895448417f2bdf4722d3a746f95443ae063f9a..05baf760b16aa49c04128666f0a87a93352d65a4 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2011-09-20  Stefano Lattarini  <stefano.lattarini@gmail.com>
+
+       docs: document planned precedence changes in aclocal search path
+       * doc/automake.texi (Macro Search Path): Explicitly state that the
+       lookup order for extra directories of `.m4' files will be changed
+       in the next major release.
+       * NEWS: Likewise.
+
 2011-09-19  Paolo Bonzini  <bonzini@gnu.org>
            Stefano Lattarini  <stefano.lattarini@gmail.com>
 

diff --git a/NEWS b/NEWS
index f9fa9594de1ca9373867ddb4f71a19127551a1a2..7ab3f07cefc748908144eae3aea9cb023d49c04e 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,10 @@ New in 1.11.0a:
   - The `--acdir' option of aclocal is deprecated, and will probably be
     removed in the next major Automake release (1.12).
 
+  - The exact order in which the directories in the aclocal macro
+    search path are looked up is probably going to be changed in the
+    next Automake release (1.12).
+
 * Changes to aclocal:
 
   - The `--acdir' option is deprecated.  Now you should use th new options

diff --git a/doc/automake.texi b/doc/automake.texi
index 44778c3f14a87d80221e7ebf8bbf33ff02b98dde..18d29bec90842f9d8e15c0c562b3ce3d60b1fbb9 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3455,6 +3455,16 @@ Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
 using a global copy of Automake and want @command{aclocal} to look for
 macros somewhere under your home directory.
 
+@subsubheading Planned future incompatibilities
+
+The order in which the directories in the macro search path are currently
+looked up is confusing and/or suboptimal in various aspects, and is
+probably going to be changed in the future Automake release.  In
+particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
+might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
+directories in @file{@var{acdir}/dirlist} might end up taking precedence
+over @file{@var{acdir}}.  @emph{This is a possible future incompatibility!}
+
 @node Extending aclocal
 @subsection Writing your own aclocal macros