[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
minor documentation cleanup
From: |
Joel E. Denny |
Subject: |
minor documentation cleanup |
Date: |
Sat, 27 Jan 2007 18:34:18 -0500 (EST) |
I committed this.
Index: ChangeLog
===================================================================
RCS file: /sources/bison/bison/ChangeLog,v
retrieving revision 1.1672
diff -p -u -r1.1672 ChangeLog
--- ChangeLog 26 Jan 2007 23:11:59 -0000 1.1672
+++ ChangeLog 27 Jan 2007 23:30:56 -0000
@@ -1,3 +1,20 @@
+2007-01-27 Joel E. Denny <address@hidden>
+
+ * 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 <address@hidden>
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
address@hidden'. 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 <address@hidden>
@@ -1076,7 +1093,7 @@
%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.
@@ -1106,7 +1123,7 @@
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.
@@ -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 <address@hidden>
@@ -1832,7 +1849,7 @@
<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
@@ -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.
Index: doc/bison.texinfo
===================================================================
RCS file: /sources/bison/bison/doc/bison.texinfo,v
retrieving revision 1.223
diff -p -u -r1.223 bison.texinfo
--- doc/bison.texinfo 23 Jan 2007 12:24:27 -0000 1.223
+++ doc/bison.texinfo 27 Jan 2007 23:31:00 -0000
@@ -2695,7 +2695,7 @@ field, which identifies the purpose of t
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}.
address@hidden of Symbols,,Bison Symbols}.
address@hidden 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-red
In order to change the behavior of @command{bison}, use the following
directives:
address@hidden {Directive} %code @address@hidden@}
address@hidden %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.
+
address@hidden 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,
address@hidden@address@hidden@}}, for most purposes.
+For a detailed discussion, see @ref{Prologue Alternatives}.
+
address@hidden 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.)
address@hidden deffn
+
address@hidden {Directive} %code @var{qualifier} @address@hidden@}
+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.
+
address@hidden 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:
+
address@hidden @bullet
address@hidden %code requires
address@hidden requires
+
address@hidden @bullet
address@hidden Language(s): C, C++
+
address@hidden Purpose: This is the best place to write dependency code
required for
address@hidden 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.
+
address@hidden Location(s): The parser header file and the parser source code
file
+before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
address@hidden itemize
+
address@hidden provides
address@hidden %code provides
+
address@hidden @bullet
address@hidden Language(s): C, C++
+
address@hidden Purpose: This is the best place to write additional definitions
and
+declarations that should be provided to other modules.
+
address@hidden Location(s): The parser header file and the parser source code
file after
+the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
address@hidden itemize
+
address@hidden top
address@hidden %code top
+
address@hidden @bullet
address@hidden Language(s): C, C++
+
address@hidden 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:
+
address@hidden
+%code top @{
+ #define _GNU_SOURCE
+ #include <stdio.h>
address@hidden
address@hidden smallexample
+
address@hidden Location(s): Near the top of the parser source code file.
address@hidden itemize
address@hidden
address@hidden imports
address@hidden %code imports
+
address@hidden @bullet
address@hidden Language(s): Java
+
address@hidden Purpose: This is the best place to write Java import directives.
+
address@hidden Location(s): The parser Java file after any Java package
directive and
+before any class definitions.
address@hidden itemize
address@hidden ignore
address@hidden 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.)
+
address@hidden 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}.
address@hidden 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}.
address@hidden {Directive} %define @var{define-variable}
address@hidden {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.
address@hidden 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.
address@hidden of Symbols, ,%code}.
address@hidden deffn
-
address@hidden {Directive} %define @var{define-variable}
address@hidden {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.
address@hidden Summary, ,%code}.
@end deffn
@deffn {Directive} %defines @var{defines-file}
@@ -7903,7 +8011,7 @@ reciprocally, both cannot include the he
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.
address@hidden of Symbols, ,%code}.
address@hidden Summary, ,%code}.
@comment file: calc++-parser.yy
@example
@@ -8669,109 +8777,9 @@ Start-Symbol}. It cannot be used in the
@end deffn
@deffn {Directive} %code @address@hidden@}
address@hidden %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.
-
address@hidden 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,
address@hidden@address@hidden@}}, for most purposes.
-For a detailed discussion, see @ref{Prologue Alternatives}.
-
address@hidden 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.)
address@hidden deffn
-
address@hidden {Directive} %code @var{qualifier} @address@hidden@}
-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.
-
address@hidden 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:
-
address@hidden @bullet
address@hidden %code requires
address@hidden requires
-
address@hidden @bullet
address@hidden Language(s): C, C++
-
address@hidden Purpose: This is the best place to write dependency code
required for
address@hidden 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.
-
address@hidden Location(s): The parser header file and the parser source code
file
-before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
address@hidden itemize
-
address@hidden provides
address@hidden %code provides
-
address@hidden @bullet
address@hidden Language(s): C, C++
-
address@hidden Purpose: This is the best place to write additional definitions
and
-declarations that should be provided to other modules.
-
address@hidden Location(s): The parser header file and the parser source code
file after
-the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
address@hidden itemize
-
address@hidden top
address@hidden %code top
-
address@hidden @bullet
address@hidden Language(s): C, C++
-
address@hidden 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:
-
address@hidden
-%code top @{
- #define _GNU_SOURCE
- #include <stdio.h>
address@hidden
address@hidden smallexample
-
address@hidden Location(s): Near the top of the parser source code file.
address@hidden itemize
address@hidden
address@hidden imports
address@hidden %code imports
-
address@hidden @bullet
address@hidden Language(s): Java
-
address@hidden Purpose: This is the best place to write Java import directives.
-
address@hidden Location(s): The parser Java file after any Java package
directive and
-before any class definitions.
address@hidden itemize
address@hidden ignore
address@hidden 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.)
-
address@hidden 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}.
address@hidden {Directive} %code @var{qualifier} @address@hidden@}
+Insert @var{code} verbatim into output parser source.
address@hidden Summary,,%code}.
@end deffn
@deffn {Directive} %debug
@@ -8790,6 +8798,12 @@ Precedence}.
@end deffn
@end ifset
address@hidden {Directive} %define @var{define-variable}
address@hidden {Directive} %define @var{define-variable} @var{value}
+Define a variable to adjust Bison's behavior.
address@hidden Summary,,%define}.
address@hidden deffn
+
@deffn {Directive} %defines
Bison declaration to create a header file meant for the scanner.
@xref{Decl Summary}.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- minor documentation cleanup,
Joel E. Denny <=