[PATCH] docs: how to work around checks on invalid primary/directory couples

[Stefano Lattarini]

Ok for maint?

Regards,
   Stefano

-*-*-*-

docs: how to work around checks on invalid primary/directory couple

* doc/automake.texi (Uniform): Document the blessed idiom which can
be used to work around Automake checks on invalid primary/directory
couples (such as `lib_PROGRAMS' or `doc_LIBRARIES').

Suggested by Ralf Wildenhues.

See also:
 <http://lists.gnu.org/archive/html/bug-automake/2010-12/msg00041.html>
or equivalently:
 <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=7657#14>

From 746dbba6da061eb5b6a3caf786ea76176bce4f76 Mon Sep 17 00:00:00 2001
From: Stefano Lattarini <address@hidden>
Date: Fri, 24 Dec 2010 22:00:40 +0100
Subject: [PATCH] docs: how to work around checks on invalid primary/directory 
couple

* doc/automake.texi (Uniform): Document the blessed idiom which can
be used to work around Automake checks on invalid primary/directory
couples (such as `lib_PROGRAMS' or `doc_LIBRARIES').

Suggested by Ralf Wildenhues.
---
 ChangeLog         |    8 ++++++++
 doc/automake.texi |   28 +++++++++++++++++++++++++++-
 2 files changed, 35 insertions(+), 1 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 224c3e0..fcb42d9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2010-12-25   Stefano Lattarini  <address@hidden>
+
+       docs: how to work around checks on invalid primary/directory couple
+       * doc/automake.texi (Uniform): Document the blessed idiom which can
+       be used to work around Automake checks on invalid primary/directory
+       couples (such as `lib_PROGRAMS' or `doc_LIBRARIES').
+       Suggested by Ralf Wildenhues.
+
 2010-12-23  Ralf Wildenhues  <address@hidden>
            Stefano Lattarini  <address@hidden>
 
diff --git a/doc/automake.texi b/doc/automake.texi
index ab5f861..7dfcf18 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -1986,7 +1986,8 @@ variable names; thus one writes @samp{bin_PROGRAMS} and 
not
 @samp{bindir_PROGRAMS}.
 
 Not every sort of object can be installed in every directory.  Automake
-will flag those attempts it finds in error.
+will flag those attempts it finds in error (see below for a trick to
+silence these checks, in case you really need to).
 Automake will also diagnose obvious misspellings in directory names.
 
 @cindex Extending list of installation directories
@@ -2008,6 +2009,31 @@ xmldir = $(datadir)/xml
 xml_DATA = file.xml
 @end example
 
+This feature can also be used to work around the sanity checks Automake
+performs against suspicious directory/primary couples (in the unlikely
+case these checks are undesirable, and you really know what you're doing
+in silencing them).  For example, Automake would error out on this input:
+
address@hidden
+pkglib_PROGRAMS = foo
+doc_LIBRARIES = libquux.a
address@hidden example
+
+but it will succeeds with this:
+
address@hidden
+my_execbindir = $(pkglibdir)
+my_doclibdir = $(docdir)
+my_execbin_PROGRAMS = foo
+my_doclib_LIBRARIES = libquux.a
address@hidden example
+
+Notice that the ``exec'' substring of @samp{my_execbindir} is not
+there by accident: it ensures that @samp{foo} is be installed by
address@hidden install-exec}.  An apparently simpler name, like
address@hidden, would cause @samp{foo} to be installed at
address@hidden install-data}, which is incorrect.
+
 @cindex @samp{noinst_} primary prefix, definition
 @vindex noinst_
 
-- 
1.7.2.3