RFC: doc: update documentation about --verbose

[Akim Demaille]

For master, and maint if easy (pushed in next with all
the other pending patches).

Currently the bits about solved conflicts are too
wide for the smallbook, they would require smallexample,
or be broken into more lines than in Real Life.

But we could also look for another presentation.
Currently:

> state 8
> 
>     1 exp: exp . '+' exp
>     1    | exp '+' exp .  [$end, '+', '-', '/']
>     2    | exp . '-' exp
>     3    | exp . '*' exp
>     4    | exp . '/' exp
> 
>     '*'  shift, and go to state 6
>     '/'  shift, and go to state 7
> 
>     '/'       [reduce using rule 1 (exp)]
>     $default  reduce using rule 1 (exp)
> 
>     Conflict between rule 1 and token '+' resolved as reduce (%left '+').
>     Conflict between rule 1 and token '-' resolved as reduce (%left '-').
>     Conflict between rule 1 and token '*' resolved as shift ('+' < '*').


It could end with:

>     Solved conflicts:
>       - rule 1 vs. token '+': reduce (%left '+')
>       - rule 1 vs. token '-': reduce (%left '-')
>       - rule 1 vs. token '*': shift ('+' < '*')

It could even be (if for instance I duplicate the rule
for '+' to get a reduce/reduce conflicts):

> state 8
> 
>     1 exp: exp . '+' exp
>     1    | exp '+' exp .  [$end, '+', '-', '/']
>     2    | exp . '+' exp
>     2    | exp '+' exp .  [$end, '+', '-', '/']
>     3    | exp . '-' exp
>     4    | exp . '*' exp
>     5    | exp . '/' exp
> 
>     '*'  shift, and go to state 6
>     '/'  shift, and go to state 7
> 
>     $end      reduce using rule 1 (exp)
>     '+'       reduce using rule 1 (exp)
>     '-'       reduce using rule 1 (exp)
>     $default  reduce using rule 1 (exp)
> 
>     Unresolved shift/reduce conflicts:
>       - rule 1 vs. token '/': shift
>       - rule 1 vs. token '/': shift
> 
>     Reduce/reduce conflicts:
>       - rule 1 vs. rule 2 [$end, '+', '-', '/']: rule 1
> 
>     User solved conflicts:
>       - rule 1 vs. token '+': reduce (%left '+')
>       - rule 1 vs. token '-': reduce (%left '-')
>       - rule 1 vs. token '*': shift ('+' < '*')
>       - rule 2 vs. token '*': shift ('+' < '*')


