bug-bison
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: bison-2.5 released [stable]


From: Joel E. Denny
Subject: Re: bison-2.5 released [stable]
Date: Sun, 29 May 2011 22:39:01 -0400 (EDT)
User-agent: Alpine 2.00 (DEB 1167 2008-08-23)

Hi Hans,

On Sun, 15 May 2011, Hans Aberg wrote:

> It compiles on Mac OS X 10.6.7, Xcode Version 3.2.6 64-bit, 
> i686-apple-darwin10-gcc-4.2.1 (GCC) 4.2.1 which is a GCC derived 
> compiler. (On this platform, there is a later clang/llvm based compiler, 
> too, that comes with Xcode 4.)

Good to hear.

> In the Bison manual, sec. 3.5.6, "Using Named References", the @ 
> location variables are used without reference before they are defined in 
> the next section. So perhaps some link there.

I had meant to move that section after the location section, but I forgot.

> The first line of this section might say that named references may be 
> more convenient, as they are more descriptive and avoid the renumbering 
> problem.

You're probably right.  It might not be obvious to everyone why numbers 
are bad.

Thanks for the feedback.

Does anyone object to the following patches?  They also include some 
documentation changes we discussed over a year ago but that I never got 
around to.

(I'm not sure if there will be a 2.5.1 release or if we'll next release 
2.6 from master.  If the former is the case, then I don't want to have to 
cherry-pick patches later, so I'm planning to push these patches to both 
branch-2.5 and master.)

>From 90dcd4156ccab3d704d9ff2771b9ce7791e3ffc4 Mon Sep 17 00:00:00 2001
From: Joel E. Denny <address@hidden>
Date: Sun, 29 May 2011 20:49:16 -0400
Subject: [PATCH 1/6] Prepare for the possibility of a 2.5.1 release.

* NEWS (2.5.1): New heading.
---
 ChangeLog |    5 +++++
 NEWS      |    2 ++
 2 files changed, 7 insertions(+), 0 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 3302b42..66ea5ae 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2011-05-29  Joel E. Denny  <address@hidden>
+
+       Prepare for the possibility of a 2.5.1 release.
+       * NEWS (2.5.1): New heading.
+
 2011-05-14  Joel E. Denny  <address@hidden>
 
        Version 2.5.
diff --git a/NEWS b/NEWS
index f481850..bc76116 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,8 @@
 Bison News
 ----------
 
+* Changes in version 2.5.1 (????-??-??):
+
 * Changes in version 2.5 (2011-05-14):
 
 ** Grammar symbol names can now contain non-initial dashes:
-- 
1.7.0.4


>From 908c8647de654d4ab0944ecef7811af1d736742b Mon Sep 17 00:00:00 2001
From: Joel E. Denny <address@hidden>
Date: Sun, 29 May 2011 19:59:44 -0400
Subject: [PATCH 2/6] doc: discuss named references after locations.

Reported by Hans Aberg at
<http://lists.gnu.org/archive/html/bug-bison/2011-05/msg00008.html>.
* NEWS (2.5.1): Document.
* doc/bison.texinfo (Named References): Because it discusses
locations in addition to semantic values, move this subsection out
of the section `Defining Language Semantics', where locations have
not yet been introduced, to be a new section after the following
section, `Tracking Locations'.
---
 ChangeLog         |   12 ++++
 NEWS              |    2 +
 doc/bison.texinfo |  177 ++++++++++++++++++++++++++---------------------------
 3 files changed, 102 insertions(+), 89 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 66ea5ae..2bcb75d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2011-05-29  Joel E. Denny  <address@hidden>
 
+       doc: discuss named references after locations.
+       Reported by Hans Aberg at
+       <http://lists.gnu.org/archive/html/bug-bison/2011-05/msg00008.html>.
+       * NEWS (2.5.1): Document.
+       * doc/bison.texinfo (Named References): Because it discusses
+       locations in addition to semantic values, move this subsection out
+       of the section `Defining Language Semantics', where locations have
+       not yet been introduced, to be a new section after the following
+       section, `Tracking Locations'.
+
+2011-05-29  Joel E. Denny  <address@hidden>
+
        Prepare for the possibility of a 2.5.1 release.
        * NEWS (2.5.1): New heading.
 
diff --git a/NEWS b/NEWS
index bc76116..f847988 100644
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,8 @@ Bison News
 
 * Changes in version 2.5.1 (????-??-??):
 
