doc: motivate named references.

Suggested by Hans Aberg at
<http://lists.gnu.org/archive/html/bug-bison/2011-05/msg00008.html>.
* doc/bison.texinfo (Named References): Explain briefly how
they're better than the traditional positional references.
(cherry picked from commit 7d31f0928907ccdd647479075d385b5a36c62611)

diff --git a/ChangeLog b/ChangeLog
index f9b8c12089b8d7b60fdbd7f14e5654185f327dcf..a639466a994ec4aba69205c9125890c24b97ba74 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+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>.
+       * doc/bison.texinfo (Named References): Explain briefly how
+       they're better than the traditional positional references.
+
 2011-05-29  Joel E. Denny  <joeldenny@joeldenny.org>
 
        doc: discuss named references after locations.

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