[PATCH 6/6] doc: explain how mid-rule actions are translated

[Akim Demaille]

* doc/bison.texi (Actions in Mid-Rule): Mention and use named references.
Split into three subsections, among which...
(Mid-Rule Action Translation): this new section.
---
 NEWS           |  10 ++---
 doc/bison.texi | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 123 insertions(+), 9 deletions(-)

diff --git a/NEWS b/NEWS
index cecc676..6149ea8 100644
--- a/NEWS
+++ b/NEWS
@@ -2,9 +2,6 @@ GNU Bison NEWS
 
 * Noteworthy changes in release ?.? (????-??-??) [?]
 
-
-* Noteworthy changes in release 2.6.90 (2012-12-07) [beta]
-
 ** Bug fixes
 
   Warnings about uninitialized yylloc in yyparse have been fixed.
@@ -99,13 +96,16 @@ GNU Bison NEWS
   These changes are present in both --graph output and xml2dot.xsl XSLT
   processing, with minor (documented) differences.
 
-  Two nodes were added to the documentation: Xml and Graphviz.
-
 ** Documentation
 
   The sections about shift/reduce and reduce/reduce conflicts resolution
   have been fixed and extended.
 
+  Although introduced more than four years ago, XML and Graphviz reports
+  were not properly documented.
+
+  The translation of mid-rule actions is now described.
+
 * Noteworthy changes in release 2.6.5 (2012-11-07) [stable]
 
   We consider compiler warnings about Bison generated parsers to be bugs.
diff --git a/doc/bison.texi b/doc/bison.texi
index 5a6cb68..a508b9c 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -208,6 +208,12 @@ Defining Language Semantics
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.
 
+Actions in Mid-Rule
+
+* Using Mid-Rule Actions::       Putting an action in the middle of a rule.
+* Mid-Rule Action Translation::  How mid-rule actions are actually processed.
+* Mid-Rule Conflicts::           Mid-rule actions can cause conflicts.
+
 Tracking Locations
 
 * Location Type::               Specifying a data type for locations.
@@ -3739,6 +3745,15 @@ Occasionally it is useful to put an action in the middle 
of a rule.
 These actions are written just like usual end-of-rule actions, but they
 are executed before the parser even recognizes the following components.
 
address@hidden
+* Using Mid-Rule Actions::       Putting an action in the middle of a rule.
+* Mid-Rule Action Translation::  How mid-rule actions are actually processed.
+* Mid-Rule Conflicts::           Mid-rule actions can cause conflicts.
address@hidden menu
+
address@hidden Using Mid-Rule Actions
address@hidden Using Mid-Rule Actions
+
 A mid-rule action may refer to the components preceding it using
 @address@hidden, but it may not refer to subsequent components because
 it is run before they are parsed.
@@ -3791,8 +3806,27 @@ list of accessible variables) as its semantic value, 
using alternative
 @code{context} in the data-type union.  Then it calls
 @code{declare_variable} to add the new variable to that list.  Once the
 first action is finished, the embedded statement @code{stmt} can be
-parsed.  Note that the mid-rule action is component number 5, so the
address@hidden is component number 6.
+parsed.
+
+Note that the mid-rule action is component number 5, so the @samp{stmt} is
+component number 6.  Named references can be used to improve the readability
+and maintainability (@pxref{Named References}):
+
address@hidden
address@hidden
+stmt:
+  "let" '(' var ')'
+    @{
+      $<context>let = push_context ();
+      declare_variable ($3);
+    @}[let]
+  stmt
+    @{
+      $$ = $6;
+      pop_context ($<context>let);
+    @}
address@hidden group
address@hidden example
 
 After the embedded statement is parsed, its semantic value becomes the
 value of the entire @code{let}-statement.  Then the semantic value from the
@@ -3826,13 +3860,13 @@ stmt:
   let stmt
     @{
       $$ = $2;
-      pop_context ($1);
+      pop_context ($let);
     @};
 
 let:
   "let" '(' var ')'
     @{
-      $$ = push_context ();
+      $let = push_context ();
       declare_variable ($3);
     @};
 
