diff options
| -rw-r--r-- | ChangeLog | 10 | ||||
| -rw-r--r-- | doc/bison.texinfo | 42 |
2 files changed, 32 insertions, 20 deletions
@@ -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 |