doc: explain how mid-rule actions are translated

* 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.

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.
 
+@menu
+* 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.
+@end menu
+
+@node Using Mid-Rule Actions
+@subsubsection Using Mid-Rule Actions
+
 A mid-rule action may refer to the components preceding it using
 @code{$@var{n}}, 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
-@samp{stmt} 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}):
+
+@example
+@group
+stmt:
+  "let" '(' var ')'
+    @{
+      $<context>let = push_context ();
+      declare_variable ($3);
+    @}[let]
+  stmt
+    @{
+      $$ = $6;
+      pop_context ($<context>let);
+    @}
+@end group
+@end 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.
 
+@node Mid-Rule Action Translation
+@subsubsection Mid-Rule Action Translation
+@vindex $@@@var{n}
+@vindex @@@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:
+
+@example
+exp: @{ a(); @} "b" @{ c(); @} @{ d(); @} "e" @{ f(); @};
+@end example
+
+@noindent
+is translated into:
+
+@example
+$@@1: /* empty */ @{ a(); @};
+$@@2: /* empty */ @{ c(); @};
+$@@3: /* empty */ @{ d(); @};
+exp: $@@1 "b" $@@2 $@@3 "e" @{ f(); @};
+@end example
+
+@noindent
+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 @code{$@var{n}} where @var{n} denote the mid-rule
+action.  In that case its nonterminal is rather named @code{@@@var{n}}:
+
+@example
+exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+@end example
+
+@noindent
+is translated into
+
+@example
+@@1: /* empty */ @{ a(); @};
+@@2: /* empty */ @{ $$ = c(); @};
+$@@3: /* empty */ @{ d(); @};
+exp: @@1 "b" @@2 $@@3 "e" @{ f = $1; @}
+@end 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
+@code{midrule-value} warnings are enabled (@pxref{Invocation, ,Invoking
+Bison}):
+
+@example
+$ bison -fcaret -Wmidrule-value mid.y
+@group
+mid.y:2.6-13: warning: unset value: $$
+ exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+      ^^^^^^^^
+@end group
+@group
+mid.y:2.19-31: warning: unused value: $3
+ exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @};
+                   ^^^^^^^^^^^^^
+@end group
+@end example
+
+
+@node Mid-Rule Conflicts
+@subsubsection 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}
+@deffnx {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
 
+@deffn {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}.
+@end deffn
+
 @deffn {Variable} $$
 In an action, the semantic value of the left-hand side of the rule.
 @xref{Actions}.