[PATCH 08/12] doc: introduce %empty and -Wempty-rule

[Akim Demaille]

* doc/bison.texi (Grammar Rules): Make it a @section which
contains...
(Rules Syntax): this new subsection (with the previous contents of
"Grammar Rules".
(Empty Rules): New subsection, extracted from the former
"Grammar Rules".
Document %empty.
(Recursion): New a subsection of "Grammar Rules".
Complete a few index entries.
(Bison Options): Document -Wempty-rule.
---
 NEWS           | 22 +++++++++++++++
 doc/bison.texi | 86 +++++++++++++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 92 insertions(+), 16 deletions(-)

diff --git a/NEWS b/NEWS
index 9489c51..564b087 100644
--- a/NEWS
+++ b/NEWS
@@ -362,6 +362,28 @@ GNU Bison NEWS
      %nonassoc '='
                ^^^
 
+** Empty rules
+
+  Empty rules (i.e., with an empty right-hand side) can now be explicitly
+  marked by the new %empty directive.  Using %empty on a non-empty rule is
+  an error.  The new -Wempty-rule warning reports empty rules without
+  %empty.  On the following grammar:
+
+    %%
+    s: a b c;
+    a: ;
+    b: %empty;
+    c: 'a' %empty;
+
+  bison reports:
+
+    3.4-5: warning: empty rule without %empty [-Wempty-rule]
+     a: {}
+        ^^
+    5.8-13: error: %empty on non-empty rule
+     c: 'a' %empty {};
+            ^^^^^^
+
 ** Java skeleton improvements
 
   Contributed by Paolo Bonzini.
diff --git a/doc/bison.texi b/doc/bison.texi
index 39e84e7..cbae43e 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -186,7 +186,6 @@ Bison Grammar Files
 * Grammar Outline::    Overall layout of the grammar file.
 * Symbols::            Terminal and nonterminal symbols.
 * Rules::              How to write grammar rules.
-* Recursion::          Writing recursive rules.
 * Semantics::          Semantic values and actions.
 * Tracking Locations:: Locations and actions.
 * Named References::   Using named references in actions.
@@ -201,6 +200,13 @@ Outline of a Bison Grammar
 * Grammar Rules::         Syntax and usage of the grammar rules section.
 * Epilogue::              Syntax and usage of the epilogue.
 
+Grammar Rules
+
+* Rules Syntax::   Syntax of the rules.
+* Empty Rules::    Symbols that can match the empty string.
+* Recursion::      Writing recursive rules.
+
+
 Defining Language Semantics
 
 * Value Type::        Specifying one data type for all semantic values.
@@ -2789,7 +2795,6 @@ The Bison grammar file conventionally has a name ending 
in @samp{.y}.
 * Grammar Outline::    Overall layout of the grammar file.
 * Symbols::            Terminal and nonterminal symbols.
 * Rules::              How to write grammar rules.
-* Recursion::          Writing recursive rules.
 * Semantics::          Semantic values and actions.
 * Tracking Locations:: Locations and actions.
 * Named References::   Using named references in actions.
@@ -3407,7 +3412,18 @@ value of the error token is 256, unless you explicitly 
assigned 256 to
 one of your tokens with a @code{%token} declaration.
 
 @node Rules
address@hidden Syntax of Grammar Rules
address@hidden Grammar Rules
+
+A Bison grammar is a list of rules.
+
address@hidden
+* Rules Syntax::   Syntax of the rules.
+* Empty Rules::    Symbols that can match the empty string.
+* Recursion::      Writing recursive rules.
address@hidden menu
+
address@hidden Rules Syntax
address@hidden Syntax of Grammar Rules
 @cindex rule syntax
 @cindex grammar rule syntax
 @cindex syntax of grammar rules
@@ -3481,33 +3497,57 @@ be joined with the vertical-bar character @samp{|} as 
follows:
 @noindent
 They are still considered distinct rules even when joined in this way.
 
-If @var{components} in a rule is empty, it means that @var{result} can
-match the empty string.  For example, here is how to define a
-comma-separated sequence of zero or more @code{exp} groupings:
address@hidden Empty Rules
address@hidden Empty Rules
address@hidden empty rule
address@hidden rule, empty
address@hidden %empty
+
+A rule is said to be @dfn{empty} if its right-hand side (@var{components})
+is empty.  It means that @var{result} can match the empty string.  For
+example, here is how to define an optional semicolon:
+
address@hidden
+semicolon.opt: | ";";
address@hidden example
+
address@hidden
+It is easy not to see an empty rule, especially when @code{|} is used.  The
address@hidden directive allows to make explicit that a rule is empty on
+purpose:
 
 @example
 @group
-expseq:
-  /* empty */
-| expseq1
+semicolon.opt:
+  %empty
+| ";"
 ;
 @end group
address@hidden example
 
+Flagging a non-empty rule with @code{%empty} is an error.  If run with
address@hidden, @command{bison} will report empty rules without
address@hidden  Using @code{%empty} enables this warning, unless
address@hidden was specified.
+
+The @code{%empty} directive is a Bison extension, it does not work with
+Yacc.  To remain compatible with POSIX Yacc, it is customary to write a
+comment @samp{/* empty */} in each rule with no components:
+
address@hidden
 @group
-expseq1:
-  exp
-| expseq1 ',' exp
+semicolon.opt:
+  /* empty */
+| ";"
 ;
 @end group
 @end example
 
address@hidden
-It is customary to write a comment @samp{/* empty */} in each rule
-with no components.
 
 @node Recursion
address@hidden Recursive Rules
address@hidden Recursive Rules
 @cindex recursive rule
address@hidden rule, recursive
 
 A rule is called @dfn{recursive} when its @var{result} nonterminal
 appears also on its right hand side.  Nearly all Bison grammars need to
@@ -3934,16 +3974,20 @@ declare a destructor for that symbol:
 @group
 %type <context> let
 %destructor @{ pop_context ($$); @} let
address@hidden group
 
 %%
 
address@hidden
 stmt:
   let stmt
     @{
       $$ = $2;
       pop_context ($let);
     @};
address@hidden group
 
address@hidden
 let:
   "let" '(' var ')'
     @{
@@ -9734,6 +9778,11 @@ no effect on the conflict report.
 Deprecated constructs whose support will be removed in future versions of
 Bison.
 
address@hidden empty-rule
+Empty rules without @code{%empty}.  @xref{Empty Rules}.  Disabled by
+default, but enabled by uses of @code{%empty}, unless
address@hidden was specified.
+
 @item precedence
 Useless precedence and associativity directives.  Disabled by default.
 
@@ -12428,6 +12477,11 @@ time to resolve reduce/reduce conflicts.  @xref{GLR 
Parsers, ,Writing
 GLR Parsers}.
 @end deffn
 
address@hidden {Directive} %empty
+Bison declaration to declare make explicit that a rule has an empty
+right-hand side.  @xref{Empty Rules}.
address@hidden deffn
+
 @deffn {Symbol} $end
 The predefined token marking the end of the token stream.  It cannot be
 used in the grammar.
-- 
1.8.1.3