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)

diff --git a/ChangeLog b/ChangeLog
index a639466a994ec4aba69205c9125890c24b97ba74..7f516ae7aae7c5e7ba38772dcc88d7be7a5284a2 100644 (file)
--- a/ChangeLog
+++ b/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.

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 6471b3b65c5a202cf5c22be9eca07d11ad859141..a8bfb2bad3acac761785bd67f9ed8de463070b8a 100644 (file)
--- 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