RFC: doc: promote %nterm over %type

[Akim Demaille]

%nterm has been supported by Bison since forever.  However, it's only recently 
that it has been documented.  I now think we should promote it over %type when 
they are used for the same purpose, as it's safer and clearer.

I'll wait for comments before pushing.

commit 0918dbef8fc07a4692fac66698685a705c4c8f49
Author: Akim Demaille <address@hidden>
Date:   Thu Nov 14 07:02:58 2019 +0100

    doc: promote %nterm over %type
    
    As an extension to POSIX Yacc, Bison's %type accepts tokens.
    Unfortunately with string literals as implicit tokens, this is
    misleading, and led some users to write
    
        %type <exVal> cond "condition"
    
    believing that "condition" would be associated to the 'cond'
    nonterminal (see https://github.com/apache/httpd/pull/72).
    
    * doc/bison.texi: Promote %nterm rather than %type to declare the type
    of nonterminals.

diff --git a/doc/bison.texi b/doc/bison.texi
index e9c5ff70..ae64897b 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -419,7 +419,7 @@ A Complete C++ Example
 Java Parsers
 
 * Java Bison Interface::        Asking for Java parser generation
-* Java Semantic Values::        %type and %token vs. Java
+* Java Semantic Values::        %token and %nterm vs. Java
 * Java Location Values::        The position and location classes
 * Java Parser Interface::       Instantiating and running the parser
 * Java Scanner Interface::      Specifying the scanner for the parser
@@ -2466,7 +2466,7 @@ Here are the C and Bison declarations for the 
multi-function calculator.
 %define api.value.type union /* Generate YYSTYPE from these types: */
 %token <double>  NUM     /* Double precision number. */
 %token <symrec*> VAR FUN /* Symbol table pointer: variable/function. */
-%type  <double>  exp
+%nterm <double>  exp
 
 @group
 %precedence '='
@@ -2492,9 +2492,9 @@ with each grammar symbol whose semantic value is used.  
These symbols are
 augmented with their data type (placed between angle brackets).  For
 instance, values of @code{NUM} are stored in @code{double}.
 
-The Bison construct @code{%type} is used for declaring nonterminal symbols,
+The Bison construct @code{%nterm} is used for declaring nonterminal symbols,
 just as @code{%token} is used for declaring token types.  Previously we did
-not use @code{%type} before because nonterminal symbols are normally
+not use @code{%nterm} before because nonterminal symbols are normally
 declared implicitly by the rules that define them.  But @code{exp} must be
 declared explicitly so we can specify its value type.  @xref{Type Decl,
 ,Nonterminal Symbols}.
@@ -3778,9 +3778,9 @@ union type whose member names are the type tags.
 @item
 Choose one of those types for each symbol (terminal or nonterminal) for
 which semantic values are used.  This is done for tokens with the
-@code{%token} Bison declaration (@pxref{Token Decl, ,Token Type Names})
-and for groupings with the @code{%type} Bison declaration (@pxref{Type
-Decl, ,Nonterminal Symbols}).
+@code{%token} Bison declaration (@pxref{Token Decl, ,Token Type Names}) and
+for groupings with the @code{%nterm}/@code{%type} Bison declarations
+(@pxref{Type Decl, ,Nonterminal Symbols}).
 @end itemize
 
 @node Type Generation
@@ -3790,9 +3790,9 @@ Decl, ,Nonterminal Symbols}).
 @findex %define api.value.type union
 
 The special value @code{union} of the @code{%define} variable
-@code{api.value.type} instructs Bison that the tags used with the
-@code{%token} and @code{%type} directives are genuine types, not names of
-members of @code{YYSTYPE}.
+@code{api.value.type} instructs Bison that the type tags (used with the
+@code{%token}, @code{%nterm} and @code{%type} directives) are genuine types,
+not names of members of @code{YYSTYPE}.
 
 For example:
 
@@ -3800,7 +3800,7 @@ For example:
 %define api.value.type union
 %token <int> INT "integer"
 %token <int> 'n'
