Re: Questions on 3.4.6 Actions

[Akim Demaille]

Hi Arthur,

> Le 15 sept. 2022 à 23:11, Arthur Schwarz <home@slipbits.com> a écrit :
> 
> Hi Akim;
> 
> You seem to be the go-to person for Harsh and Unremitting Criticism; sorry.

I don't know how to read your sentence :)  It's ambiguous to me.  But reports 
are welcome.  You made many of them, unfortunately during a time where I was 
away from Bison.  They are still on my radar, and I will process them, in 
series, when I have time.


> What is being said is that the User's Manual is incomplete in that it doesn't 
> give a full description of the syntax. It selectively chooses what syntax to 
> describe and ignores the rest. This is a request to expand the syntax 
> descriptions to include the entire Bison specific syntax. I think I sent you 
> a partial document to illustrate what I mean.

I have great respect for this user manual.  It is one of the most well written 
ones I saw in the GNU realm.  Or "was": Charles Donnelly had written it for 
Bison in its original state, say 1.28.  Over the years many changes were made 
in Bison, which required to add pieces of documentation here and there.  As a 
consequence, I am pretty confident the manual is not as beautiful as it once 
was, and probably ugly in some places.  However, I try to respect the spirit of 
this text, its structure. In particular it starts with more or less a tutorial, 
and then proceeds with something more like a reference manual.  It is therefore 
expected that early sections keep silent about gory details, or avoid defining 
rigorously things upfront, when common sense usually suffices to fill the gap.

And I will keep this.

I'm ok with forward-references though.


> I think that the user should be made aware of what syntax is legitimate. For 
> example, is "%token" a keyword or is "%" a delimiter and "token" a keyword. 
> If "%" is a delimiter does that mean that between the "%" and the "token" 
> there can be zero or more blanks. Must a Bison item be fully contained on a 
> single line, or can it be on multiple lines. What is the alphabet. Where are 
> blanks allowed. What is a delimiter, and so on.

I believe that you are right, and I doubt it's specified somewhere in the 
documentation that you can't put comments between "%" and "token".

But on this regard, I don't care.  If someone wants to try, bison will quickly 
give some feedback on this weird idea.

Similarly, I won't try to document Bison's grammar.  Because it is actually 
quite complex, because I don't think it really provides insight to the reader, 
and because if the reader is really looking for such details about Bison, she 
can certainly read parsegram.y and get the true truth.

So rather, we try to document things where they matter, for instance precisely 
the section about %token, %left, etc. 
(https://lists.gnu.org/r/bug-bison/2022-09/msg00009.html)


> I can volunteer my time to provide text (putting words where my mouth is - a 
> sick, sad, pun). I'm not asking for something that I can't aid in producing.

Contributions are most welcome!  But please note that this is on my spare time, 
and my bandwidth is limited.

Cheers.