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 ce24f7f59b9ececb3137a53a881e25fa28e19466)

2 files changed, 32 insertions, 20 deletions

diff --git a/ChangeLog b/ChangeLog
index a639466a..7f516ae7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
 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.
 	Suggested by Hans Aberg at
 	<http://lists.gnu.org/archive/html/bug-bison/2011-05/msg00008.html>.
diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 6471b3b6..a8bfb2ba 100644
--- a/doc/bison.texinfo
+++ b/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
-about using the named references construct.
+@xref{Named References}, for more information about using the named
+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
-about using the named references construct.
+@xref{Named References}, for more information about using the named
+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
-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:
+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]
@@ -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{.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.
+@samp{$name.suffix} as a reference to symbol value @code{$name} followed by
+@samp{.suffix}, i.e., an access to the @code{suffix} field of the semantic
+value.  In order to force Bison to recognize @samp{name.suffix} in its
+entirety as the name of a semantic value, the bracketed syntax
+@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
-not reference @code{$$} in the mid-rule's action or @code{$@var{n}} (where
-@var{n} is the RHS symbol position of the mid-rule) in any later action in that
-rule.
-However, if you do reference either, the Bison-generated parser will invoke the
-@code{<>} @code{%destructor} whenever it discards the mid-rule symbol.
+That is, Bison does not consider a mid-rule to have a semantic value if you
+do not reference @code{$$} in the mid-rule's action or @code{$@var{n}}
+(where @var{n} is the right-hand side symbol position of the mid-rule) in
+any later action in that rule.  However, if you do reference either, the
+Bison-generated parser will invoke the @code{<>} @code{%destructor} whenever
+it discards the mid-rule symbol.
 
 @ignore
 @noindent