* src/output.c (output_gram): Rely on nritems, not the

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index bf0f790b371cd38698d5802c67e3904ecfa1c8bb..4aca74cebcbd3f03e3156d5c5a46bb399d5dbebc 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -693,7 +693,7 @@ arrange for it to call @code{yyparse} or the parser will never run.
 @xref{Interface, ,Parser C-Language Interface}.
 
 Aside from the token type names and the symbols in the actions you
-write, all variable and function names used in the Bison parser file
+write, all symbols defined in the Bison parser file itself
 begin with @samp{yy} or @samp{YY}.  This includes interface functions
 such as the lexical analyzer function @code{yylex}, the error reporting
 function @code{yyerror} and the parser function @code{yyparse} itself.
@@ -702,6 +702,15 @@ Therefore, you should avoid using C identifiers starting with @samp{yy}
 or @samp{YY} in the Bison grammar file except for the ones defined in
 this manual.
 
+In some cases the Bison parser file includes system headers, and in
+those cases your code should respect the identifiers reserved by those
+headers.  On some non-@sc{gnu} hosts, @code{<alloca.h>},
+@code{<stddef.h>}, and @code{<stdlib.h>} are included as needed to
+declare memory allocators and related types.  In the same situation,
+C++ parsers may include @code{<cstddef>} and @code{<cstdlib>} instead.
+Other system headers may be included if you define @code{YYDEBUG} to a
+nonzero value (@pxref{Debugging, ,Debugging Your Parser}).
+
 @node Stages
 @section Stages in Using Bison
 @cindex stages in using Bison
@@ -3227,9 +3236,9 @@ directives:
 
 @table @code
 @item %debug
-Output a definition of the macro @code{YYDEBUG} into the parser file, so
-that the debugging facilities are compiled.  @xref{Debugging, ,Debugging
-Your Parser}.
+In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
+already defined, so that the debugging facilities are compiled.
+@xref{Debugging, ,Debugging Your Parser}.
 
 @item %defines
 Write an extra output file containing macro definitions for the token
@@ -4916,14 +4925,23 @@ If a Bison grammar compiles properly but doesn't do what you want when it
 runs, the @code{yydebug} parser-trace feature can help you figure out why.
 
 To enable compilation of trace facilities, you must define the macro
-@code{YYDEBUG} when you compile the parser.  You could use @samp{-DYYDEBUG=1}
-as a compiler option or you could put @samp{#define YYDEBUG 1} in the prologue
-of the grammar file (@pxref{Prologue, , The Prologue}). Alternatively, use the
-@samp{-t} option when you run Bison (@pxref{Invocation, ,Invoking Bison}).
-We always define @code{YYDEBUG} so that debugging is always possible.
-
-The trace facility uses @code{stderr}, so you must add
-@w{@code{#include <stdio.h>}} to the prologue unless it is already there.
+@code{YYDEBUG} to a nonzero value when you compile the parser.  You
+could use @samp{-DYYDEBUG=1} as a compiler option or you could put
+@samp{#define YYDEBUG 1} in the prologue of the grammar file
+(@pxref{Prologue, , The Prologue}).  Alternatively, use the @samp{-t}
+option when you run Bison (@pxref{Invocation, ,Invoking Bison}) or the
+@code{%debug} declaration (@pxref{Decl Summary, ,Bison Declaration
+Summary}).  We suggest that you always define @code{YYDEBUG} so that
+debugging is always possible.
+
+The trace facility outputs messages with macro calls of the form
+@code{YYFPRINTF (YYSTDERR, @var{format}, @var{args})} where
+@var{format} and @var{args} are the usual @code{printf} format and
+arguments.  If you define @code{YYDEBUG} to a nonzero value but do not
+define @code{YYFPRINTF}, @code{<stdio.h>} is automatically included
+and the macros are defined to @code{fprintf} and @code{stderr}.  In
+the same situation, C++ parsers include @code{<cstdio.h>} instead, and
+use @code{std::fprintf} and @code{std::stderr}.
 
 Once you have compiled the program with trace facilities, the way to
 request a trace is to store a nonzero value in the variable @code{yydebug}.
@@ -5002,7 +5020,7 @@ Here @var{infile} is the grammar file name, which usually ends in
 @samp{.y}.  The parser file's name is made by replacing the @samp{.y}
 with @samp{.tab.c}.  Thus, the @samp{bison foo.y} filename yields
 @file{foo.tab.c}, and the @samp{bison hack/foo.y} filename yields
-@file{hack/foo.tab.c}. It's is also possible, in case you are writting
+@file{hack/foo.tab.c}. It's is also possible, in case you are writing
 C++ code instead of C in your grammar file, to name it @file{foo.ypp}
 or @file{foo.y++}. Then, the output files will take an extention like
 the given one as input (repectively @file{foo.tab.cpp} and @file{foo.tab.c++}).
@@ -5084,9 +5102,9 @@ you are developing Bison.
 
 @item -t
 @itemx --debug
-Output a definition of the macro @code{YYDEBUG} into the parser file, so
-that the debugging facilities are compiled.  @xref{Debugging, ,Debugging
-Your Parser}.
+In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
+already defined, so that the debugging facilities are compiled.
+@xref{Debugging, ,Debugging Your Parser}.
 
 @item --locations
 Pretend that @code{%locations} was specified.  @xref{Decl Summary}.