bug#7988: the manual suggests installing macro files to hard-coded location

[Stefano Lattarini]

On Sunday 20 March 2011, Peter Johansson wrote:
> Hello Stefano,
> 
> On 3/19/11 8:36 AM, Stefano Lattarini wrote:
> >
> > Another viable approach would be to install the third-party macro file
> > in `$(third-party-prefix)/share/aclocal', and then extend the file
> > `$(aclocal-prefix)/share/aclocal/dirlist' to list that directory too; but
> > this would mean *modify* a possibly pre-existing file (and in a hard-coded
> > location too), and I'm not sure this is a wise move (but maybe might be
> > worth citing in the documentation anyway... Opinions?)
> >
> IMVHO that doesn't sound like an improvement. Say that I, e.g., install 
> an old version of GSL with --prefix=/usr/local/gsl-1.6. That doesn't 
> mean I want aclocal to look for m4 files in 
> `/usr/local/gsl-1.6/share/aclocal'. And what happens with all the times 
> I install my own package within distcheck, would that prefix 
> (`pwd`/_inst) also be added in `dirlist'?
> 
> > Finally, note that this problem should be ameliorated once the pending
> > patches introducing support for the ACLOCAL_PATH environment variable
> > are merged:
> >   <http://lists.gnu.org/archive/html/automake-patches/2010-11/msg00089.html>
> > At that point, a thid-party package providing macro files can install them
> > into `$(third-party-prefix)/share/aclocal', and then tell the user to
> > extend the system-wide definition of ACLOCAL_PATH accordingly (somewhat
> > similarly to what libtool install rules does with `LD_LIBRARY_PATH').
> 
> Sounds good.
> 
> Thanks,
> Peter
> 
OK, now we have ACLOCAL_PATH support implemented into maint, so it's time to
fix this bug.  I'll push the attached patch to maint in a couple of days if
there is no objection.

Regards,
  Stefano


From b100d18da312f4b22be283b9a877b221667b2245 Mon Sep 17 00:00:00 2001
Message-Id: <address@hidden>
From: Stefano Lattarini <address@hidden>
Date: Sun, 25 Sep 2011 14:29:19 +0200
Subject: [PATCH] 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.
---
 ChangeLog         |   12 ++++++++++++
 THANKS            |    1 +
 doc/automake.texi |   17 +++++++++++++----
 3 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 47aee92..12cdb6e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2011-09-28  Stefano Lattarini  <address@hidden>
+
+       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  <address@hidden>
 
        tests: fix tests on aclocal search path precedences
diff --git a/THANKS b/THANKS
index f83e1fc..3c106c7 100644
--- a/THANKS
+++ b/THANKS
@@ -275,6 +275,7 @@ Per Oyvind Hvidsten address@hidden
 Peter Breitenlohner    address@hidden
 Peter Eisentraut       address@hidden
 Peter Gavin            address@hidden
+Peter Johansson                address@hidden
 Peter Mattis           address@hidden
 Peter Muir             address@hidden
 Peter O'Gorman         address@hidden
diff --git a/doc/automake.texi b/doc/automake.texi
index a8233dd..c463fe7 100644
--- 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
address@hidden(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.
 
address@hidden
 @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
address@hidden variable (@pxref{ACLOCAL_PATH}) so that
address@hidden 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
-- 
1.7.2.3