+** Minor improvements have been made to the manual.
+
 * Changes in version 2.5 (2011-05-14):
 
 ** Grammar symbol names can now contain non-initial dashes:
diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index e0d5aa5..8fdac07 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -186,6 +186,7 @@ Bison Grammar Files
 * Recursion::         Writing recursive rules.
 * Semantics::         Semantic values and actions.
 * Locations::         Locations and actions.
+* Named References::  Using named references in actions.
 * Declarations::      All kinds of Bison declarations are described here.
 * Multiple Parsers::  Putting more than one Bison parser in one program.
 
@@ -206,7 +207,6 @@ Defining Language Semantics
 * Mid-Rule Actions::  Most actions go at the end of a rule.
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.
-* Named References::  Using named references in actions.
 
 Tracking Locations
 
@@ -2627,6 +2627,7 @@ The Bison grammar file conventionally has a name ending 
in @samp{.y}.
 * Recursion::         Writing recursive rules.
 * Semantics::         Semantic values and actions.
 * Locations::         Locations and actions.
+* Named References::  Using named references in actions.
 * Declarations::      All kinds of Bison declarations are described here.
 * Multiple Parsers::  Putting more than one Bison parser in one program.
 @end menu
@@ -3388,7 +3389,6 @@ the numbers associated with @var{x} and @var{y}.
 * Mid-Rule Actions::  Most actions go at the end of a rule.
                       This says when, why and how to use the exceptional
                         action in the middle of a rule.
-* Named References::  Using named references in actions.
 @end menu
 
 @node Value Type
@@ -3806,93 +3806,6 @@ compound: subroutine
 Now Bison can execute the action in the rule for @code{subroutine} without
 deciding which rule for @code{compound} it will eventually use.
 
address@hidden Named References
address@hidden Using Named References
address@hidden named references
-
-While every semantic value can be accessed with positional references
address@hidden@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:
-
address@hidden
address@hidden
-invocation: op '(' args ')'
-  @{ $invocation = new_invocation ($op, $args, @@invocation); @}
address@hidden group
address@hidden example
-
address@hidden
-The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be
-mixed with @code{$name} and @code{@@name} arbitrarily.  For example:
-
address@hidden
address@hidden
-invocation: op '(' args ')'
-  @{ $$ = new_invocation ($op, $args, @@$); @}
address@hidden group
address@hidden example
-
address@hidden
-However, sometimes regular symbol names are not sufficient due to
-ambiguities:
-
address@hidden
address@hidden
-exp: exp '/' exp
-  @{ $exp = $exp / $exp; @} // $exp is ambiguous.
-
-exp: exp '/' exp
-  @{ $$ = $1 / $exp; @} // One usage is ambiguous.
-
-exp: exp '/' exp
-  @{ $$ = $1 / $3; @} // No error.
address@hidden group
address@hidden example
-
address@hidden
-When ambiguity occurs, explicitly declared names may be used for values and
-locations.  Explicit names are declared as a bracketed name after a symbol
-appearance in rule definitions.  For example:
address@hidden
address@hidden
-exp[result]: exp[left] '/' exp[right]
-  @{ $result = $left / $right; @}
address@hidden group
address@hidden example
-
address@hidden
-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:
address@hidden
address@hidden
-exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right]
-  @{ $res = $left + $right; @}
address@hidden group
address@hidden example
-
address@hidden
-
-In references, in order to specify names containing dots and dashes, an 
explicit
-bracketed syntax @code{$[name]} and @code{@@[name]} must be used:
address@hidden
address@hidden
-if-stmt: IF '(' expr ')' THEN then.stmt ';'
-  @{ $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); @}
address@hidden group
address@hidden example
-
-It often happens that named references are followed by a dot, dash or other
-C punctuation marks and operators.  By default, Bison will read
address@hidden as a reference to symbol value @code{$name} followed by
address@hidden, 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.
-
-
 @node Locations
 @section Tracking Locations
 @cindex location
@@ -4101,6 +4014,92 @@ macro should expand to something that can be used as a 
single
 statement when it is followed by a semicolon.
 @end itemize
 