(I don't know how easy the not-solved conflicts part would be)
instead of:

> state 8
> 
>     1 exp: exp . '+' exp
>     1    | exp '+' exp .  [$end, '+', '-', '/']
>     2    | exp . '+' exp
>     2    | exp '+' exp .  [$end, '+', '-', '/']
>     3    | exp . '-' exp
>     4    | exp . '*' exp
>     5    | exp . '/' exp
> 
>     '*'  shift, and go to state 6
>     '/'  shift, and go to state 7
> 
>     $end      reduce using rule 1 (exp)
>     $end      [reduce using rule 2 (exp)]
>     '+'       reduce using rule 1 (exp)
>     '+'       [reduce using rule 2 (exp)]
>     '-'       reduce using rule 1 (exp)
>     '-'       [reduce using rule 2 (exp)]
>     '/'       [reduce using rule 1 (exp)]
>     '/'       [reduce using rule 2 (exp)]
>     $default  reduce using rule 1 (exp)
> 
>     Conflict between rule 1 and token '+' resolved as reduce (%left '+').
>     Conflict between rule 1 and token '-' resolved as reduce (%left '-').
>     Conflict between rule 1 and token '*' resolved as shift ('+' < '*').
>     Conflict between rule 2 and token '*' resolved as shift ('+' < '*').




From bca9bf1ff94861dbee2c791e8ae3698d7c9291ec Mon Sep 17 00:00:00 2001
From: Akim Demaille <address@hidden>
Date: Fri, 16 Mar 2012 10:13:16 +0100
Subject: [PATCH] doc: update the --verbose report format.

* doc/bison.texinfo (Understanding): Adjust to match the
current format.
---
 doc/bison.texinfo |  272 +++++++++++++++++++++++++++--------------------------
 1 file changed, 139 insertions(+), 133 deletions(-)

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 8739819..9824781 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -8416,26 +8416,6 @@ creates a file @file{calc.output} with contents detailed 
below.  The
 order of the output and the exact presentation might vary, but the
 interpretation is the same.
 
-The first section includes details on conflicts that were solved thanks
-to precedence and/or associativity:
-
address@hidden
-Conflict in state 8 between rule 2 and token '+' resolved as reduce.
-Conflict in state 8 between rule 2 and token '-' resolved as reduce.
-Conflict in state 8 between rule 2 and token '*' resolved as shift.
address@hidden @dots{}
address@hidden example
-
address@hidden
-The next section lists states that still have conflicts.
-
address@hidden
-State 8 conflicts: 1 shift/reduce
-State 9 conflicts: 1 shift/reduce
-State 10 conflicts: 1 shift/reduce
-State 11 conflicts: 4 shift/reduce
address@hidden example
-
 @noindent
 @cindex token, useless
 @cindex useless token
@@ -8443,36 +8423,45 @@ State 11 conflicts: 4 shift/reduce
 @cindex useless nonterminal
 @cindex rule, useless
 @cindex useless rule
-The next section reports useless tokens, nonterminal and rules.  Useless
-nonterminals and rules are removed in order to produce a smaller parser,
-but useless tokens are preserved, since they might be used by the
-scanner (note the difference between ``useless'' and ``unused''
-below):
+The first section reports useless tokens, nonterminal and rules.  Useless
+nonterminals and rules are removed in order to produce a smaller parser, but
+useless tokens are preserved, since they might be used by the scanner (note
+the difference between ``useless'' and ``unused'' below):
 
 @example
-Nonterminals useless in grammar:
+Nonterminals useless in grammar
    useless
 
-Terminals unused in grammar:
+Terminals unused in grammar
    STR
 
-Rules useless in grammar:
-#6     useless: STR;
+Rules useless in grammar
+    6 useless: STR
 @end example
 
 @noindent
-The next section reproduces the exact grammar that Bison used:
+The next section lists states that still have conflicts.
+
address@hidden
+State 8 conflicts: 1 shift/reduce
+State 9 conflicts: 1 shift/reduce
+State 10 conflicts: 1 shift/reduce
+State 11 conflicts: 4 shift/reduce
address@hidden example
+
address@hidden
+Then Bison reproduces the exact grammar it used:
 
 @example
 Grammar
 
-  Number, Line, Rule
-    0   5 $accept -> exp $end
-    1   5 exp -> exp '+' exp
-    2   6 exp -> exp '-' exp
-    3   7 exp -> exp '*' exp
-    4   8 exp -> exp '/' exp
-    5   9 exp -> NUM
+    0 $accept: exp $end
+
+    1 exp: exp '+' exp
+    2    | exp '-' exp
+    3    | exp '*' exp
+    4    | exp '/' exp
+    5    | NUM
 @end example
 
 @noindent
@@ -8489,14 +8478,15 @@ $end (0) 0
 '/' (47) 4
 error (256)
 NUM (258) 5
+STR (259)
 @end group
 
 @group
 Nonterminals, with rules where they appear
 
-$accept (8)
+$accept (9)
     on left: 0
-exp (9)
+exp (10)
     on left: 1 2 3 4 5, on right: 0 1 2 3 4
 @end group
 @end example
@@ -8513,11 +8503,11 @@ that the input cursor.
 @example
 state 0
 
-    $accept  ->  . exp $   (rule 0)
+    0 $accept: . exp $end
 
-    NUM         shift, and go to state 1
+    NUM  shift, and go to state 1
 
-    exp         go to state 2
+    exp  go to state 2
 @end example
 
 This reads as follows: ``state 0 corresponds to being at the very
@@ -8544,27 +8534,27 @@ be derived:
 @example
 state 0
 
-    $accept  ->  . exp $   (rule 0)
-    exp  ->  . exp '+' exp   (rule 1)
-    exp  ->  . exp '-' exp   (rule 2)
-    exp  ->  . exp '*' exp   (rule 3)
-    exp  ->  . exp '/' exp   (rule 4)
-    exp  ->  . NUM   (rule 5)
+    0 $accept: . exp $end
+    1 exp: . exp '+' exp
+    2    | . exp '-' exp
+    3    | . exp '*' exp
+    4    | . exp '/' exp
+    5    | . NUM
 
-    NUM         shift, and go to state 1
+    NUM  shift, and go to state 1
 
-    exp         go to state 2
+    exp  go to state 2
 @end example
 
 @noindent
-In the state 1...
+In the state address@hidden
 
 @example
 state 1
 
-    exp  ->  NUM .   (rule 5)
+    5 exp: NUM .
 
-    $default    reduce using rule 5 (exp)
+    $default  reduce using rule 5 (exp)
 @end example
 
 @noindent
@@ -8576,24 +8566,24 @@ jump to state 2 (@samp{exp: go to state 2}).
 @example
 state 2
 
-    $accept  ->  exp . $   (rule 0)
-    exp  ->  exp . '+' exp   (rule 1)
-    exp  ->  exp . '-' exp   (rule 2)
-    exp  ->  exp . '*' exp   (rule 3)
-    exp  ->  exp . '/' exp   (rule 4)
+    0 $accept: exp . $end
+    1 exp: exp . '+' exp
+    2    | exp . '-' exp
+    3    | exp . '*' exp
+    4    | exp . '/' exp
 
-    $           shift, and go to state 3
-    '+'         shift, and go to state 4
-    '-'         shift, and go to state 5
-    '*'         shift, and go to state 6
-    '/'         shift, and go to state 7
+    $end  shift, and go to state 3
+    '+'   shift, and go to state 4
+    '-'   shift, and go to state 5
+    '*'   shift, and go to state 6
+    '/'   shift, and go to state 7
 @end example
 
 @noindent
 In state 2, the automaton can only shift a symbol.  For instance,
-because of the item @samp{exp -> exp . '+' exp}, if the lookahead if
+because of the item @samp{exp: exp . '+' exp}, if the lookahead if
 @samp{+}, it will be shifted on the parse stack, and the automaton
-control will jump to state 4, corresponding to the item @samp{exp -> exp
+control will jump to state 4, corresponding to the item @samp{exp: exp
 '+' . exp}.  Since there is no default action, any other token than
 those listed above will trigger a syntax error.
 
@@ -8604,14 +8594,14 @@ state}:
 @example
 state 3
 
-    $accept  ->  exp $ .   (rule 0)
+    0 $accept: exp $end .
 
-    $default    accept
+    $default  accept
 @end example
 
 @noindent
-the initial rule is completed (the start symbol and the end
-of input were read), the parsing exits successfully.
+the initial rule is completed (the start symbol and the end-of-input were
+read), the parsing exits successfully.
 
 The interpretation of states 4 to 7 is straightforward, and is left to
 the reader.
@@ -8619,35 +8609,38 @@ the reader.
 @example
 state 4
 
-    exp  ->  exp '+' . exp   (rule 1)
+    1 exp: exp '+' . exp
 
-    NUM         shift, and go to state 1
+    NUM  shift, and go to state 1
+
+    exp  go to state 8
 
-    exp         go to state 8
 
 state 5
 
-    exp  ->  exp '-' . exp   (rule 2)
+    2 exp: exp '-' . exp
+
+    NUM  shift, and go to state 1
 
-    NUM         shift, and go to state 1
+    exp  go to state 9
 
-    exp         go to state 9
 
 state 6
 
-    exp  ->  exp '*' . exp   (rule 3)
+    3 exp: exp '*' . exp
 
-    NUM         shift, and go to state 1
+    NUM  shift, and go to state 1
+
+    exp  go to state 10
 
-    exp         go to state 10
 
 state 7
 
-    exp  ->  exp '/' . exp   (rule 4)
+    4 exp: exp '/' . exp
 
-    NUM         shift, and go to state 1
+    NUM  shift, and go to state 1
 
-    exp         go to state 11
+    exp  go to state 11
 @end example
 
 As was announced in beginning of the report, @samp{State 8 conflicts:
@@ -8656,17 +8649,17 @@ As was announced in beginning of the report, 
@samp{State 8 conflicts:
 @example
 state 8
 
-    exp  ->  exp . '+' exp   (rule 1)
-    exp  ->  exp '+' exp .   (rule 1)
-    exp  ->  exp . '-' exp   (rule 2)
-    exp  ->  exp . '*' exp   (rule 3)
-    exp  ->  exp . '/' exp   (rule 4)
+    1 exp: exp . '+' exp
+    1    | exp '+' exp .
+    2    | exp . '-' exp
+    3    | exp . '*' exp
+    4    | exp . '/' exp
 
-    '*'         shift, and go to state 6
-    '/'         shift, and go to state 7
+    '*'  shift, and go to state 6
+    '/'  shift, and go to state 7
 
-    '/'         [reduce using rule 1 (exp)]
-    $default    reduce using rule 1 (exp)
+    '/'       [reduce using rule 1 (exp)]
+    $default  reduce using rule 1 (exp)
 @end example
 
 Indeed, there are two actions associated to the lookahead @samp{/}:
@@ -8680,7 +8673,7 @@ NUM}, which corresponds to reducing rule 1.
 
 Because in deterministic parsing a single decision can be made, Bison
 arbitrarily chose to disable the reduction, see @ref{Shift/Reduce, ,
-Shift/Reduce Conflicts}.  Discarded actions are reported in between
+Shift/Reduce Conflicts}.  Discarded actions are reported between
 square brackets.
 
 Note that all the previous states had a single possible action: either
@@ -8699,72 +8692,85 @@ with some set of possible lookahead tokens.  When run 
with
 @example
 state 8
 
-    exp  ->  exp . '+' exp   (rule 1)
-    exp  ->  exp '+' exp .  [$, '+', '-', '/']   (rule 1)
-    exp  ->  exp . '-' exp   (rule 2)
-    exp  ->  exp . '*' exp   (rule 3)
-    exp  ->  exp . '/' exp   (rule 4)
+    1 exp: exp . '+' exp
+    1    | exp '+' exp .  [$end, '+', '-', '/']
+    2    | exp . '-' exp
+    3    | exp . '*' exp
+    4    | exp . '/' exp
+
+    '*'  shift, and go to state 6
+    '/'  shift, and go to state 7
 
-    '*'         shift, and go to state 6
-    '/'         shift, and go to state 7
+    '/'       [reduce using rule 1 (exp)]
+    $default  reduce using rule 1 (exp)
address@hidden example
+
+Note however that while @samp{NUM + NUM / NUM} is amiguous (which results in
+the conflicts on @samp{/}), @samp{NUM + NUM * NUM} is not: the conflit was
+solved thanks to associativity and precedence directives.  If invoked with
address@hidden, Bison includes information about the solved
+conflicts in the report:
 
-    '/'         [reduce using rule 1 (exp)]
-    $default    reduce using rule 1 (exp)
address@hidden
+Conflict between rule 1 and token '+' resolved as reduce (%left '+').
+Conflict between rule 1 and token '-' resolved as reduce (%left '-').
+Conflict between rule 1 and token '*' resolved as shift ('+' < '*').
 @end example
 
+
 The remaining states are similar:
 
 @example
 @group
 state 9
 
-    exp  ->  exp . '+' exp   (rule 1)
-    exp  ->  exp . '-' exp   (rule 2)
-    exp  ->  exp '-' exp .   (rule 2)
-    exp  ->  exp . '*' exp   (rule 3)
-    exp  ->  exp . '/' exp   (rule 4)
+    1 exp: exp . '+' exp
+    2    | exp . '-' exp
+    2    | exp '-' exp .
+    3    | exp . '*' exp
+    4    | exp . '/' exp
 
-    '*'         shift, and go to state 6
-    '/'         shift, and go to state 7
+    '*'  shift, and go to state 6
+    '/'  shift, and go to state 7
 
-    '/'         [reduce using rule 2 (exp)]
-    $default    reduce using rule 2 (exp)
+    '/'       [reduce using rule 2 (exp)]
+    $default  reduce using rule 2 (exp)
 @end group
 
 @group
 state 10
 
-    exp  ->  exp . '+' exp   (rule 1)
-    exp  ->  exp . '-' exp   (rule 2)
-    exp  ->  exp . '*' exp   (rule 3)
-    exp  ->  exp '*' exp .   (rule 3)
-    exp  ->  exp . '/' exp   (rule 4)
+    1 exp: exp . '+' exp
+    2    | exp . '-' exp
+    3    | exp . '*' exp
+    3    | exp '*' exp .
+    4    | exp . '/' exp
 
-    '/'         shift, and go to state 7
+    '/'  shift, and go to state 7
 
-    '/'         [reduce using rule 3 (exp)]
-    $default    reduce using rule 3 (exp)
+    '/'       [reduce using rule 3 (exp)]
+    $default  reduce using rule 3 (exp)
 @end group
 
 @group
 state 11
 
-    exp  ->  exp . '+' exp   (rule 1)
-    exp  ->  exp . '-' exp   (rule 2)
-    exp  ->  exp . '*' exp   (rule 3)
-    exp  ->  exp . '/' exp   (rule 4)
-    exp  ->  exp '/' exp .   (rule 4)
-
-    '+'         shift, and go to state 4
-    '-'         shift, and go to state 5
-    '*'         shift, and go to state 6
-    '/'         shift, and go to state 7
-
-    '+'         [reduce using rule 4 (exp)]
-    '-'         [reduce using rule 4 (exp)]
-    '*'         [reduce using rule 4 (exp)]
-    '/'         [reduce using rule 4 (exp)]
-    $default    reduce using rule 4 (exp)
+    1 exp: exp . '+' exp
+    2    | exp . '-' exp
+    3    | exp . '*' exp
+    4    | exp . '/' exp
+    4    | exp '/' exp .
+
+    '+'  shift, and go to state 4
+    '-'  shift, and go to state 5
+    '*'  shift, and go to state 6
+    '/'  shift, and go to state 7
+
+    '+'       [reduce using rule 4 (exp)]
+    '-'       [reduce using rule 4 (exp)]
+    '*'       [reduce using rule 4 (exp)]
+    '/'       [reduce using rule 4 (exp)]
+    $default  reduce using rule 4 (exp)
 @end group
 @end example
 
-- 
1.7.9.2