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

[Ralf Wildenhues]

* 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.  How about "avoid" or "override"; you used the latter already in
the previous hunk, so I guess the former might be nicer, avoiding
repetition.

> +performs against suspicious directory/primary couples (in the unlikely

s/against/to flag/  or "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

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

* 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