+2007-01-27 Joel E. Denny <jdenny@ces.clemson.edu>
+
+ * ChangeLog: For changes in doc/bison.texinfo, consistently reference
+ node names: say "Table of Symbols" not "Bison Symbols", and say "Decl
+ Summary" not "Directives".
+ * doc/bison.texinfo (Decl Summary, Calc++ Parser): Cross-reference the
+ %code entry in "Decl Summary" rather than the one in "Table of Symbols"
+ since the former is now the more complete one.
+ (Prologue Alternatives): Likewise and do the same for %defines.
+ (Table of Symbols): Add summary of %code, add summary of %define, and
+ move full %code documentation to...
+ (Decl Summary): ... here for consistency with other entries in these
+ sections.
+ Move %define entry in order to keep this list alphabetized.
+ Reword %define entry a little to put less emphasis on the skeleton
+ concept, which most users shouldn't have to think about.
+
2007-01-26 Paul Eggert <eggert@cs.ucla.edu>
Adjust to recent gnulib changes.
* data/glr.cc: Likewise.
* data/location.cc: Use b4_percent_define_flag_if.
- * doc/bison.texinfo (Directives): Document %define.
+ * doc/bison.texinfo (Decl Summary): Document %define.
* src/parse-gram.y (Unqualified %code): Change muscle name to
b4_percent_code().
(C++ Location Values): Update %define uses.
(Calc++ Parser Interface): Likewise.
(Calc++ Parser): Likewise, and update `%code requires' uses.
- (Bison Symbols): Update %code documentation.
+ (Table of Symbols): Update %code documentation.
* src/parse-gram.y (prologue_declaration): For %define variables, use
`variable' instead of `STRING'.
(grammar_declaration): For %code qualifiers, use `ID' instead of
* doc/bison.texinfo (Prologue Alternatives): Update.
(Decl Summary): Update to %code "requires" and %code "provides".
(Calc++ Parser): Update to %code "requires".
- (Bison Symbols): Remove entries for %requires, %provides, and
+ (Table of Symbols): Remove entries for %requires, %provides, and
%code-top. Rewrite %code entry, and add a %code "QUALIFIER" entry.
* data/bison.m4 (b4_user_provides, b4_user_requires): Remove as these
are replaced by b4_percent_code_provides and b4_percent_code_requires,
documentation instead.
(Calc++ Parser): Use `%require "@value{VERSION}"' rather than
`%require "2.3b"' so that the example is always up-to-date.
- (Bison Symbols): Add entries for %language and %skeleton.
+ (Table of Symbols): Add entries for %language and %skeleton.
* examples/extexi (normalize): Instead of replacing every %require
argument with the current Bison version, just substitute for
`@value{VERSION}'. This guarantees that we're testing what actually
* doc/bison.texinfo (C++ Parser Interface): Prefer %language
over %skeleton.
- (Directives): Document %language and %skeleton.
+ (Decl Summary): Document %language and %skeleton.
(Command line): Document -L.
* examples/extexi: Rewrite %require directive.
(2.3a): Annotate this entry to say the old forms of these features were
also experimental.
* doc/bison.texinfo (Prologue Alternatives, Freeing Discarded Symbols,
- Bison Symbols): Say they're experimental. Comment out any mention
+ Table of Symbols): Say they're experimental. Comment out any mention
of Java (we'll want this back eventually).
2006-12-01 Joel E. Denny <jdenny@ces.clemson.edu>
%file-prefix, %name-prefix, and %output. Discussed at
<http://lists.gnu.org/archive/html/help-bison/2006-09/msg00001.html>.
* NEWS (2.3a+): Mention.
- * doc/bison.texinfo (Decl Summary, Bison Symbols): Add entry for new
+ * doc/bison.texinfo (Decl Summary, Table of Symbols): Add entry for new
form of %defines, and remove `=' from entries for %file-prefix,
%name-prefix, and %output.
* src/parse-gram.y (prologue_declaration): Implement.
Rename <!> to <>. Discussed starting at
<http://lists.gnu.org/archive/html/bison-patches/2006-11/msg00039.html>.
* NEWS (2.3a+): Update.
- * doc/bison.texinfo (Freeing Discarded Symbols, Bison Symbols):
+ * doc/bison.texinfo (Freeing Discarded Symbols, Table of Symbols):
Update.
* src/parse-gram.y (TYPE_TAG_NONE, generic_symlist_item): Implement.
* src/scan-gram.l (INITIAL): Implement.
* NEWS (2.3a+): Mention.
* doc/bison.texinfo (Freeing Discarded Symbols): Document this and the
previous change today related to mid-rules.
- (Bison Symbols): Remove %symbol-default and add <*> and <!>.
+ (Table of Symbols): Remove %symbol-default and add <*> and <!>.
* src/parse-gram.y (PERCENT_SYMBOL_DEFAULT): Remove.
(TYPE_TAG_ANY): Add as <*>.
(TYPE_TAG_NONE): Add as <!>.
alternatives to...
(Prologue Alternatives): ... this new section, and extend it to discuss
all 4 directives in detail.
- (Bison Symbols): Clean up discussion of prologue alternatives and add
- %code-top.
+ (Table of Symbols): Clean up discussion of prologue alternatives and
+ add %code-top.
2006-10-16 Juan Manuel Guerrero <juan.guerrero@gmx.de>
<http://lists.gnu.org/archive/html/bison-patches/2006-09/msg00007.html>.
* NEWS (2.3+): Add %symbol-default to example.
* bison.texinfo (Freeing Discarded Symbols): Likewise.
- (Bison Symbols): Add entry for %symbol-default.
+ (Table of Symbols): Add entry for %symbol-default.
* src/parse-gram.y (PERCENT_SYMBOL_DEFAULT): New token.
(generic_symlist, generic_symlist_item): New nonterminals for creating
a list in which each item is a symbol, semantic type, or
prologue blocks with %*-header declarations.
(Calc++ Parser): Likewise.
(Bison Declaration Summary): Update names.
- (Bison Symbols): Update description.
+ (Table of Symbols): Update description.
* src/parse-gram.y (PERCENT_AFTER_DEFINITIONS): Update to...
(PERCENT_END_HEADER): ... this.
(PERCENT_BEFORE_DEFINITIONS): Update to...
file.
(Calc++ Parser): Forward declare driver in a %before-definitions rather
than in the pre-prologue so that make check succeeds.
- (Bison Symbols): Add entries for %before-definitions and
+ (Table of Symbols): Add entries for %before-definitions and
%after-definitions.
* src/parse-gram.y (PERCENT_BEFORE_DEFINITIONS): New token for
%before-definitions.
in the yychar entry.
In the yychar entry, remove mention of the local yychar case (pure
parser) since this is irrelevant information when writing semantic
- actions and since it's already discussed in `Bison Symbols' where
+ actions and since it's already discussed in `Table of Symbols' where
yychar is otherwise described as an external variable.
In the yychar entry, don't call it the `current' look-ahead since it
isn't when semantic actions are deferred.
`current' look-ahead, and do mention yylval and yylloc.
(Error Recovery): Cross-reference `Action Features' when mentioning
yyclearin.
- (Bison Symbols): In the yychar entry, don't call it the `current'
+ (Table of Symbols): In the yychar entry, don't call it the `current'
look-ahead.
In the yylloc and yylval entries, mention look-ahead usage.
Bison should generate it.
For C/C++, the qualifier can be omitted for the default location, or it can be
@code{requires}, @code{provides}, or @code{top}.
-@xref{Table of Symbols,,Bison Symbols}.
+@xref{Decl Summary,,%code}.
Look again at the example of the previous section:
The first line after the warning is required by @code{YYSTYPE} and thus also
needs to appear in the parser source code file.
However, if you've instructed Bison to generate a parser header file
-(@pxref{Table of Symbols, ,%defines}), you probably want that line to appear
-before the @code{YYSTYPE} definition in that header file as well.
+(@pxref{Decl Summary, ,%defines}), you probably want that line to appear before
+the @code{YYSTYPE} definition in that header file as well.
The @code{YYLTYPE} definition should also appear in the parser header file to
override the default @code{YYLTYPE} definition there.
In order to change the behavior of @command{bison}, use the following
directives:
+@deffn {Directive} %code @{@var{code}@}
+@findex %code
+This is the unqualified form of the @code{%code} directive.
+It inserts @var{code} verbatim at the default location in the output.
+That default location is determined by the selected target language and/or
+parser skeleton.
+
+@cindex Prologue
+For the current C/C++ skeletons, the default location is the parser source code
+file after the usual contents of the parser header file.
+Thus, @code{%code} replaces the traditional Yacc prologue,
+@code{%@{@var{code}%@}}, for most purposes.
+For a detailed discussion, see @ref{Prologue Alternatives}.
+
+@comment For Java, the default location is inside the parser class.
+
+(Like all the Yacc prologue alternatives, this directive is experimental.
+More user feedback will help to determine whether it should become a permanent
+feature.)
+@end deffn
+
+@deffn {Directive} %code @var{qualifier} @{@var{code}@}
+This is the qualified form of the @code{%code} directive.
+If you need to specify location-sensitive verbatim @var{code} that does not
+belong at the default location selected by the unqualified @code{%code} form,
+use this form instead.
+
+@var{qualifier} identifies the purpose of @var{code} and thus the location(s)
+where Bison should generate it.
+Not all values of @var{qualifier} are available for all target languages:
+
+@itemize @bullet
+@findex %code requires
+@item requires
+
+@itemize @bullet
+@item Language(s): C, C++
+
+@item Purpose: This is the best place to write dependency code required for
+@code{YYSTYPE} and @code{YYLTYPE}.
+In other words, it's the best place to define types referenced in @code{%union}
+directives, and it's the best place to override Bison's default @code{YYSTYPE}
+and @code{YYLTYPE} definitions.
+
+@item Location(s): The parser header file and the parser source code file
+before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
+@end itemize
+
+@item provides
+@findex %code provides
+
+@itemize @bullet
+@item Language(s): C, C++
+
+@item Purpose: This is the best place to write additional definitions and
+declarations that should be provided to other modules.
+
+@item Location(s): The parser header file and the parser source code file after
+the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
+@end itemize
+
+@item top
+@findex %code top
+
+@itemize @bullet
+@item Language(s): C, C++
+
+@item Purpose: The unqualified @code{%code} or @code{%code requires} should
+usually be more appropriate than @code{%code top}.
+However, occasionally it is necessary to insert code much nearer the top of the
+parser source code file.
+For example:
+
+@smallexample
+%code top @{
+ #define _GNU_SOURCE
+ #include <stdio.h>
+@}
+@end smallexample
+
+@item Location(s): Near the top of the parser source code file.
+@end itemize
+@ignore
+@item imports
+@findex %code imports
+
+@itemize @bullet
+@item Language(s): Java
+
+@item Purpose: This is the best place to write Java import directives.
+
+@item Location(s): The parser Java file after any Java package directive and
+before any class definitions.
+@end itemize
+@end ignore
+@end itemize
+
+(Like all the Yacc prologue alternatives, this directive is experimental.
+More user feedback will help to determine whether it should become a permanent
+feature.)
+
+@cindex Prologue
+For a detailed discussion of how to use @code{%code} in place of the
+traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
+@end deffn
+
@deffn {Directive} %debug
In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
already defined, so that the debugging facilities are compiled.
@end deffn
@xref{Tracing, ,Tracing Your Parser}.
+@deffn {Directive} %define @var{define-variable}
+@deffnx {Directive} %define @var{define-variable} @var{value}
+Define a variable to adjust Bison's behavior.
+The list of available variables and their meanings depends on the selected
+target language and/or the parser skeleton (@pxref{Decl Summary,,%language}).
+The @var{value} can be omitted for boolean variables; for
+boolean variables, the skeletons will treat a @var{value} of @samp{0}
+or @samp{false} as the boolean variable being false, and anything else
+as true.
+@end deffn
+
@deffn {Directive} %defines
Write a header file containing macro definitions for the token type
names defined in the grammar as well as a few other declarations.
@findex %code provides
If you have declared @code{%code requires} or @code{%code provides}, the output
header also contains their code.
-@xref{Table of Symbols, ,%code}.
-@end deffn
-
-@deffn {Directive} %define @var{define-variable}
-@deffnx {Directive} %define @var{define-variable} @var{value}
-Define a variable to be used by the skeleton in order to adjust its
-behavior. The @var{value} can be omitted for boolean variables; for
-boolean variables, the skeletons will treat a @var{value} of @samp{0}
-or @samp{false} as the boolean variable being false, and anything else
-as true.
+@xref{Decl Summary, ,%code}.
@end deffn
@deffn {Directive} %defines @var{defines-file}
driver's header needs detailed knowledge about the parser class (in
particular its inner types), it is the parser's header which will simply
use a forward declaration of the driver.
-@xref{Table of Symbols, ,%code}.
+@xref{Decl Summary, ,%code}.
@comment file: calc++-parser.yy
@example
@end deffn
@deffn {Directive} %code @{@var{code}@}
-@findex %code
-This is the unqualified form of the @code{%code} directive.
-It inserts @var{code} verbatim at the default location in the output.
-That default location is determined by the selected target language and/or
-parser skeleton.
-
-@cindex Prologue
-For the current C/C++ skeletons, the default location is the parser source code
-file after the usual contents of the parser header file.
-Thus, @code{%code} replaces the traditional Yacc prologue,
-@code{%@{@var{code}%@}}, for most purposes.
-For a detailed discussion, see @ref{Prologue Alternatives}.
-
-@comment For Java, the default location is inside the parser class.
-
-(Like all the Yacc prologue alternatives, this directive is experimental.
-More user feedback will help to determine whether it should become a permanent
-feature.)
-@end deffn
-
-@deffn {Directive} %code @var{qualifier} @{@var{code}@}
-This is the qualified form of the @code{%code} directive.
-If you need to specify location-sensitive verbatim @var{code} that does not
-belong at the default location selected by the unqualified @code{%code} form,
-use this form instead.
-
-@var{qualifier} identifies the purpose of @var{code} and thus the location(s)
-where Bison should generate it.
-Not all values of @var{qualifier} are available for all target languages:
-
-@itemize @bullet
-@findex %code requires
-@item requires
-
-@itemize @bullet
-@item Language(s): C, C++
-
-@item Purpose: This is the best place to write dependency code required for
-@code{YYSTYPE} and @code{YYLTYPE}.
-In other words, it's the best place to define types referenced in @code{%union}
-directives, and it's the best place to override Bison's default @code{YYSTYPE}
-and @code{YYLTYPE} definitions.
-
-@item Location(s): The parser header file and the parser source code file
-before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
-@end itemize
-
-@item provides
-@findex %code provides
-
-@itemize @bullet
-@item Language(s): C, C++
-
-@item Purpose: This is the best place to write additional definitions and
-declarations that should be provided to other modules.
-
-@item Location(s): The parser header file and the parser source code file after
-the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
-@end itemize
-
-@item top
-@findex %code top
-
-@itemize @bullet
-@item Language(s): C, C++
-
-@item Purpose: The unqualified @code{%code} or @code{%code requires} should
-usually be more appropriate than @code{%code top}.
-However, occasionally it is necessary to insert code much nearer the top of the
-parser source code file.
-For example:
-
-@smallexample
-%code top @{
- #define _GNU_SOURCE
- #include <stdio.h>
-@}
-@end smallexample
-
-@item Location(s): Near the top of the parser source code file.
-@end itemize
-@ignore
-@item imports
-@findex %code imports
-
-@itemize @bullet
-@item Language(s): Java
-
-@item Purpose: This is the best place to write Java import directives.
-
-@item Location(s): The parser Java file after any Java package directive and
-before any class definitions.
-@end itemize
-@end ignore
-@end itemize
-
-(Like all the Yacc prologue alternatives, this directive is experimental.
-More user feedback will help to determine whether it should become a permanent
-feature.)
-
-@cindex Prologue
-For a detailed discussion of how to use @code{%code} in place of the
-traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
+@deffnx {Directive} %code @var{qualifier} @{@var{code}@}
+Insert @var{code} verbatim into output parser source.
+@xref{Decl Summary,,%code}.
@end deffn
@deffn {Directive} %debug
@end deffn
@end ifset
+@deffn {Directive} %define @var{define-variable}
+@deffnx {Directive} %define @var{define-variable} @var{value}
+Define a variable to adjust Bison's behavior.
+@xref{Decl Summary,,%define}.
+@end deffn
+
@deffn {Directive} %defines
Bison declaration to create a header file meant for the scanner.
@xref{Decl Summary}.
projects / bison.git / commitdiff
