doc: clean up `Named References' a little.

* doc/bison.texinfo (Named References): Rename section to match
the node name, and update all cross references.  Don't use the
acronyms RHS and LHS given that we don't expand them anywhere in
the manual.  Try to use @samp and @code properly.  Mention that
named references are experimental as we've already stated in NEWS.
(Destructor Decl): Expand the only remaining use of RHS or LHS.
(cherry picked from commit ce24f7f59b)

ChangeLog

@@ -1,3 +1,13 @@
+2011-05-29  Joel E. Denny  <joeldenny@joeldenny.org>
+
+	doc: clean up `Named References' a little.
+	* doc/bison.texinfo (Named References): Rename section to match
+	the node name, and update all cross references.  Don't use the
+	acronyms RHS and LHS given that we don't expand them anywhere in
+	the manual.  Try to use @samp and @code properly.  Mention that
+	named references are experimental as we've already stated in NEWS.
+	(Destructor Decl): Expand the only remaining use of RHS or LHS.
+
 2011-05-29  Joel E. Denny  <joeldenny@joeldenny.org>
 
 	doc: motivate named references.

doc/bison.texinfo

@@ -3583,8 +3583,8 @@ the addition-expression just recognized by the rule.  If there were a
 useful semantic value associated with the @samp{+} token, it could be
 referred to as @code{$2}.
 
-@xref{Named References,,Using Named References}, for more information
+@xref{Named References}, for more information about using the named
-about using the named references construct.
+references construct.
 
 Note that the vertical-bar character @samp{|} is really a rule
 separator, and actions are attached to a single rule.  This is a
@@ -3950,8 +3950,8 @@ The location of the @var{n}th component of the right hand side is
 
 In addition, the named references construct @code{@@@var{name}} and
 @code{@@[@var{name}]} may also be used to address the symbol locations.
-@xref{Named References,,Using Named References}, for more information
+@xref{Named References}, for more information about using the named
-about using the named references construct.
+references construct.
 
 Here is a basic example using the default data type for locations:
 
@@ -4089,7 +4089,7 @@ statement when it is followed by a semicolon.
 @end itemize
 
 @node Named References
-@section Using Named References
+@section Named References
 @cindex named references
 
 As described in the preceding sections, the traditional way to refer to any
@@ -4149,10 +4149,9 @@ exp[result]: exp[left] '/' exp[right]
 @end example
 
 @noindent
-Explicit names may be declared for RHS and for LHS symbols as well.  In order
+In order to access a semantic value generated by a mid-rule action, an
-to access a semantic value generated by a mid-rule action, an explicit name
+explicit name may also be declared by putting a bracketed name after the
-may also be declared by putting a bracketed name after the closing brace of
+closing brace of the mid-rule action code:
-the mid-rule action code:
 @example
 @group
 exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right]
@@ -4173,11 +4172,14 @@ if-stmt: IF '(' expr ')' THEN then.stmt ';'
 
 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{$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
+@samp{.suffix}, i.e., an access to the @code{suffix} field of the semantic
-value.  In order to force Bison to recognize @code{name.suffix} in its entirety
+value.  In order to force Bison to recognize @samp{name.suffix} in its
-as the name of a semantic value, bracketed syntax @code{$[name.suffix]}
+entirety as the name of a semantic value, the bracketed syntax
-must be used.
+@samp{$[name.suffix]} must be used.
+
+The named references feature is experimental.  More user feedback will help
+to stabilize it.
 
 @node Declarations
 @section Bison Declarations
@@ -4625,12 +4627,12 @@ redefine it from @code{$end} to, for example, @code{END}:
 @cindex mid-rule actions
 Finally, Bison will never invoke a @code{%destructor} for an unreferenced
 mid-rule semantic value (@pxref{Mid-Rule Actions,,Actions in Mid-Rule}).
-That is, Bison does not consider a mid-rule to have a semantic value if you do
+That is, Bison does not consider a mid-rule to have a semantic value if you
-not reference @code{$$} in the mid-rule's action or @code{$@var{n}} (where
+do not reference @code{$$} in the mid-rule's action or @code{$@var{n}}
-@var{n} is the RHS symbol position of the mid-rule) in any later action in that
+(where @var{n} is the right-hand side symbol position of the mid-rule) in
-rule.
+any later action in that rule.  However, if you do reference either, the
-However, if you do reference either, the Bison-generated parser will invoke the
+Bison-generated parser will invoke the @code{<>} @code{%destructor} whenever
-@code{<>} @code{%destructor} whenever it discards the mid-rule symbol.
+it discards the mid-rule symbol.
 
 @ignore
 @noindent