address@hidden Named References
address@hidden Using Named References
address@hidden named references
+
+While every semantic value can be accessed with positional references
address@hidden@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:
+
address@hidden
address@hidden
+invocation: op '(' args ')'
+  @{ $invocation = new_invocation ($op, $args, @@invocation); @}
address@hidden group
address@hidden example
+
address@hidden
+The positional @code{$$}, @code{@@$}, @code{$n}, and @code{@@n} can be
+mixed with @code{$name} and @code{@@name} arbitrarily.  For example:
+
address@hidden
address@hidden
+invocation: op '(' args ')'
+  @{ $$ = new_invocation ($op, $args, @@$); @}
address@hidden group
address@hidden example
+
address@hidden
+However, sometimes regular symbol names are not sufficient due to
+ambiguities:
+
address@hidden
address@hidden
+exp: exp '/' exp
+  @{ $exp = $exp / $exp; @} // $exp is ambiguous.
+
+exp: exp '/' exp
+  @{ $$ = $1 / $exp; @} // One usage is ambiguous.
+
+exp: exp '/' exp
+  @{ $$ = $1 / $3; @} // No error.
address@hidden group
address@hidden example
+
address@hidden
+When ambiguity occurs, explicitly declared names may be used for values and
+locations.  Explicit names are declared as a bracketed name after a symbol
+appearance in rule definitions.  For example:
address@hidden
address@hidden
+exp[result]: exp[left] '/' exp[right]
+  @{ $result = $left / $right; @}
address@hidden group
address@hidden example
+
address@hidden
+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:
address@hidden
address@hidden
+exp[res]: exp[x] '+' @{$left = $x;@}[left] exp[right]
+  @{ $res = $left + $right; @}
address@hidden group
address@hidden example
+
address@hidden
+
+In references, in order to specify names containing dots and dashes, an 
explicit
+bracketed syntax @code{$[name]} and @code{@@[name]} must be used:
address@hidden
address@hidden
+if-stmt: IF '(' expr ')' THEN then.stmt ';'
+  @{ $[if-stmt] = new_if_stmt ($expr, $[then.stmt]); @}
address@hidden group
address@hidden example
+
+It often happens that named references are followed by a dot, dash or other
+C punctuation marks and operators.  By default, Bison will read
address@hidden as a reference to symbol value @code{$name} followed by
address@hidden, 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.
+
 @node Declarations
 @section Bison Declarations
 @cindex declarations, Bison
-- 
1.7.0.4


>From 7d31f0928907ccdd647479075d385b5a36c62611 Mon Sep 17 00:00:00 2001
From: Joel E. Denny <address@hidden>
Date: Sun, 29 May 2011 20:06:22 -0400
Subject: [PATCH 3/6] 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.
---
 ChangeLog         |    8 ++++++++
 doc/bison.texinfo |   17 +++++++++++------
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 2bcb75d..ea82a41 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2011-05-29  Joel E. Denny  <address@hidden>
 
+       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  <address@hidden>
+
        doc: discuss named references after locations.
        Reported 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 8fdac07..42ea8e2 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -4018,10 +4018,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
address@hidden@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 @address@hidden, @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
@@ -4031,8 +4037,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
-- 
1.7.0.4


>From ce24f7f59b9ececb3137a53a881e25fa28e19466 Mon Sep 17 00:00:00 2001
From: Joel E. Denny <address@hidden>
Date: Sun, 29 May 2011 20:28:09 -0400
Subject: [PATCH 4/6] 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.
---
 ChangeLog         |   10 ++++++++++
 doc/bison.texinfo |   42 ++++++++++++++++++++++--------------------
 2 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ea82a41..e03b13b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
 2011-05-29  Joel E. Denny  <address@hidden>
 
+       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  <address@hidden>
+
        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 42ea8e2..0d6675b 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -3509,8 +3509,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}.
 
address@hidden References,,Using Named References}, for more information
-about using the named references construct.
address@hidden 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
@@ -3876,8 +3876,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{@@address@hidden may also be used to address the symbol locations.
address@hidden References,,Using Named References}, for more information
-about using the named references construct.
address@hidden References}, for more information about using the named
+references construct.
 
 Here is a basic example using the default data type for locations:
 
@@ -4015,7 +4015,7 @@ statement when it is followed by a semicolon.
 @end itemize
 
 @node Named References
address@hidden Using Named References
address@hidden Named References
 @cindex named references
 
 As described in the preceding sections, the traditional way to refer to any
@@ -4075,10 +4075,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]
@@ -4099,11 +4098,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
address@hidden as a reference to symbol value @code{$name} followed by
address@hidden, 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.
address@hidden as a reference to symbol value @code{$name} followed by
address@hidden, 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
address@hidden must be used.
+
+The named references feature is experimental.  More user feedback will help
+to stabilize it.
 
 @node Declarations
 @section Bison Declarations