-%type <int> expr
+%nterm <int> expr
 %token <char const *> ID "identifier"
 @end example
 
@@ -3870,8 +3870,9 @@ For example:
 @noindent
 This says that the two alternative types are @code{double} and @code{symrec
 *}.  They are given names @code{val} and @code{tptr}; these names are used
-in the @code{%token} and @code{%type} declarations to pick one of the types
-for a terminal or nonterminal symbol (@pxref{Type Decl, ,Nonterminal Symbols}).
+in the @code{%token}, @code{%nterm} and @code{%type} declarations to pick
+one of the types for a terminal or nonterminal symbol (@pxref{Type Decl,
+,Nonterminal Symbols}).
 
 As an extension to POSIX, a tag is allowed after the @code{%union}.  For
 example:
@@ -3926,7 +3927,7 @@ and then your grammar can use the following instead of 
@code{%union}:
 #include "parser.h"
 %@}
 %define api.value.type @{union YYSTYPE@}
-%type <val> expr
+%nterm <val> expr
 %token <tptr> ID
 @end group
 @end example
@@ -4346,7 +4347,7 @@ that symbol:
 
 @example
 @group
-%type <context> let
+%nterm <context> let
 %destructor @{ pop_context ($$); @} let
 %printer @{ print_context (yyo, $$); @} let
 @end group
@@ -5015,12 +5016,13 @@ same value type.  Use spaces to separate the symbol 
names.
 
 While POSIX Yacc allows @code{%type} only for nonterminals, Bison accepts
 that this directive be also applied to terminal symbols.  To declare
-exclusively nonterminal symbols, use @code{%nterm}:
+exclusively nonterminal symbols, use the safer @code{%nterm}:
 
 @example
 %nterm <@var{type}> @var{nonterminal}@dots{}
 @end example
 
+
 @node Symbol Decls
 @subsection Syntax of Symbol Declarations
 @findex %left
@@ -5119,8 +5121,9 @@ The parser will invoke the @var{code} associated with one 
of these whenever it
 discards any user-defined grammar symbol that has no per-symbol and no per-type
 @code{%destructor}.
 The parser uses the @var{code} for @code{<*>} in the case of such a grammar
-symbol for which you have formally declared a semantic type tag (@code{%type}
-counts as such a declaration, but @code{$<tag>$} does not).
+symbol for which you have formally declared a semantic type tag (@code{%token},
+@code{%nterm}, and @code{%type}
+count as such a declaration, but @code{$<tag>$} does not).
 The parser uses the @var{code} for @code{<>} in the case of such a grammar
 symbol that has no declared semantic type tag.
 @end deffn
@@ -5131,10 +5134,10 @@ For example:
 @example
 %union @{ char *string; @}
 %token <string> STRING1 STRING2
-%type  <string> string1 string2
+%nterm <string> string1 string2
 %union @{ char character; @}
 %token <character> CHR
-%type  <character> chr
+%nterm <character> chr
 %token TAGLESS
 
 %destructor @{ @} <character>
@@ -5257,10 +5260,10 @@ For example:
 @example
 %union @{ char *string; @}
 %token <string> STRING1 STRING2
-%type  <string> string1 string2
+%nterm <string> string1 string2
 %union @{ char character; @}
 %token <character> CHR
-%type  <character> chr
+%nterm <character> chr
 %token TAGLESS
 
 %printer @{ fprintf (yyo, "'%c'", $$); @} <character>
@@ -6378,7 +6381,7 @@ Use this @var{type} as semantic value.
 @code{union-directive} if @code{%union} is used, otherwise @dots{}
 @item
 @code{int} if type tags are used (i.e., @samp{%token <@var{type}>@dots{}} or
-@samp{%type <@var{type}>@dots{}} is used), otherwise @dots{}
+@samp{%nterm <@var{type}>@dots{}} is used), otherwise @dots{}
 @item
 undefined.
 @end itemize
@@ -9382,11 +9385,11 @@ The following grammar file, @file{calc.y}, will be used 
in the sequel:
 @end group
 @group
 %token <ival> NUM
