From a40e77ebf62c136a38594ce30cf39ae2f5f08471 Mon Sep 17 00:00:00 2001 From: "Joel E. Denny" Date: Sun, 29 May 2011 20:06:22 -0400 Subject: doc: motivate named references. Suggested by Hans Aberg at . * doc/bison.texinfo (Named References): Explain briefly how they're better than the traditional positional references. (cherry picked from commit 7d31f0928907ccdd647479075d385b5a36c62611) --- ChangeLog | 8 ++++++++ doc/bison.texinfo | 17 +++++++++++------ 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index f9b8c120..a639466a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2011-05-29 Joel E. Denny + + doc: motivate named references. + Suggested by Hans Aberg at + . + * doc/bison.texinfo (Named References): Explain briefly how + they're better than the traditional positional references. + 2011-05-29 Joel E. Denny doc: discuss named references after locations. diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 456eb7b6..6471b3b6 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -4092,10 +4092,16 @@ statement when it is followed by a semicolon. @section Using Named References @cindex named references -While every semantic value can be accessed with positional references -@code{$@var{n}} and @code{$$}, it's often much more convenient to refer to -them by name. First of all, original symbol names may be used as named -references. For example: +As described in the preceding sections, the traditional way to refer to any +semantic value or location is a @dfn{positional reference}, which takes the +form @code{$@var{n}}, @code{$$}, @code{@@@var{n}}, and @code{@@$}. However, +such a reference is not very descriptive. Moreover, if you later decide to +insert or remove symbols in the right-hand side of a grammar rule, the need +to renumber such references can be tedious and error-prone. + +To avoid these issues, you can also refer to a semantic value or location +using a @dfn{named reference}. First of all, original symbol names may be +used as named references. For example: @example @group @@ -4105,8 +4111,7 @@ invocation: op '(' args ')' @end example @noindent -The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be -mixed with @code{$name} and @code{@@name} arbitrarily. For example: +Positional and named references can be mixed arbitrarily. For example: @example @group -- cgit v1.2.1