@@ -3844,6 +3878,76 @@ Note that the action is now at the end of its rule.
 Any mid-rule action can be converted to an end-of-rule action in this way, and
 this is what Bison actually does to implement mid-rule actions.
 
address@hidden Mid-Rule Action Translation
address@hidden Mid-Rule Action Translation
address@hidden $@@@var{n}
address@hidden @@@var{n}
+
+As hinted earlier, mid-rule actions are actually transformed into regular
+rules and actions.  The various reports generated by Bison (textual,
+graphical, etc., see @ref{Understanding, , Understanding Your Parser})
+reveal this translation, best explained by means of an example.  The
+following rule:
+
address@hidden
+exp: @{ a(); @} "b" @{ c(); @} @{ d(); @} "e" @{ f(); @};
address@hidden example
+
address@hidden
+is translated into:
+
address@hidden
+$@@1: /* empty */ @{ a(); @};
+$@@2: /* empty */ @{ c(); @};
+$@@3: /* empty */ @{ d(); @};
+exp: $@@1 "b" $@@2 $@@3 "e" @{ f(); @};
address@hidden example
+
address@hidden
+with new nonterminal symbols @code{$@@@var{n}}, where @var{n} is a number.
+
+A mid-rule action is expected to generate a value if it uses @code{$$}, or
+the (final) action uses @address@hidden where @var{n} denote the mid-rule
+action.  In that case its nonterminal is rather named @code{@@@var{n}}:
+
address@hidden
+exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
address@hidden example
+
address@hidden
+is translated into
+
address@hidden
+@@1: /* empty */ @{ a(); @};
+@@2: /* empty */ @{ $$ = c(); @};
+$@@3: /* empty */ @{ d(); @};
+exp: @@1 "b" @@2 $@@3 "e" @{ f = $1; @}
address@hidden example
+
+There are probably two errors in the above example: the first mid-rule
+action does not generate a value (it does not use @code{$$} although the
+final action uses it), and the value of the second one is not used (the
+final action does not use @code{$3}).  Bison reports these errors when the
address@hidden warnings are enabled (@pxref{Invocation, ,Invoking
+Bison}):
+
address@hidden
+$ bison -fcaret -Wmidrule-value mid.y
address@hidden
+mid.y:2.6-13: warning: unset value: $$
+ exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+      ^^^^^^^^
address@hidden group
address@hidden
+mid.y:2.19-31: warning: unused value: $3
+ exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+                   ^^^^^^^^^^^^^
address@hidden group
address@hidden example
+
+
address@hidden Mid-Rule Conflicts
address@hidden Conflicts due to Mid-Rule Actions
 Taking action before a rule is completely recognized often leads to
 conflicts since the parser must commit to a parse in order to execute the
 action.  For example, the following two rules, without mid-rule actions,
@@ -3941,6 +4045,7 @@ compound:
 Now Bison can execute the action in the rule for @code{subroutine} without
 deciding which rule for @code{compound} it will eventually use.
 
+
 @node Tracking Locations
 @section Tracking Locations
 @cindex location
@@ -11404,8 +11509,12 @@ In an action, the location of the left-hand side of 
the rule.
 @end deffn
 
 @deffn {Variable} @@@var{n}
address@hidden {Symbol} @@@var{n}
 In an action, the location of the @var{n}-th symbol of the right-hand side
 of the rule.  @xref{Tracking Locations}.
+
+In a grammar, the Bison-generated nonterminal symbol for a mid-rule action
+with a semantical value.  @xref{Mid-Rule Action Translation}.
 @end deffn
 
 @deffn {Variable} @@@var{name}
@@ -11414,6 +11523,11 @@ In an action, the location of a symbol addressed by 
@var{name}.
 @xref{Tracking Locations}.
 @end deffn
 
address@hidden {Symbol} $@@@var{n}
+In a grammar, the Bison-generated nonterminal symbol for a mid-rule action
+with no semantical value.  @xref{Mid-Rule Action Translation}.
address@hidden deffn
+
 @deffn {Variable} $$
 In an action, the semantic value of the left-hand side of the rule.
 @xref{Actions}.
-- 
1.8.0.1