-%type  <ival> exp
+%nterm <ival> exp
 @end group
 @group
 %token <sval> STR
-%type  <sval> useless
+%nterm <sval> useless
 @end group
 @group
 %left '+' '-'
@@ -10410,7 +10413,7 @@ important part of it with carets (@samp{^}). Here is an 
example, using the
 following file @file{in.y}:
 
 @example
-%type <ival> exp
+%nterm <ival> exp
 %%
 exp: exp '+' exp @{ $exp = $1 + $2; @};
 @end example
@@ -11072,7 +11075,7 @@ result:
 ;
 @end group
 
-%type <std::vector<std::string>> list;
+%nterm <std::vector<std::string>> list;
 @group
 list:
   %empty     @{ /* Generates an empty string list */ @}
@@ -11127,7 +11130,7 @@ strings:
 
 @comment file: c++/simple.yy: 2
 @example
-%type <std::string> item;
+%nterm <std::string> item;
 %token <std::string> TEXT;
 %token <int> NUMBER;
 @group
@@ -12208,14 +12211,14 @@ tokens with @code{TOK_} (@pxref{%define 
Summary,,api.token.prefix}).
 
 @noindent
 Since we use variant-based semantic values, @code{%union} is not used, and
-both @code{%type} and @code{%token} expect genuine types, as opposed to type
+@code{%token}, @code{%nterm} and @code{%type} expect genuine types, not type
 tags.
 
 @comment file: calc++/parser.yy
 @example
 %token <std::string> IDENTIFIER "identifier"
 %token <int> NUMBER "number"
-%type  <int> exp
+%nterm <int> exp
 @end example
 
 @noindent
@@ -12520,7 +12523,7 @@ main (int argc, char *argv[])
 
 @menu
 * Java Bison Interface::        Asking for Java parser generation
-* Java Semantic Values::        %type and %token vs. Java
+* Java Semantic Values::        %token and %nterm vs. Java
 * Java Location Values::        The position and location classes
 * Java Parser Interface::       Instantiating and running the parser
 * Java Scanner Interface::      Specifying the scanner for the parser
@@ -12584,17 +12587,17 @@ otherwise, report a bug so that the parser skeleton 
will be improved.
 
 @node Java Semantic Values
 @subsection Java Semantic Values
-@c - No %union, specify type in %type/%token.
+@c - No %union, specify type in %nterm/%token.
 @c - YYSTYPE
 @c - Printer and destructor
 
-There is no @code{%union} directive in Java parsers.  Instead, the
-semantic values' types (class names) should be specified in the
-@code{%type} or @code{%token} directive:
+There is no @code{%union} directive in Java parsers.  Instead, the semantic
+values' types (class names) should be specified in the @code{%nterm} or
+@code{%token} directive:
 
 @example
-%type <Expression> expr assignment_expr term factor
-%type <Integer> number
+%nterm <Expression> expr assignment_expr term factor
+%nterm <Integer> number
 @end example
 
 By default, the semantic stack is declared to have @code{Object} members,
@@ -12608,8 +12611,8 @@ directive.  For example, after the following 
declaration:
 @end example
 
 @noindent
-any @code{%type} or @code{%token} specifying a semantic type which
-is not a subclass of ASTNode, will cause a compile-time error.
+any @code{%token}, @code{%nterm} or @code{%type} specifying a semantic type
+which is not a subclass of @code{ASTNode}, will cause a compile-time error.
 
 @c FIXME: Documented bug.
 Types used in the directives may be qualified with a package name.
@@ -13062,7 +13065,7 @@ Declare tokens.  Note that the angle brackets enclose a 
Java @emph{type}.
 @xref{Java Semantic Values}.
 @end deffn
 
-@deffn {Directive} %type <@var{type}> @var{nonterminal} @dots{}
+@deffn {Directive} %nterm <@var{type}> @var{nonterminal} @dots{}
 Declare the type of nonterminals.  Note that the angle brackets enclose
 a Java @emph{type}.
 @xref{Java Semantic Values}.