From 148d66d8612b5e382495f43d672fbdeeee1d3802 Mon Sep 17 00:00:00 2001 From: "Joel E. Denny" Date: Sat, 27 Jan 2007 23:34:16 +0000 Subject: [PATCH 1/1] * 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. --- ChangeLog | 49 ++++++--- doc/bison.texinfo | 248 ++++++++++++++++++++++++---------------------- 2 files changed, 164 insertions(+), 133 deletions(-) diff --git a/ChangeLog b/ChangeLog index 15041486..3abe74cc 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,20 @@ +2007-01-27 Joel E. Denny + + * 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 Adjust to recent gnulib changes. @@ -18,7 +35,7 @@ * 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(). @@ -200,7 +217,7 @@ (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 @@ -418,7 +435,7 @@ * 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, @@ -831,7 +848,7 @@ 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 @@ -866,7 +883,7 @@ * 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. @@ -1067,7 +1084,7 @@ (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 @@ -1076,7 +1093,7 @@ %file-prefix, %name-prefix, and %output. Discussed at . * 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. @@ -1106,7 +1123,7 @@ Rename to <>. Discussed starting at . * 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. @@ -1282,7 +1299,7 @@ * 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 . @@ -1375,8 +1392,8 @@ 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 @@ -1832,7 +1849,7 @@ . * 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 @@ -2474,7 +2491,7 @@ 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... @@ -2555,7 +2572,7 @@ 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. @@ -3645,7 +3662,7 @@ 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. @@ -3656,7 +3673,7 @@ `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. diff --git a/doc/bison.texinfo b/doc/bison.texinfo index c6c36607..38888287 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -2695,7 +2695,7 @@ field, which identifies the purpose of the code and thus the location(s) where 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: @@ -2793,8 +2793,8 @@ parser source code file. 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. @@ -4569,12 +4569,129 @@ Declare the expected number of shift-reduce conflicts 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 +@} +@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. @@ -4612,16 +4729,7 @@ Tokens}. @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} @@ -7903,7 +8011,7 @@ reciprocally, both cannot include the header of the other. Because the 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 @@ -8669,109 +8777,9 @@ Start-Symbol}. It cannot be used in the grammar. @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 -@} -@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 @@ -8790,6 +8798,12 @@ Precedence}. @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}. -- 2.45.2