@@ -4545,12 +4547,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 @address@hidden (where
address@hidden 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
address@hidden<>} @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 @address@hidden
+(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
-- 
1.7.0.4


>From 7404cdf3a1235c4f7304c29b942ac72029600f19 Mon Sep 17 00:00:00 2001
From: Joel E. Denny <address@hidden>
Date: Sun, 29 May 2011 22:18:27 -0400
Subject: [PATCH 5/6] doc: clean up references to `Tracking Locations'.

* doc/bison.texinfo (Locations): Rename node to...
(Tracking Locations): ... this, which is its section name, and
update all cross references.  The trouble is that there is another
node about locations.  Its section name is `Locations', which was
easily confused with the node name of this node.  Moreover, its
node name is `Locations Overview', which was mistakenly used to
label some cross references to this node.
---
 ChangeLog         |   11 +++++
 doc/bison.texinfo |  111 ++++++++++++++++++++++++++---------------------------
 2 files changed, 66 insertions(+), 56 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index e03b13b..7d45fc8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,16 @@
 2011-05-29  Joel E. Denny  <address@hidden>
 
+       doc: clean up references to `Tracking Locations'.
+       * doc/bison.texinfo (Locations): Rename node to...
+       (Tracking Locations): ... this, which is its section name, and
+       update all cross references.  The trouble is that there is another
+       node about locations.  Its section name is `Locations', which was
+       easily confused with the node name of this node.  Moreover, its
+       node name is `Locations Overview', which was mistakenly used to
+       label some cross references to this node.
+
+2011-05-29  Joel E. Denny  <address@hidden>
+
        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
diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 0d6675b..509dbed 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -180,15 +180,15 @@ Multi-Function Calculator: @code{mfcalc}
 
 Bison Grammar Files
 
-* Grammar Outline::   Overall layout of the grammar file.
-* Symbols::           Terminal and nonterminal symbols.
-* Rules::             How to write grammar rules.
-* Recursion::         Writing recursive rules.
-* Semantics::         Semantic values and actions.
-* Locations::         Locations and actions.
-* Named References::  Using named references in actions.
-* Declarations::      All kinds of Bison declarations are described here.
-* Multiple Parsers::  Putting more than one Bison parser in one program.
+* Grammar Outline::    Overall layout of the grammar file.
+* Symbols::            Terminal and nonterminal symbols.
+* Rules::              How to write grammar rules.
+* Recursion::          Writing recursive rules.
+* Semantics::          Semantic values and actions.
+* Tracking Locations:: Locations and actions.
+* Named References::   Using named references in actions.
+* Declarations::       All kinds of Bison declarations are described here.
+* Multiple Parsers::   Putting more than one Bison parser in one program.
 
 Outline of a Bison Grammar
 
@@ -1217,9 +1217,10 @@ the @dfn{textual location}, or @dfn{location}, of each 
syntactic construct.
 Bison provides a mechanism for handling these locations.
 
 Each token has a semantic value.  In a similar fashion, each token has an
-associated location, but the type of locations is the same for all tokens and
-groupings.  Moreover, the output parser is equipped with a default data
-structure for storing locations (@pxref{Locations}, for more details).
+associated location, but the type of locations is the same for all tokens
+and groupings.  Moreover, the output parser is equipped with a default data
+structure for storing locations (@pxref{Tracking Locations}, for more
+details).
 
 Like semantic values, locations can be reached in actions using a dedicated
 set of constructs.  In the example above, the location of the whole grouping
@@ -2621,15 +2622,15 @@ The Bison grammar file conventionally has a name ending 
in @samp{.y}.
 @xref{Invocation, ,Invoking Bison}.
 
 @menu
-* Grammar Outline::   Overall layout of the grammar file.
-* Symbols::           Terminal and nonterminal symbols.
-* Rules::             How to write grammar rules.
-* Recursion::         Writing recursive rules.
-* Semantics::         Semantic values and actions.
-* Locations::         Locations and actions.
-* Named References::  Using named references in actions.
-* Declarations::      All kinds of Bison declarations are described here.
-* Multiple Parsers::  Putting more than one Bison parser in one program.
+* Grammar Outline::    Overall layout of the grammar file.
+* Symbols::            Terminal and nonterminal symbols.
+* Rules::              How to write grammar rules.
+* Recursion::          Writing recursive rules.
+* Semantics::          Semantic values and actions.
+* Tracking Locations:: Locations and actions.
+* Named References::   Using named references in actions.
+* Declarations::       All kinds of Bison declarations are described here.
+* Multiple Parsers::   Putting more than one Bison parser in one program.
 @end menu
 
 @node Grammar Outline
@@ -3806,7 +3807,7 @@ compound: subroutine
 Now Bison can execute the action in the rule for @code{subroutine} without
 deciding which rule for @code{compound} it will eventually use.
 
address@hidden Locations
address@hidden Tracking Locations
 @section Tracking Locations
 @cindex location
 @cindex textual location
@@ -4918,9 +4919,8 @@ Unless your parser is pure, the parser header file 
declares
 (Reentrant) Parser}.
 
 If you have also used locations, the parser header file declares
