Re: push parser documentation

[Joel E. Denny]

On Sat, 4 Aug 2007, Bob Rossi wrote:

> > Moreover, to keep users safe, I wonder if impure push mode should have a 
> > global variable that counts yypstate instances.  If yypstate_new detects 
> > more than 1 instance, it should invoke yyerror with a message about 
> > %pure-parser and then return NULL.
> > 
> > What do you think?
> 
> I'm not sure. There are some unfortunate limitations this would impose
> on the user. Say they wanted to create all of the objects up front but
> then there program is "smart enough" to ensure they are only used one at
> a time. At least with the new documentation, they are warned...

If a user needs multiple objects, he should declare %pure-parser, so I 
don't really see this as a limitation.  Does that alleviate your concern? 
Again, I feel that impure push parsers are only for backward compatibility 
with Yacc pull parsing, which also, because of its global variables, can 
support only one parser instance at a time.

> > > +When the @code{%push-parser} or @code{%push-pull-parser} declaration is 
> > > used
> > > +then it is important to understand that all references to the 
> > > @code{yyparse}
> > > +function in this manual corresponds to the @code{yypush_parser} function 
> > > +unless otherwise stated.
> > 
> > I'm afraid I don't understand what you mean in that last paragraph.  Can 
> > we drop it?
> 
> OK, This sentence seemed important to me. I'll describe the problem, let
> me know what a good solution is. There are lots of places in the manual
> where it says "X happens when pure parser is used" or "X is in yyparse
> function". I wanted to make it clear the the yyparse function is the
> same as the yypush_parse function in that regards. Maybe that is just
> obvious to the uesr?

There are statements in the manual for which this isn't true.  For 
example, in section 1.7 Bison Output: the Parser File:

  The Bison parser file is C code which defines a function named
  `yyparse' which implements that grammar.  This function does not make a
  complete C program: you must supply some additional functions.  One is
  the lexical analyzer.

The last statement is true of yyparse or yypull_parse but not 
yypush_parse.

Another in section 2.1.2.1 Explanation of `input':

  The parser function `yyparse' continues to process input until a
  grammatical error is seen or the lexical analyzer says there are no more
  input tokens; we will arrange for the latter to happen at end-of-input.

This is only true of pull parsers.

I didn't search any further for additional examples, but I think you can 
see the problem.  The manual was written mostly with traditional Yacc pull 
parsing in mind.  I'm guessing it makes many more statements that don't 
make sense for push parsing.  I feel that readers will understand that the 
push parsing documentation shows a way to modify the functionality 
described in the rest of the manual, and I don't think you should claim 
that the rest of the manual applies to push parsing.

Does this make sense to you?

I'll have to review the rest of your changes later.