Re: Proposal to improving section 3.4.5 of the Bison's manual for version 3.0.4

[Gabriel Czernikier]

Hello,

About the subject in the title, of which I talked yesterday, I would like
to be more clear.

I’m having difficulties to get to know what “such as previous comments”
exactly means. This phrase is cited from section 3.4.5 “Providing a
Structured Semantic Value Type”.

The phrase is kind of reference to a “previous” section in which “comments”
are made on purpose of the topic being discussed in the paragraph to which
that phrase belongs: using structured values for the %define api.value.type
as a mean to track symbol information.

Now, citing other parts of the paragraph, if “every symbol” is to be
tracked information for, then a struct being the semantic type fits very
well to the case. If not so for every symbol, then you can have a structure
for some symbols and whatever types for others, all wrapped in an union.
The section 2.5 “Multi-Function Calculator: mfcalc” is an example where a
“union” is declared as the type, and a structure is contained in its inner
for only the symbols that require tracking, not all of them. After all,
whether it be “{union}”, “union” or “{struct}”, the option for %define
api.value.type could be considered more relatively: whenever you would
choose “{struct}”, you could as well choose any of the other two; of
course, changing the type declaration implies more things to be changed,
you always have to know what you are doing, but essentially, one
declaration can take the place of the other with neither loss of
functionality nor harm if at an early stage of development.

Unlike most references in the handbook, which are very precise in terms of
where they are pointing out, the phrase in question, “such as preceding
comments”, is vague to the extreme of doubt about whether or not it is
meant as a reference. With a note on the fact that example of section 2.5
entails structs but within a union declaration to track some symbols, one
could put a reference to that example, instead of the vague phrase in
question.

The writing of a new example that uses “{struct}” for completing the
section is another option. I would keep in mind the handbook being short
and simple. The more references can be given to existing text, the less new
text has to be written. Additionally, a mention on something relative to
compiler construction fits very well within around the same paragraph
claimed in need of a fix. A text could be appended which states that, in
creating a compiler, symbol information tracking is involved. The same text
could give a reference to stuff on the subject, possibly picked from the
“Bibliography” section.

Sincerely,
Gabriel Czernikier

On Wed, Feb 1, 2017 at 5:49 PM, Gabriel Czernikier <address@hidden>
wrote:

> Hello,
>
> I have an opinion on Bison’s manual for Bison 3.0.4, particularly about
> the %define api.value.type when used with the “{struct…}” option.
>
> Storing, alongside the parser states, structured values on the push stack,
> leverages the parser to a capability extent unreacheable if through the
> more modest untyped and union values.
>
> Between parentheses, you can consider unions bearing with such structures
> as a particularity for the generality addressed in these notes.
>
> Just to be mentioned by a humble naive on the matter, structured values
> representing the grammar symbols are used to build a so called “derivation
> tree”, used in compiler construction. Bison and especially Yacc handbooks
> themselves have a bibliographical references notice pointing to papers
> talking on that (be a case “LR Parsing”, A. V. Aho and S. C. Johnson). Yacc
> handbook is included in standard Bison distributions.
>
> Structured values used in the parser, open the door to all sort of
> possibilities, techniques and subjects that are addressed in their own,
> dedicated-to-the-subject books. Giving bibliographic references does a job
> in showing the reader that open door.
>
> In section 3.4.5, “Providing a Structured Semantic Value Type”, we have
> the following text: “Actually, you may also provide a struct rather that a
> union, which may be handy if you want to track information for every symbol
> (such as preceding comments).”
>
> It’s okay to say it, except the part “(such as preceding comments)”, for
> when I read it, I was led into a state of uncertainness.
>
> To me, a question arose on  what “preceding comments” means. I thought it
> was a way of handling with input string representing “comments” in the
> language of the generated parser (for example /*this*/ in C). Not. Then I
> thought it was about a loose reference to a “previous comment” on the
> handbook itself (lacking the precise section, in contrast to usual Bison
> manual’s internal reference style). Neither.
>
> The quoted paragraph (except the phrase in objection) is a place on the
> book that makes an opportunity available to lead the reader to a state of
> curiosity about what will be beyond what I called above the “open door”,
> had this paragraph ended with a more instilling phrase, one that conveys
> through path on structured values, track of symbols, a mention on the big
> subject they relate to, Bison’s impossibility to have it all inside its
> scope, and a connection to the bibliographical references section. We could
> think a reformulation to the paragraph entirely.
>
> Sincerely,
> Gabriel Czernikier
>