doc: discuss named references after locations.

Reported by Hans Aberg at
<http://lists.gnu.org/archive/html/bug-bison/2011-05/msg00008.html>.
* NEWS (2.5.1): Document.
* doc/bison.texinfo (Named References): Because it discusses
locations in addition to semantic values, move this subsection out
of the section `Defining Language Semantics', where locations have
not yet been introduced, to be a new section after the following
section, `Tracking Locations'.
(cherry picked from commit 908c8647de654d4ab0944ecef7811af1d736742b)

3 files changed, 102 insertions, 89 deletions

diff --git a/ChangeLog b/ChangeLog
index c0bfec95..f9b8c120 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2011-05-29  Joel E. Denny  <joeldenny@joeldenny.org>
 
+	doc: discuss named references after locations.
+	Reported by Hans Aberg at
+	<http://lists.gnu.org/archive/html/bug-bison/2011-05/msg00008.html>.
+	* NEWS (2.5.1): Document.
+	* doc/bison.texinfo (Named References): Because it discusses
+	locations in addition to semantic values, move this subsection out
+	of the section `Defining Language Semantics', where locations have
+	not yet been introduced, to be a new section after the following
+	section, `Tracking Locations'.
+
+2011-05-29  Joel E. Denny  <joeldenny@joeldenny.org>
+
 	Prepare for the possibility of a 2.5.1 release.
 	* NEWS (2.5.1): New heading.
 
diff --git a/NEWS b/NEWS
index 435279fa..ff3f19fe 100644
--- a/NEWS
+++ b/NEWS
@@ -62,6 +62,8 @@ Bison News
 
 * Changes in version 2.5.1 (????-??-??):
 
+** Minor improvements have been made to the manual.
+
 * Changes in version 2.5 (2011-05-14):
 
 ** Grammar symbol names can now contain non-initial dashes:
diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index ce86334d..456eb7b6 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -187,6 +187,7 @@ Bison Grammar Files
 * Recursion::         Writing recursive rules.
 * Semantics::         Semantic values and actions.
 * Locations::         Locations and actions.
+* Named References::  Using named references in actions.
 * Declarations::      All kinds of Bison declarations are described here.
 * Multiple Parsers::  Putting more than one Bison parser in one program.
 
@@ -207,7 +208,6 @@ Defining Language Semantics
 * Mid-Rule Actions::  Most actions go at the end of a rule.
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.
-* Named References::  Using named references in actions.
 
 Tracking Locations
 
@@ -2701,6 +2701,7 @@ The Bison grammar file conventionally has a name ending in @samp{.y}.
 * Recursion::         Writing recursive rules.
 * Semantics::         Semantic values and actions.
 * Locations::         Locations and actions.
+* Named References::  Using named references in actions.
 * Declarations::      All kinds of Bison declarations are described here.
 * Multiple Parsers::  Putting more than one Bison parser in one program.
 @end menu
@@ -3462,7 +3463,6 @@ the numbers associated with @var{x} and @var{y}.
 * Mid-Rule Actions::  Most actions go at the end of a rule.
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.
-* Named References::  Using named references in actions.
 @end menu
 
 @node Value Type
@@ -3880,93 +3880,6 @@ compound: subroutine
 Now Bison can execute the action in the rule for @code{subroutine} without
 deciding which rule for @code{compound} it will eventually use.
 
