-F/--force-define and relative %define/-D/--define priorities.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 744641a0a62ec87669a4fab901a33698ae832967..45a6075e9a0a7cd8d06f4c1855e026173e6a2800 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -4845,7 +4845,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.
+Bison will warn 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{""}.
@@ -8140,8 +8141,29 @@ 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 processes all command-line definitions in order and then processes
+all @code{%define} definitions in order.
+@item
+Later definitions override earlier definitions except that Bison quietly
+ignores all @code{%define} definitions if the last command-line
+definition is specified by @code{-F} or @code{--force-define}.
+@item
+Bison never warns when a command-line definition overrides another
+definition, but Bison always warns when a @code{%define} definition
+overrides a command-line or @code{%define} definition.
+@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}
@@ -8267,9 +8289,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