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

[Stefano Lattarini]

On Sunday 02 January 2011, Ralf Wildenhues wrote:
> * Stefano Lattarini wrote on Sun, Jan 02, 2011 at 12:23:48PM CET:
> > On Sunday 02 January 2011, Ralf Wildenhues wrote:
> > > * Stefano Lattarini wrote on Sat, Dec 25, 2010 at 10:57:57AM CET:
> > > > Ok for maint?
> > > 
> > > OK with nits addressed.  Do we have testsuite coverage for this?
> > > 
> > Not yet, but once this patch is applied, I might easily extend the
> > new tests in pending patch " Warnings about primary/prefix mismatch
> > fixed and extended" to cover these new examples, too.
> 
> Cool.
> 
> > Attached is what I squashed in, and the amended patch.
> 
> Thanks.
> 
> > I'll wait for an ACK before pushing.
> 
> OK, except that I overlooked a couple of nits in my first review.  :-)
> Feel free to address them as you prefer and push.
> 
> > --- a/doc/automake.texi
> > +++ b/doc/automake.texi
> 
> > @@ -2008,6 +2009,33 @@ xmldir = $(datadir)/xml
> >  xml_DATA = file.xml
> >  @end example
> >  
> > +This feature can also be used to work around the sanity checks Automake
> 
> "work around" sounds like there is a bug, but in this case there is no
> bug.
>
Right.  Fixed.

> How about "avoid" or "override"; you used the latter already in
> the previous hunk, so I guess the former might be nicer, avoiding
> repetition.
>
I still went with "override", since IMHO it is clearer and more correct,
and I find this more important than being nicer.

> > +performs against suspicious directory/primary couples (in the unlikely
> 
> s/against/to flag/  or "to diagnose"
>
I decided for "to diagnose".

> > +case these checks are undesirable, and you really know what you're doing).
> > +For example, Automake would error out on this input:
> > +
> > address@hidden
> > +# Forbidden directory combinations, automake will error out on this.
> > +pkglib_PROGRAMS = foo
> > +doc_LIBRARIES = libquux.a
> > address@hidden example
> > +
> > address@hidden
> > +but it will succeeds with this:
> 
> succeed
>
Oops.  Fixed.

> > address@hidden
> > +# Work around forbidden directory combinations.  Do not use this
> > +# without a very good reason!
> > +my_execbindir = $(pkglibdir)
> > +my_doclibdir = $(docdir)
> > +my_execbin_PROGRAMS = foo
> > +my_doclib_LIBRARIES = libquux.a
> > address@hidden example
> > +
> > +The @samp{exec} substring of the @samp{my_execbindir} variable is not
> > +there by accident: it lets the files be installed at the right time
> > +(@pxref{The Two Parts of Install}).
> 
> I'd write  s/is not there by accident: it//
> mostly because it reads better (more like a book, less like a newspaper
> headline).
>
OK.

> * Stefano Lattarini wrote on Sun, Jan 02, 2011 at 01:08:13PM CET:
> > On Sunday 02 January 2011, Ralf Wildenhues wrote:
> > > > > +pkglib_PROGRAMS = foo
> > > > > +doc_LIBRARIES = libquux.a
> > > 
> > > Another nit: can we find less obviously bogus combinations that users
> > > might actually want to use?
> [...]
> > I haven't tought about this yet.  But IMHO it's no big deal if the usages
> > in our examples are "bogus"; in fact, the bogusness helps to show how
> > powerful and potentially dangerous the idiom is.
> > 
> > Anyway, you're obviously free to amend to example to make them less bogus,
> > if you still think this would be useful.  I have no strong opinion on the
> > matter.
> 
> Agreed, this can be improved later.
> 
> Thanks,
> Ralf
> 

Thanks for the reviews.  Here is what I pushed:

-*-*-

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

* 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 |   30 +++++++++++++++++++++++++++++-
 2 files changed, 37 insertions(+), 1 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 22bd532..9a1d180 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2011-01-02   Stefano Lattarini  <address@hidden>
+            Ralf Wildenhues  <address@hidden>
+
+       docs: how to work around checks on invalid primary/directory couples
+       * 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').
+
 2011-01-02  Ralf Wildenhues  <address@hidden>
 
        Sync auxiliary files from upstream.
diff --git a/doc/automake.texi b/doc/automake.texi
index 1f4b9ec..43ad581 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 (but see below how to override
+the check if you really need to).
 Automake will also diagnose obvious misspellings in directory names.
 
 @cindex Extending list of installation directories
@@ -2008,6 +2009,33 @@ xmldir = $(datadir)/xml
 xml_DATA = file.xml
 @end example
 
+This feature can also be used to override the sanity checks Automake
+performs to diagnose suspicious directory/primary couples (in the
+unlikely case these checks are undesirable, and you really know what
+you're doing).  For example, Automake would error out on this input:
+
address@hidden
+# Forbidden directory combinations, automake will error out on this.
+pkglib_PROGRAMS = foo
+doc_LIBRARIES = libquux.a
address@hidden example
+
address@hidden
+but it will succeed with this:
+
address@hidden
+# Work around forbidden directory combinations.  Do not use this
+# without a very good reason!
+my_execbindir = $(pkglibdir)
+my_doclibdir = $(docdir)
+my_execbin_PROGRAMS = foo
+my_doclib_LIBRARIES = libquux.a
address@hidden example
+
+The @samp{exec} substring of the @samp{my_execbindir} variable lets
+the files be installed at the right time (@pxref{The Two Parts of
+Install}).
+
 @cindex @samp{noinst_} primary prefix, definition
 @vindex noinst_
 
-- 
1.7.2.3