-@node Named References
-@subsection Using Named References
-@cindex named references
-
-While every semantic value can be accessed with positional references
-@code{$@var{n}} and @code{$$}, it's often much more convenient to refer to
-them by name.  First of all, original symbol names may be used as named
-references.  For example:
-
-@example
-@group
-invocation: op '(' args ')'
-  @{ $invocation = new_invocation ($op, $args, @@invocation); @}
-@end group
-@end example
-
-@noindent
-The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be
-mixed with @code{$name} and @code{@@name} arbitrarily.  For example:
-
-@example
-@group
-invocation: op '(' args ')'
-  @{ $$ = new_invocation ($op, $args, @@$); @}
-@end group
-@end example
-
-@noindent
-However, sometimes regular symbol names are not sufficient due to
-ambiguities:
-
-@example
-@group
-exp: exp '/' exp
-  @{ $exp = $exp / $exp; @} // $exp is ambiguous.
-
-exp: exp '/' exp
-  @{ $$ = $1 / $exp; @} // One usage is ambiguous.
-
-exp: exp '/' exp
-  @{ $$ = $1 / $3; @} // No error.
-@end group
-@end example
-
-@noindent
-When ambiguity occurs, explicitly declared names may be used for values and
-locations.  Explicit names are declared as a bracketed name after a symbol
-appearance in rule definitions.  For example:
-@example
-@group
-exp[result]: exp[left] '/' exp[right]
-  @{ $result = $left / $right; @}
-@end group
-@end example
-
-@noindent
-Explicit names may be declared for RHS and for LHS symbols as well.  In order
-to access a semantic value generated by a mid-rule action, an explicit name
-may also be declared by putting a bracketed name after the closing brace of
-the mid-rule action code:
-@example
-@group
-exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right]
-  @{ $res = $left + $right; @}
-@end group
-@end example
-
-@noindent
-
-In references, in order to specify names containing dots and dashes, an explicit
-bracketed syntax @code{$[name]} and @code{@@[name]} must be used:
-@example
-@group
-if-stmt: IF '(' expr ')' THEN then.stmt ';'
-  @{ $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); @}
-@end group
-@end example
-
-It often happens that named references are followed by a dot, dash or other
-C punctuation marks and operators.  By default, Bison will read
-@code{$name.suffix} as a reference to symbol value @code{$name} followed by
-@samp{.suffix}, i.e., an access to the @samp{suffix} field of the semantic
-value.  In order to force Bison to recognize @code{name.suffix} in its entirety
-as the name of a semantic value, bracketed syntax @code{$[name.suffix]}
-must be used.
-
-
 @node Locations
 @section Tracking Locations
 @cindex location
@@ -4175,6 +4088,92 @@ macro should expand to something that can be used as a single
 statement when it is followed by a semicolon.
 @end itemize
 
+@node Named References
+@section Using Named References
+@cindex named references
+
+While every semantic value can be accessed with positional references
+@code{$@var{n}} and @code{$$}, it's often much more convenient to refer to
+them by name.  First of all, original symbol names may be used as named
+references.  For example:
+
+@example
+@group
+invocation: op '(' args ')'
+  @{ $invocation = new_invocation ($op, $args, @@invocation); @}
+@end group
+@end example
+
+@noindent
+The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be
+mixed with @code{$name} and @code{@@name} arbitrarily.  For example:
+
+@example
+@group
+invocation: op '(' args ')'
+  @{ $$ = new_invocation ($op, $args, @@$); @}
+@end group
+@end example
+
+@noindent
+However, sometimes regular symbol names are not sufficient due to
+ambiguities:
+
+@example
+@group
+exp: exp '/' exp
+  @{ $exp = $exp / $exp; @} // $exp is ambiguous.
+
+exp: exp '/' exp
+  @{ $$ = $1 / $exp; @} // One usage is ambiguous.
+
+exp: exp '/' exp
+  @{ $$ = $1 / $3; @} // No error.
+@end group
+@end example
+
+@noindent
+When ambiguity occurs, explicitly declared names may be used for values and
+locations.  Explicit names are declared as a bracketed name after a symbol
+appearance in rule definitions.  For example:
+@example
+@group
+exp[result]: exp[left] '/' exp[right]
+  @{ $result = $left / $right; @}
+@end group
+@end example
+
+@noindent
+Explicit names may be declared for RHS and for LHS symbols as well.  In order
+to access a semantic value generated by a mid-rule action, an explicit name
+may also be declared by putting a bracketed name after the closing brace of
+the mid-rule action code:
+@example
+@group
+exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right]
+  @{ $res = $left + $right; @}
+@end group
+@end example
+
+@noindent
+
+In references, in order to specify names containing dots and dashes, an explicit
+bracketed syntax @code{$[name]} and @code{@@[name]} must be used:
+@example
+@group
+if-stmt: IF '(' expr ')' THEN then.stmt ';'
+  @{ $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); @}
+@end group
+@end example
+
+It often happens that named references are followed by a dot, dash or other
+C punctuation marks and operators.  By default, Bison will read
+@code{$name.suffix} as a reference to symbol value @code{$name} followed by
+@samp{.suffix}, i.e., an access to the @samp{suffix} field of the semantic
+value.  In order to force Bison to recognize @code{name.suffix} in its entirety
+as the name of a semantic value, bracketed syntax @code{$[name.suffix]}
+must be used.
+
 @node Declarations
 @section Bison Declarations
 @cindex declarations, Bison