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

[Ralf Wildenhues]

* 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?

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.

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

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

I would replace the last sentence 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.

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

>  @cindex @samp{noinst_} primary prefix, definition
>  @vindex noinst_