Future/bison
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/bison.git synced 2026-03-09 12:23:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: clean up new subsections in manual.

Browse Source 
* doc/bison.texinfo (%define Summary): Reword so it reads well as
a separate section.  For example, add an intro, and move most of
the text outside of the @deffn so it is not indented so far.
(%code Summary): Likewise.
(Table of Symbols): Reword %code entry to match the %code entry in
Decl Summary.
This commit is contained in:
Joel E. Denny
2011-02-06 14:18:01 -05:00
parent 2f4518a126
commit 406dec8286
2 changed files with 68 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
ChangeLog
View File

@@ -1,3 +1,13 @@
2011-02-06 Joel E. Denny <joeldenny@joeldenny.org>
doc: clean up new subsections in manual.
* doc/bison.texinfo (%define Summary): Reword so it reads well as
a separate section. For example, add an intro, and move most of
the text outside of the @deffn so it is not indented so far.
(%code Summary): Likewise.
(Table of Symbols): Reword %code entry to match the %code entry in
Decl Summary.
2011-02-06 Joel E. Denny <joeldenny@joeldenny.org> 2011-02-06 Joel E. Denny <joeldenny@joeldenny.org>
doc: finish splitting apart the manual's Decl Summary section. doc: finish splitting apart the manual's Decl Summary section.

94
doc/bison.texinfo
View File

@@ -5066,23 +5066,35 @@ including its naming conventions. @xref{Bison Options}, for more.
@node %define Summary @node %define Summary
@subsection %define Summary @subsection %define Summary
There are many features of Bison's behavior that can be controlled by
assigning the feature a single value. For historical reasons, some
such features are assigned values by dedicated directives, such as
@code{%start}, which assigns the start symbol. However, newer such
features are associated with variables, which are assigned by the
@code{%define} directive:
@deffn {Directive} %define @var{variable} @deffn {Directive} %define @var{variable}
@deffnx {Directive} %define @var{variable} @var{value} @deffnx {Directive} %define @var{variable} @var{value}
@deffnx {Directive} %define @var{variable} "@var{value}" @deffnx {Directive} %define @var{variable} "@var{value}"
Define a variable to adjust Bison's behavior. Define @var{variable} to @var{value}.
It is an error if a @var{variable} is defined by @code{%define} multiple @var{value} must be placed in quotation marks if it contains any
times, but see @ref{Bison Options,,-D @var{name}[=@var{value}]}. character other than a letter, underscore, period, or non-initial dash
or digit. Omitting @code{"@var{value}"} entirely is always equivalent
to specifying @code{""}.
@var{value} must be placed in quotation marks if it contains any character It is an error if a @var{variable} is defined by @code{%define}
other than a letter, underscore, period, or non-initial dash or digit. multiple times, but see @ref{Bison Options,,-D
@var{name}[=@var{value}]}.
@end deffn
Omitting @code{"@var{value}"} entirely is always equivalent to specifying The rest of this section summarizes variables and values that
@code{""}. @code{%define} accepts.
Some @var{variable}s take Boolean values. Some @var{variable}s take Boolean values. In this case, Bison will
In this case, Bison will complain if the variable definition does not meet one complain if the variable definition does not meet one of the following
of the following four conditions: four conditions:
@enumerate @enumerate
@item @code{@var{value}} is @code{true} @item @code{@var{value}} is @code{true}
@@ -5474,40 +5486,49 @@ insignificant for practical grammars.
@end itemize @end itemize
@end itemize @end itemize
@end deffn
@node %code Summary @node %code Summary
@subsection %code Summary @subsection %code Summary
@deffn {Directive} %code @{@var{code}@}
@findex %code @findex %code
This is the unqualified form of the @code{%code} directive.
It inserts @var{code} verbatim at a language-dependent default location in the
output@footnote{The default location is actually skeleton-dependent;
writers of non-standard skeletons however should choose the default location
consistently with the behavior of the standard Bison skeletons.}.
@cindex Prologue @cindex Prologue
The @code{%code} directive inserts code verbatim into the output
parser source at any of a predefined set of locations. It thus serves
as a flexible and user-friendly alternative to the traditional Yacc
prologue, @code{%@{@var{code}%@}}. This section summarizes the
functionality of @code{%code} for the various target languages
supported by Bison. For a detailed discussion of how to use
@code{%code} in place of @code{%@{@var{code}%@}} for C/C++ and why it
is advantageous to do so, @pxref{Prologue Alternatives}.
@deffn {Directive} %code @{@var{code}@}
This is the unqualified form of the @code{%code} directive. It
inserts @var{code} verbatim at a language-dependent default location
in the parser implementation.
For C/C++, the default location is the parser implementation file For C/C++, the default location is the parser implementation file
after the usual contents of the parser header file. Thus, after the usual contents of the parser header file. Thus, the
@code{%code} replaces the traditional Yacc prologue, unqualified form replaces @code{%@{@var{code}%@}} for most purposes.
@code{%@{@var{code}%@}}, for most purposes. For a detailed
discussion, see @ref{Prologue Alternatives}.
For Java, the default location is inside the parser class. For Java, the default location is inside the parser class.
@end deffn @end deffn
@deffn {Directive} %code @var{qualifier} @{@var{code}@} @deffn {Directive} %code @var{qualifier} @{@var{code}@}
This is the qualified form of the @code{%code} directive. This is the qualified form of the @code{%code} directive.
If you need to specify location-sensitive verbatim @var{code} that does not @var{qualifier} identifies the purpose of @var{code} and thus the
belong at the default location selected by the unqualified @code{%code} form, location(s) where Bison should insert it. That is, if you need to
use this form instead. specify location-sensitive @var{code} that does not belong at the
default location selected by the unqualified @code{%code} form, use
this form instead.
@end deffn
@var{qualifier} identifies the purpose of @var{code} and thus the location(s) For any particular qualifier or for the unqualified form, if there are
where Bison should generate it. multiple occurrences of the @code{%code} directive, Bison concatenates
Not all @var{qualifier}s are accepted for all target languages. the specified code in the order in which it appears in the grammar
Unaccepted @var{qualifier}s produce an error. file.
Some of the accepted @var{qualifier}s are:
Not all qualifiers are accepted for all target languages. Unaccepted
qualifiers produce an error. Some of the accepted qualifiers are:
@itemize @bullet @itemize @bullet
@item requires @item requires
@@ -5575,10 +5596,10 @@ before any class definitions.
@end itemize @end itemize
@end itemize @end itemize
@cindex Prologue Though we say the insertion locations are language-dependent, they are
For a detailed discussion of how to use @code{%code} in place of the technically skeleton-dependent. Writers of non-standard skeletons
traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}. however should choose their locations consistently with the behavior
@end deffn of the standard Bison skeletons.
@node Multiple Parsers @node Multiple Parsers
@@ -10236,7 +10257,8 @@ Start-Symbol}. It cannot be used in the grammar.
@deffn {Directive} %code @{@var{code}@} @deffn {Directive} %code @{@var{code}@}
@deffnx {Directive} %code @var{qualifier} @{@var{code}@} @deffnx {Directive} %code @var{qualifier} @{@var{code}@}
Insert @var{code} verbatim into output parser source. Insert @var{code} verbatim into the output parser source at the
default location or at the location specified by @var{qualifier}.
@xref{%code Summary}. @xref{%code Summary}.
@end deffn @end deffn