bug#7828: documentation about '-d' in AM_YFLAGS is suboptimal

[Ralf Wildenhues]

* Stefano Lattarini wrote on Wed, Jan 12, 2011 at 01:36:08PM CET:
> On Wednesday 12 January 2011, Юрий Пухальский wrote:
> > Package isn't enclosed because otherwise the message doesn't get through.
> > 
> > > Finally had time to make some tests, and now i've got it:)
> > >
> > > When i set AM_YFLAGS to -dt it doesn't distribute a header, probably
> > > because it's searching for -d to be alone.
> > > When i set AM_YFLAGS = -d -t, it works.
> > >
> ... I agree the documentation might be clearer about this.
> 
> Ralf, what about the attached patch (for 'yacc-work' and 'maint')?
> Tested with "make pdf ps dvi html MAKEINFOFLAGS=--no-split".  The
> output in all forms looked fine.

OK with nits addressed.

Thanks!
Ralf

> From cf43febea57a25173e665e2c610b1ccafdd26b01 Mon Sep 17 00:00:00 2001
> From: Stefano Lattarini <address@hidden>
> Date: Wed, 12 Jan 2011 13:23:59 +0100
> Subject: [PATCH] docs: clustered '-d' not recognized in YFLAGS
> MIME-Version: 1.0
> Content-Type: text/plain; charset=UTF-8
> Content-Transfer-Encoding: 8bit
> 
> This commit fixes automake bug#7828.
> 
> * doc/automake.texi (Yacc and Lex): Tell that automake recognizes

s/Tell/Document/
("tell" is rarely a good choice in written text.  I don't know why.)

> '-d' in AM_YFLAGS only if it's not clusterd with other options.

clustered

> From a report by ???????? ????????????????????.

My email client renders this as a bunch of question marks only.  Please
ensure that both the git log entry and the ChangeLog entry are properly
encoded in UTF-8.

> --- a/doc/automake.texi
> +++ b/doc/automake.texi
> @@ -6078,7 +6078,12 @@ intended for the @file{Makefile.am} author.
>  @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
>  @command{yacc}.  Automake knows what this means and will automatically
>  adjust its rules to update and distribute the header file built by
> address@hidden -d}.  What Automake cannot guess, though, is where this
> address@hidden address@hidden note that @command{automake} recognizes
> address@hidden in @code{AM_YFLAGS} only if it is not clustered with other
> +options; for example, it won't be recognized if @code{AM_YFLAGS} is
> address@hidden, but it will be if @code{AM_YFLAGS} is @samp{-d -t} or
> address@hidden -d}.}.

Generally, @footnote's should be used sparingly, as they disrupt the
flow of reading and don't render well in the info output.  I guess it's
acceptable here though.

Please use @option for denoting the options here.

> +What Automake cannot guess, though, is where this
>  header will be used: it is up to you to ensure the header gets built
>  before it is first used.  Typically this is necessary in order for
>  dependency tracking to work when the header is included by another