Convert multiple variable definition warnings to complaints.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index a02d07607b655bd85da5d75820fd457804cccc01..3c63a19a9666f2e1cc5226a92b7af2f10a9e27f5 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -3048,8 +3048,8 @@ A @dfn{nonterminal symbol} stands for a class of syntactically
 equivalent groupings.  The symbol name is used in writing grammar rules.
 By convention, it should be all lower case.
 
-Symbol names can contain letters, underscores, period, and (not at the
-beginning) digits and dashes.  Dashes in symbol names are a GNU
+Symbol names can contain letters, underscores, periods, dashes, and (not
+at the beginning) digits.  Dashes in symbol names are a GNU
 extension, incompatible with @acronym{POSIX} Yacc.  Terminal symbols
 that contain periods or dashes make little sense: since they are not
 valid symbols (in most programming languages) they are not exported as
@@ -4837,7 +4837,8 @@ The possible choices for @var{variable}, as well as their meanings, depend on
 the selected target language and/or the parser skeleton (@pxref{Decl
 Summary,,%language}, @pxref{Decl Summary,,%skeleton}).
 
-Bison will warn if a @var{variable} is defined multiple times.
+It is an error if a @var{variable} is defined by @code{%define} multiple
+times, but @ref{Bison Options,,-D @var{name}[=@var{value}]}.
 
 Omitting @code{"@var{value}"} is always equivalent to specifying it as
 @code{""}.
@@ -7982,8 +7983,32 @@ already defined, so that the debugging facilities are compiled.
 
 @item -D @var{name}[=@var{value}]
 @itemx --define=@var{name}[=@var{value}]
-Same as running @samp{%define @var{name} "@var{value}"} (@pxref{Decl
-Summary, ,%define}).
+@item -F @var{name}[=@var{value}]
+@itemx --force-define=@var{name}[=@var{value}]
+Each of these is equivalent to @samp{%define @var{name} "@var{value}"}
+(@pxref{Decl Summary, ,%define}) except that Bison processes multiple
+definitions for the same @var{name} as follows:
+
+@itemize
+@item
+Bison quietly ignores all command-line definitions for @var{name} except
+the last.
+@item
+If that command-line definition is specified by a @code{-D} or
+@code{--define}, Bison reports an error for any @code{%define}
+definition for @var{name}.
+@item
+If that command-line definition is specified by a @code{-F} or
+@code{--force-define} instead, Bison quietly ignores all @code{%define}
+definitions for @var{name}.
+@item
+Otherwise, Bison reports an error if there are multiple @code{%define}
+definitions for @var{name}.
+@end itemize
+
+You should avoid using @code{-F} and @code{--force-define} in your
+makefiles unless you are confident that it is safe to quietly ignore any
+conflicting @code{%define} that may be added to the grammar file.
 
 @item -L @var{language}
 @itemx --language=@var{language}
@@ -8109,9 +8134,9 @@ More user feedback will help to stabilize it.)
 @section Option Cross Key
 
 Here is a list of options, alphabetized by long option, to help you find
-the corresponding short option.
+the corresponding short option and directive.
 
-@multitable {@option{--defines=@var{defines-file}}} {@option{-D @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
+@multitable {@option{--force-define=@var{name}[=@var{value}]}} {@option{-F @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
 @headitem Long Option @tab Short Option @tab Bison Directive
 @include cross-options.texi
 @end multitable
@@ -8735,8 +8760,8 @@ parser's to get the set of defined tokens.
 @example
 %@{                                            /* -*- C++ -*- */
 # include <cstdlib>
-# include <errno.h>
-# include <limits.h>
+# include <cerrno>
+# include <climits>
 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"
@@ -9008,7 +9033,7 @@ The first, inclusive, position of the range, and the first beyond.
 @end deftypeivar
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{loc})
-Create a @code{Location} denoting an empty range located at a given point. 
+Create a @code{Location} denoting an empty range located at a given point.
 @end deftypeop
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})
@@ -9222,12 +9247,12 @@ Return immediately from the parser, indicating success.
 @end deffn
 
 @deffn {Statement} {return YYERROR;}
-Start error recovery without printing an error message. 
+Start error recovery without printing an error message.
 @xref{Error Recovery}.
 @end deffn
 
 @deffn {Statement} {return YYFAIL;}
-Print an error message and start error recovery. 
+Print an error message and start error recovery.
 @xref{Error Recovery}.
 @end deffn