parse.error: document and diagnose the incompatibility with %token-table

* doc/bison.texi (Tokens from Literals): Move to code using
%token-table to...
(Decl Summary: %token-table): here.
* data/skeletons/bison.m4: Implement mutual exclusion.
* tests/input.at: Check it.
* doc/local.mk: Be robust to the removal of doc/.

1 files changed, 25 insertions, 23 deletions

diff --git a/doc/bison.texi b/doc/bison.texi
index 37853834..678101a3 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -5780,6 +5780,8 @@ This is similar to how most shells resolve commands.
 @end deffn
 
 @deffn {Directive} %token-table
+This feature is obsolescent, avoid it in new projects.
+
 Generate an array of token names in the parser implementation file.  The
 name of the array is @code{yytname}; @code{yytname[@var{i}]} is the name of
 the token whose internal Bison token code number is @var{i}.  The first
@@ -5809,6 +5811,29 @@ The number of grammar rules,
 @item YYNSTATES
 The number of parser states (@pxref{Parser States}).
 @end table
+
+Here's code for looking up a multicharacter token in @code{yytname},
+assuming that the characters of the token are stored in @code{token_buffer},
+and assuming that the token does not contain any characters like @samp{"}
+that require escaping.
+
+@example
+for (int i = 0; i < YYNTOKENS; i++)
+  if (yytname[i]
+      && yytname[i][0] == '"'
+      && ! strncmp (yytname[i] + 1, token_buffer,
+                    strlen (token_buffer))
+      && yytname[i][strlen (token_buffer) + 1] == '"'
+      && yytname[i][strlen (token_buffer) + 2] == 0)
+    break;
+@end example
+
+This method is discouraged: the primary purpose of string aliases is forging
+good error messages, not describing the spelling of keywords.  In addition,
+looking for the token type at runtime incurs a (small but noticeable) cost.
+
+Finally, @code{%token-table} is incompatible with the @code{custom} and
+@code{detailed} values of the @code{parse.error} @code{%define} variable.
 @end deffn
 
 @deffn {Directive} %verbose
@@ -7089,29 +7114,6 @@ forging good error messages, not describing the spelling of keywords.  In
 addition, looking for the token type at runtime incurs a (small but
 noticeable) cost.
 
-The index of the token in the table is the token type's code.  The name of a
-multicharacter token is recorded in @code{yytname} with a double-quote, the
-token's characters, and another double-quote.  The token's characters are
-escaped as necessary to be suitable as input to Bison.
-
-Here's code for looking up a multicharacter token in @code{yytname},
-assuming that the characters of the token are stored in @code{token_buffer},
-and assuming that the token does not contain any characters like @samp{"}
-that require escaping.
-
-@example
-for (int i = 0; i < YYNTOKENS; i++)
-  @{
-    if (yytname[i]
-        && yytname[i][0] == '"'
-        && ! strncmp (yytname[i] + 1, token_buffer,
-                      strlen (token_buffer))
-        && yytname[i][strlen (token_buffer) + 1] == '"'
-        && yytname[i][strlen (token_buffer) + 2] == 0)
-      break;
-  @}
-@end example
-
 The @code{yytname} table is generated only if you use the
 @code{%token-table} declaration.  @xref{Decl Summary}.
 @end itemize