Re: [SPAM] Re: [updated PATCH] %language declaration

[Joel E. Denny]

On Wed, 13 Dec 2006, Paul Eggert wrote:

> "Joel E. Denny" <address@hidden> writes:
> 
> > Do you use `make alpha', `make distcheck', or something else to roll the 
> > tarball?
> 
> I don't use 'make alpha'; it doesn't work.  I can't remember now whether
> I use make distcheck or make maintainer-check; probably both.
>
> ('make alpha' is high-maintenance, and nobody has the time to maintain
> it right now.)

Thanks.  It seems that HACKING needs an update.

> >> Can we reword this documentation to not need
> >> the version number?
> >
> > That implies that we should never refer to the next release in the manual.
> 
> As a general rule, the manual should explain only the current Bison
> release.  The manual is not a good place to discuss what we might do
> in the future, or what things looked like in the past, as typically
> such discussions overly complicate the explanation of the present
> situation.  Plus, these discussions make the manual harder to maintain
> -- and it's important to keep the manual easy to maintain.
> 
> For future stuff, TODO is the usual place.
> 
> For past stuff, NEWS and/or ChangeLog is the usual place.
> 
> (There are exceptions to this general rule of course.)

Paolo, following the above general rule, maybe the manual shouldn't try to 
explain how to achieve backward compatibility, so we could eliminate 
mention of 2.3b.  I'm looking at this:

  @footnote{For both
  the grammar directive and the command-line option, the
  language name is case-insensitive}.  These were introduced
  in Bison 2.3b; for compatibility with earlier versions, you
  may also pass the option @option{--skeleton=lalr1.cc} to Bison
  or include the directive @samp{%skeleton "lalr1.cc"} in the
  grammar preamble.  Specifying the language is however preferred,
  because it is clearer and because it will automatically choose the
  correct skeleton for GLR parsers (the C++ GLR skeleton is still
  under development).

(By the way, I'm wondering if the notes about case sensitivity and about 
why %language is better than %skeleton are a distraction in "C++ Bison 
Interface".  Why not just cross-reference the %language documentation and 
explain it there?  By "the %language documentation", I mean the %language 
entry in "Bison Declaration Summary".  Shouldn't %language and %skeleton 
also appear in "Bison Symbols"?  Or maybe "Bison Symbols", which appears 
to be comprehensive, is sufficient?)

For the %require in the "C++ Parser" example, maybe it should always 
reference @value{VERSION}?  extexi would need to parse @value{VERSION}, so 
you'd need a slightly different version of your previous extexi patch.  
In this way, the C++ example appearing in the manual will be consistent 
with the one extracted and checked.  Moreover, the examples will always 
make sense for the current version, which is probably more reasonable 
anyway.