Re: Bug in documentation for 3.0.4

[Gabriel Czernikier]

I would give me a take to explain it better.

The introduction of the section 3.4.8.2, "Mid-Rule Action Translation"
makes it seeming that a subject will be addressed along the section about
how Bison's reports can reveal that the grammar was changed to a different
form, after applying mid-rules processing. Thru the end of the section, it
doesn't happen.

It wouldn't be a true bug, if other sections of the manual took up to
address the subject. The section "8.1 Understanding your parser", is
probably the major candidate to do this job, since the introduction of the
secction in question (3.4.8.2) points to it as the place to find more
information. If section 8.1 already does it, that could mean the end of
this bug. If not, it could mean the need of putting a better reference in
the introduction (which doesn't mean to remove the current reference to
8.1).

Anyway, the introduction states that Bison's reports reveal the
translations in the grammar when any of them has taken place, but it
doesn't specify which of all the reports are reached by this statement. By
the end of the section, there is kind of and example of an invocation to
Bison and its return messages when run for a grammar having mid-rules hence
owning the conditions to be translated. Though not its major sake, this
example is an opportunity to make a point on the subject. Because it
doesn't care to do so, it can left the reader in a feeling of hesitation,
perhaps wondering any of the following:
- Does the report contained in this example falls out of the category of
Bison's reports that reveal translations in grammars?
- Does this example purposely simplifies things by means of ommiting the
translations in the grammar that would be revealed in real life?
- Is it all about an error in the manual?

After all, and to sum things up, what we have is:
- An introduction, making a sort of assertion on grammar translations and
reports revealing them.
- A section in which this introduction is found, not careing to show an
example of that.
- An example, by the end of the section that, while playing for a different
purpose, makes doubt turn out if the it has to be reformulated in how the
messages are reported to be consistent with "revealing the translations".
- A reference to other section that, in the case of expanding the subject
with examples and/or specifications, results in leaving the first section
being not self-contained. Not a big problem, would be my personal opinion.

Regards,
Gabriel Czernikier


On Thu, Jan 12, 2017 at 5:55 PM, Gabriel Czernikier <address@hidden>
wrote:

> Hello,
>
> I find the section 3.4.8.2 Mid-Rule Action Translation being a bit
> confusing, for what I raise this bug report.
>
> As I understand per the first paragraph, the goal of this section is to
> show how mid-rule translation works, and the output of one or more Bison
> reports revealing the structural grammar changes due to that translation.
>
> The next lines of text, give examples of grammars containing mid-rules and
> the translations that take place on them, which ultimately works for the
> sake of the lesson taught by this section.
>
> The last example, by its own side, is intended to show tne outcomes of a
> mid-rule that refers to an unused $$, and a final (last component) rule
> that refer to a mid-rule without $$ asingment. Although, this goal is well
> achieved, a reader could get confused expecting the output reveal the
> translations about which were taken up in prior paragraphs.
>
> The documentation should give one example that shows how the report of
> Bison's output features alterations in the actual grammar. Or else, it
> should make an statement that both given cases, the one with the grammar
> translations and the one with the Bison invocation, are unrelated to each
> other.
>
> Regards,
> Gabriel Czernikier
>
>