doc: motivate named references.

[bison.git] / doc / bison.texinfo

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