doc: clean up `Named References' a little.

[bison.git] / doc / bison.texinfo

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