docs: don't suggest installing `.m4' files in hard-coded location

This change fixes automake bug#7988.

* doc/automake.texi (aclocal Options): State that the use of
the `--print-ac-dir' option to determine the directory where
third-party packages can install their `.m4' files is discouraged
now.
(Extending aclocal): Suggest telling the user about ACLOCAL_PATH.
* THANKS: Update.

Report by Peter Johansson.

diff --git a/ChangeLog b/ChangeLog
index 47aee92b102ea42a39ef6e0407cbd7ddb9358482..12cdb6e12f7719c35a70ffa2412bb85c63c5dc91 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2011-09-28  Stefano Lattarini  <stefano.lattarini@gmail.com>
+
+       docs: don't suggest installing `.m4' files in hard-coded location
+       This change fixes automake bug#7988.
+       * doc/automake.texi (aclocal Options): State that the use of
+       the `--print-ac-dir' option to determine the directory where
+       third-party packages can install their `.m4' files is discouraged
+       now.
+       (Extending aclocal): Suggest telling the user about ACLOCAL_PATH.
+       * THANKS: Update.
+       Report by Peter Johansson.
+
 2011-09-22  Stefano Lattarini  <stefano.lattarini@gmail.com>
 
        tests: fix tests on aclocal search path precedences

diff --git a/THANKS b/THANKS
index f83e1fce41cb5d710147890face980899cd370e9..3c106c7b317495420828af2244d7c1187dc54e31 100644 (file)
--- a/THANKS
+++ b/THANKS
@@ -275,6 +275,7 @@ Per Oyvind Hvidsten poeh@enter.vg
 Peter Breitenlohner    peb@mppmu.mpg.de
 Peter Eisentraut       peter_e@gmx.net
 Peter Gavin            pgavin@debaser.kicks-ass.org
+Peter Johansson                trojkan@gmail.com
 Peter Mattis           petm@scam.XCF.Berkeley.EDU
 Peter Muir             iyhi@yahoo.com
 Peter O'Gorman         peter@pogma.com

diff --git a/doc/automake.texi b/doc/automake.texi
index a8233dd1a0d37d54ae1bb46f92a2cda10a64a24a..c463fe7898140a4222bbd342ffda7d254b9b14dd 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3254,8 +3254,12 @@ Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
 @opindex --print-ac-dir
 Prints the name of the directory that @command{aclocal} will search to
 find third-party @file{.m4} files.  When this option is given, normal
-processing is suppressed.  This option can be used by a package to
-determine where to install a macro file.
+processing is suppressed.  This option was used @emph{in the past} by
+third-party packages to determine where to install @file{.m4} macro
+files, but @emph{this usage is today discouraged}, since it causes
+@samp{$(prefix)} not to be thoroughly honoured (which violates the
+GNU Coding Standards), and a similar semantics can be better obtained
+with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
 
 @item --verbose
 @opindex --verbose
@@ -3430,6 +3434,7 @@ Similarly, @file{dirlist} can be handy if you have installed a local
 copy of Automake in your account and want @command{aclocal} to look for
 macros installed at other places on the system.
 
+@anchor{ACLOCAL_PATH}
 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
 @cindex @env{ACLOCAL_PATH}
 
@@ -3491,8 +3496,12 @@ aclocal_DATA = mymacro.m4 myothermacro.m4
 
 @noindent
 Please do use @file{$(datadir)/aclocal}, and not something based on
-the result of @samp{aclocal --print-ac-dir}.  @xref{Hard-Coded Install
-Paths}, for arguments.
+the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
+Paths}, for arguments).  It might also be helpful to suggest to
+the user to add the @file{$(datadir)/aclocal} directory to his
+@env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
+@command{aclocal} will find the @file{.m4} files installed by your
+package automatically.
 
 A file of macros should be a series of properly quoted
 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The