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 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.

> Thanks,
> Ralf
> 
> > 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
> 
> I would s/Automake/automake/ here, as you're speaking about the program
> in particular.  Oh well, not a biggie.
>
Fixed anyway.

> > couples (such as `lib_PROGRAMS' or `doc_LIBRARIES').
> 
> > --- 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).
> 
> Let's avoid "trick", as there is no magic involved here.  How about
> this?
> 
>   ... (but see below how to override the check if you need to).
>
OK, done (but I left the "if you really need to" in place, to highlight
the fact that the overridde should be done only in exceptional situations).

> >  Automake will also diagnose obvious misspellings in directory names.
> 
> 
> > @@ -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:
> 
> s/in silencing them//
>
Fixed.

> I would replace the last sentence
>
I would leave the sentence in place, *and* in addition add the comments
you suggested in the code (I agree these would be very useful, sorry for
not having thought about them myself).

> with a comment in the code (users
> always like to copy and paste even broken code, so they should be
> warned as closely as possible), here and below:
> 
> > address@hidden
>   +# Forbidden directory combinations, automake will error out on this.
> > +pkglib_PROGRAMS = foo
> > +doc_LIBRARIES = libquux.a
> > address@hidden example
> > +
> > +but it will succeeds with this:
> 
> Precede this line with
>   @noindent
> 
> on a line of its own.
>
Done.

> > 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
> 
> > +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.
> 
> This paragraph is repetitive of another part of the manual which already
> explains the 'exec' feature.  How about:
> 
>   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}).
>
Hmm... what about:

    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've gone for this ATM, but I will fix it if you still feel it's too
verbose.
 
> >  @cindex @samp{noinst_} primary prefix, definition
> >  @vindex noinst_
> 

Attached is what I squashed in, and the amended patch.
I'll wait for an ACK before pushing.

Regards,
   Stefano

diff --git a/ChangeLog b/ChangeLog
index 46e5ea8..9a1d180 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,10 +1,10 @@
-2010-12-25   Stefano Lattarini  <address@hidden>
+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
+       be used to work around automake checks on invalid primary/directory
        couples (such as `lib_PROGRAMS' or `doc_LIBRARIES').
-       Suggested by Ralf Wildenhues.
 
 2011-01-02  Ralf Wildenhues  <address@hidden>
 
diff --git a/doc/automake.texi b/doc/automake.texi
index 174e4f4..51cb7e5 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -1986,8 +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 (see below for a trick to
-silence these checks, in case you really need to).
+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
@@ -2011,28 +2011,30 @@ xml_DATA = file.xml
 
 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:
+case these checks are undesirable, and you really know what you're doing).
+For example, Automake would error out on this input:
 
 @example
+# Forbidden directory combinations, automake will error out on this.
 pkglib_PROGRAMS = foo
 doc_LIBRARIES = libquux.a
 @end example
 
address@hidden
 but it will succeeds with this:
 
 @example
+# 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
 @end 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.
+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}).
 
 @cindex @samp{noinst_} primary prefix, definition
 @vindex noinst_

From 16975c6dfebdf978770cbb069dde16dc72558969 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 
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..51cb7e5 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 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).
+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:
+
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}).
+
 @cindex @samp{noinst_} primary prefix, definition
 @vindex noinst_
 
-- 
1.7.2.3