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:
>
> > +...@example
> +# Forbidden directory combinations, automake will error out on this.
> > +pkglib_PROGRAMS = foo
> > +doc_LIBRARIES = libquux.a
> > +...@end example
> > +
> > +but it will succeeds with this:
>
> Precede this line with
> @noindent
>
> on a line of its own.
>
Done.
> > +...@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
> > +...@samp{make install-exec}. An apparently simpler name, like
> > +...@samp{my_bindir}, would cause @samp{foo} to be installed at
> > +...@samp{make 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 <stefano.lattar...@gmail.com>
+2011-01-02 Stefano Lattarini <stefano.lattar...@gmail.com>
+ Ralf Wildenhues <ralf.wildenh...@gmx.de>
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 <ralf.wildenh...@gmx.de>
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
+...@noindent
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
-...@samp{make install-exec}. An apparently simpler name, like
-...@samp{my_bindir}, would cause @samp{foo} to be installed at
-...@samp{make 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 <stefano.lattar...@gmail.com>
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 <stefano.lattar...@gmail.com>
+ Ralf Wildenhues <ralf.wildenh...@gmx.de>
+
+ 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 <ralf.wildenh...@gmx.de>
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:
+
+...@example
+# Forbidden directory combinations, automake will error out on this.
+pkglib_PROGRAMS = foo
+doc_LIBRARIES = libquux.a
+...@end example
+
+...@noindent
+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
+
+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