address@hidden and @code{yylloc} using a protocol similar to that of
-the @code{YYSTYPE} macro and @code{yylval}.  @xref{Locations,
-,Tracking Locations}.
address@hidden and @code{yylloc} using a protocol similar to that of the
address@hidden macro and @code{yylval}.  @xref{Tracking Locations}.
 
 This parser header file is normally essential if you wish to put the
 definition of @code{yylex} in a separate source file, because
@@ -5759,12 +5759,12 @@ then the code in @code{yylex} might look like this:
 @subsection Textual Locations of Tokens
 
 @vindex yylloc
-If you are using the @samp{@@@var{n}}-feature (@pxref{Locations, ,
-Tracking Locations}) in actions to keep track of the textual locations
-of tokens and groupings, then you must provide this information in
address@hidden  The function @code{yyparse} expects to find the textual
-location of a token just parsed in the global variable @code{yylloc}.
-So @code{yylex} must store the proper data in that variable.
+If you are using the @samp{@@@var{n}}-feature (@pxref{Tracking Locations})
+in actions to keep track of the textual locations of tokens and groupings,
+then you must provide this information in @code{yylex}.  The function
address@hidden expects to find the textual location of a token just parsed
+in the global variable @code{yylloc}.  So @code{yylex} must store the proper
+data in that variable.
 
 By default, the value of @code{yylloc} is a structure and you need only
 initialize the members that are going to be used by the actions.  The
@@ -6090,9 +6090,9 @@ Actions}).
 
 @deffn {Value} @@$
 @findex @@$
-Acts like a structure variable containing information on the textual location
-of the grouping made by the current rule.  @xref{Locations, ,
-Tracking Locations}.
+Acts like a structure variable containing information on the textual
+location of the grouping made by the current rule.  @xref{Tracking
+Locations}.
 
 @c Check if those paragraphs are still useful or not.
 
@@ -6116,9 +6116,9 @@ Tracking Locations}.
 
 @deffn {Value} @@@var{n}
 @findex @@@var{n}
-Acts like a structure variable containing information on the textual location
-of the @var{n}th component of the current rule.  @xref{Locations, ,
-Tracking Locations}.
+Acts like a structure variable containing information on the textual
+location of the @var{n}th component of the current rule.  @xref{Tracking
+Locations}.
 @end deffn
 
 @node Internationalization
@@ -8760,10 +8760,10 @@ Symbols}.
 @c - %define filename_type "const symbol::Symbol"
 
 When the directive @code{%locations} is used, the C++ parser supports
-location tracking, see @ref{Locations, , Locations Overview}.  Two
-auxiliary classes define a @code{position}, a single point in a file,
-and a @code{location}, a range composed of a pair of
address@hidden (possibly spanning several files).
+location tracking, see @ref{Tracking Locations}.  Two auxiliary classes
+define a @code{position}, a single point in a file, and a @code{location}, a
+range composed of a pair of @code{position}s (possibly spanning several
+files).
 
 @deftypemethod {position} {std::string*} file
 The name of the file.  It will always be handled as a pointer, the
@@ -9515,14 +9515,13 @@ can be used to print the semantic values.  This however 
may change
 @c - class Position
 @c - class Location
 
