Re: --report

[Paul Eggert]

> From: Akim Demaille <address@hidden>
> Date: 20 May 2002 20:11:47 +0200

> address@hidden 1
> +
> +The textual file is generated when the options @option{--report} or
> address@hidden are specified, see @xref{Invocation, , Invoking
> +Bison}.
> +
> +also describes all the conflicts, both those resolved
> +by operator precedence and the unresolved ones.

The text looks incomplete.  Also, I assume the "@sp 1" is a typo?

> +As expected, @command{bison} reports that @samp{calc.y contains 1

I don't understand why the two words "As expected" are there.
Perhaps they should be removed?

> +useless nonterminal and 1 useless rule} and that @samp{calc.y contains 7
> +shift/reduce conflicts}.  When given @option{--report=state}, in
> +addition to @file{calc.tab.c}, it has created a file @file{calc.output}

has created -> creates

> +which contents is detailed address@hidden order of the paragraphs

which contents is -> with contents
paragraphs -> output

I would move the footnote into the main text.  Footnotes are evil;
sometimes a necessary evil, but not here.

> +The first section includes details on conflicts which were solved thanks

which -> that

> +Then states which still have conflicts are listed.

Change to:
The next section lists states that still have conflicts.

(I prefer active voice to passive.)

> +Useless tokens, nonterminal and rules are reported.

Change to:
The next section reports useless tokens, nonterminals, and rules.

> +nonterminals and rules are really removed in order to produce a smaller

really ->

> +Terminals which are not used:

which -> that
(this requires a code change)

+The exact grammar that Bison used is then reproduced.

Change to:
The next section reproduces the exact grammar that Bison used:

> +  Number, Line, Rule
> +    0   5 $axiom -> exp $

What is the "axiom"?  The term is never explained.  It should be
explained at its first occurrence.

> +and the uses of the symbols are reported:

Change to:
and reports the uses of the symbols:

> +Bison then proceeds onto the automaton itself, describing each state
> +with it set of @dfn{items}, also known as ``pointed rules'':

with it -> with its

``pointed rules'': ->
``pointed rules''.  Each item is a production rule together with a
point (marked by @code{.}) that stands for the input cursor.

> address@hidden
> +state 0
> +
> +    $axiom  ->  . exp $   (rule 0)
> +
> +    NUM      shift, and go to state 1
> +
> +    exp      go to state 2
> address@hidden example
> +
> +It reads as follows: ``state 0 corresponds to being at the very

It -> This

> +beginning of the parsing, in the initial rule, right before the axiom
> +(here, @code{exp}).  When the parser is in this state, if a reduction
> +produced an @code{exp}, the control flow jumps to state 1.  If there is

produced -> produces
state 1 -> state 2

> +no such transition on a nonterminal symbol, and the lookahead is a

Sorry, I don't understand what the phrase "If there is no such
transition on a nonterminal symbol" is getting at.  NUM and exp are
both lookaheads; one is a nonterminal, the other a terminal.  Perhaps
the point should be made that exp is a lookahead too?

> address@hidden, then this token is shifted on the parse stack, and the
> +control flow jumps to state 2.  Any other lookahead triggers a parse

state 2 -> state 1

> +You might wonder how the automaton can expect a @code{NUM} while the
> +only active rule in state 0 seems to be rule 0.  Actually, the reading
> +point being right before an @code{exp}, the automaton knows it can be at
> +the beginning of any rule deriving an @code{exp}, and by default it
> +reports only the so called @dfn{core} or @dfn{kernel} of the item set.
> +Invoking @command{bison} with @option{--report=itemset} lists all the
> +items, including those that can be derived:

It's better if the documentation is not anthropomorphic.  Also, this
description confuses Bison with the automaton.  And it uses "item set"
without defining it.  How about this rewrite instead?

Even though the only active rule in state 0 seems to be rule 0, the
report lists @code{NUM} as a lookahead symbol because @code{NUM} can
be at the beginning of any rule deriving an @code{exp}.  By default
Bison reports the so-called @dfn{core} or @dfn{kernel} of the item
set, but if you want to see more detail you can invoke @command{bison}
with @option{--report=itemset} to list all the items, including those
that can be derived:

> +
> +For instance, on the following grammar
> +

This insertion seems to be a stray typo and should be removed.

> +  /* In a series of synonyms, present the most meaning full first, so

meaning full -> meaningful

> +THINGS is a list of comma separated words amongst:\n\

amongst: -> that can include:

> +  `state'        description of the states\n\

description of the states -> describe the states


> +#define report_none        (0)
> +#define report_states      (1 << 0)
> +#define report_itemsets    (1 << 1 | report_states)
> +#define report_lookaheads  (1 << 2 | report_states)
> +#define report_all         (~0)
> +extern int report_flag;
> +/* Return TRUE iff THING ought to be reported.  */
> +#define report_p(Thing)   ((report_flag & report_##Thing) == report_##Thing)

This is a fairly minor point, but I would parenthesize 1<<1 and 1<<2
to avoid warnings with some compilers.  Better yet, I would use an
enum, and remove the funny dependency of report_itemsets on
report_states.  I.e.:

  enum
  {
    report_none = 0,
    report_states = 1 << 0,
    report_itemsets = 1 << 1,
    report_lookaheads = 1 << 2,
    report_all = ~0
  };
  extern int report_flag;

and then in the rest of the code, uniformly replace:

report_p (states) -> report_flag
report_p (itemsets) -> report_flag & itemsets
report_p (lookaheads) -> report_flag & lookaheads

This will be easier to understand, for me at least
(and it will also generate slightly faster code :-).