-When the directive @code{%locations} is used, the Java parser
-supports location tracking, see @ref{Locations, , Locations Overview}.
-An auxiliary user-defined class defines a @dfn{position}, a single point
-in a file; Bison itself defines a class representing a @dfn{location},
-a range composed of a pair of positions (possibly spanning several
-files).  The location class is an inner class of the parser; the name
-is @code{Location} by default, and may also be renamed using
address@hidden location_type "@var{class-name}"}.
+When the directive @code{%locations} is used, the Java parser supports
+location tracking, see @ref{Tracking Locations}.  An auxiliary user-defined
+class defines a @dfn{position}, a single point in a file; Bison itself
+defines a class representing a @dfn{location}, a range composed of a pair of
+positions (possibly spanning several files).  The location class is an inner
+class of the parser; the name is @code{Location} by default, and may also be
+renamed using @code{%define location_type "@var{class-name}"}.
 
 The location class treats the position as a completely opaque value.
 By default, the class name is @code{Position}, but this can be changed
@@ -10362,22 +10361,22 @@ See @url{http://lists.gnu.org/}.
 
 @deffn {Variable} @@$
 In an action, the location of the left-hand side of the rule.
address@hidden, , Locations Overview}.
address@hidden Locations}.
 @end deffn
 
 @deffn {Variable} @@@var{n}
-In an action, the location of the @var{n}-th symbol of the right-hand
-side of the rule.  @xref{Locations, , Locations Overview}.
+In an action, the location of the @var{n}-th symbol of the right-hand side
+of the rule.  @xref{Tracking Locations}.
 @end deffn
 
 @deffn {Variable} @@@var{name}
-In an action, the location of a symbol addressed by name.
address@hidden, , Locations Overview}.
+In an action, the location of a symbol addressed by name.  @xref{Tracking
+Locations}.
 @end deffn
 
 @deffn {Variable} @@address@hidden
-In an action, the location of a symbol addressed by name.
address@hidden, , Locations Overview}.
+In an action, the location of a symbol addressed by name.  @xref{Tracking
+Locations}.
 @end deffn
 
 @deffn {Variable} $$
-- 
1.7.0.4


>From 8348436580ae3db8091f564e8b24d552a9d23590 Mon Sep 17 00:00:00 2001
From: Joel E. Denny <address@hidden>
Date: Sun, 29 May 2011 22:30:55 -0400
Subject: [PATCH 6/6] doc: clean up references to `Locations Overview'.

* doc/bison.texinfo (Locations Overview): Rename node to...
(Locations): ... this, which is its section name.  Update menus to
match that and not to use the title `Tracking Locations', which is
a different section.
---
 ChangeLog         |    8 ++++++++
 doc/bison.texinfo |    6 +++---
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 7d45fc8..8169127 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2011-05-29  Joel E. Denny  <address@hidden>
 
+       doc: clean up references to `Locations Overview'.
+       * doc/bison.texinfo (Locations Overview): Rename node to...
+       (Locations): ... this, which is its section name.  Update menus to
+       match that and not to use the title `Tracking Locations', which is
+       a different section.
+
+2011-05-29  Joel E. Denny  <address@hidden>
+
        doc: clean up references to `Tracking Locations'.
        * doc/bison.texinfo (Locations): Rename node to...
        (Tracking Locations): ... this, which is its section name, and
diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 509dbed..0a207f3 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -125,7 +125,7 @@ The Concepts of Bison
                            the name of an identifier, etc.).
 * Semantic Actions::     Each rule can have an action containing C code.
 * GLR Parsers::          Writing parsers for general context-free languages.
-* Locations Overview::   Tracking Locations.
+* Locations::            Overview of location tracking.
 * Bison Parser::         What are Bison's input and output,
                            how is the output used?
 * Stages::               Stages in writing and running Bison grammars.
@@ -449,7 +449,7 @@ use Bison or Yacc, we suggest you start by reading this 
chapter carefully.
                            the name of an identifier, etc.).
 * Semantic Actions::     Each rule can have an action containing C code.
 * GLR Parsers::          Writing parsers for general context-free languages.
-* Locations Overview::   Tracking Locations.
+* Locations::            Overview of location tracking.
 * Bison Parser::         What are Bison's input and output,
                            how is the output used?
 * Stages::               Stages in writing and running Bison grammars.
@@ -1205,7 +1205,7 @@ will suffice.  Otherwise, we suggest
 address@hidden
 @end example
 
address@hidden Locations Overview
address@hidden Locations
 @section Locations
 @cindex location
 @cindex textual location
-- 
1.7.0.4




reply via email to

[Prev in Thread] Current Thread [Next in Thread]