skeletons: make the warning about implementation details clearer

[Akim Demaille]

commit f486783bc907bb00ff821d02a92396909c43d80d
Author: Akim Demaille <address@hidden>
Date:   Sat Apr 25 15:26:49 2020 +0200

    skeletons: make the warning about implementation details clearer
    
    * data/skeletons/bison.m4 (b4_disclaimer): Here.
    * data/skeletons/lalr1.d, data/skeletons/lalr1.java: Use it.

diff --git a/data/skeletons/bison.m4 b/data/skeletons/bison.m4
index c83ae70e..e70175b6 100644
--- a/data/skeletons/bison.m4
+++ b/data/skeletons/bison.m4
@@ -72,8 +72,9 @@ version 2.2 of Bison.])
 # -------------
 # Issue a warning about private implementation details.
 m4_define([b4_disclaimer],
-[b4_comment([Undocumented macros, especially those whose name start with YY_,
-are private implementation details.  Do not rely on them.])
+[b4_comment([Do not rely on features that are not documented in the manual,
+especially those whose name start with YY_ or yy_.  They are
+private implementation details that can be changed or removed.])
 ])
 
 
diff --git a/data/skeletons/lalr1.d b/data/skeletons/lalr1.d
index 01257411..85242b14 100644
--- a/data/skeletons/lalr1.d
+++ b/data/skeletons/lalr1.d
@@ -21,7 +21,7 @@ m4_include(b4_skeletonsdir/[d.m4])
 b4_output_begin([b4_parser_file_name])
 b4_copyright([Skeleton implementation for Bison LALR(1) parsers in D],
              [2007-2012, 2019-2020])[
-
+]b4_disclaimer[
 ]b4_percent_define_ifdef([package], [module b4_percent_define_get([package]);
 ])[
 version(D_Version2) {
diff --git a/data/skeletons/lalr1.java b/data/skeletons/lalr1.java
index 7e9c4da2..e4273895 100644
--- a/data/skeletons/lalr1.java
+++ b/data/skeletons/lalr1.java
@@ -78,6 +78,7 @@ m4_define([b4_define_state],[[
 ]b4_output_begin([b4_parser_file_name])[
 ]b4_copyright([Skeleton implementation for Bison LALR(1) parsers in Java],
               [2007-2015, 2018-2020])[
+]b4_disclaimer[
 ]b4_percent_define_ifdef([package], [package b4_percent_define_get([package]);[
 ]])[
 ]b4_user_pre_prologue[
diff --git a/data/skeletons/yacc.c b/data/skeletons/yacc.c
index f52d11a5..645188bc 100644
--- a/data/skeletons/yacc.c
+++ b/data/skeletons/yacc.c
@@ -358,6 +358,7 @@ b4_output_begin([b4_parser_file_name])[
 /* C LALR(1) parser skeleton written by Richard Stallman, by
    simplifying the original so-called "semantic" parser.  */
 
+]b4_disclaimer[
 /* All symbols defined below should begin with yy or YY, to avoid
    infringing on user name space.  This should be done even for local
    variables, as they might otherwise be expanded by user macros.
@@ -365,7 +366,6 @@ b4_output_begin([b4_parser_file_name])[
    define necessary library symbols; they are noted "INFRINGES ON
    USER NAME SPACE" below.  */
 
-]b4_disclaimer[
 ]b4_identification[
 ]b4_percent_code_get([[top]])[]dnl
 m4_if(b4_api_prefix, [yy], [],
diff --git a/src/parse-gram.c b/src/parse-gram.c
index 63842113..cfcd2208 100644
--- a/src/parse-gram.c
+++ b/src/parse-gram.c
@@ -34,6 +34,10 @@
 /* C LALR(1) parser skeleton written by Richard Stallman, by
    simplifying the original so-called "semantic" parser.  */
 
+/* Do not rely on features that are not documented in the manual,
+   especially those whose name start with YY_ or yy_.  They are
+   private implementation details that can be changed or removed.  */
+
 /* All symbols defined below should begin with yy or YY, to avoid
    infringing on user name space.  This should be done even for local
    variables, as they might otherwise be expanded by user macros.
@@ -41,9 +45,6 @@
    define necessary library symbols; they are noted "INFRINGES ON
    USER NAME SPACE" below.  */
 
-/* Undocumented macros, especially those whose name start with YY_,
-   are private implementation details.  Do not rely on them.  */
-
 /* Identify Bison output.  */
 #define YYBISON 1
 
diff --git a/src/parse-gram.h b/src/parse-gram.h
index 3ae6f375..c80581f2 100644
--- a/src/parse-gram.h
+++ b/src/parse-gram.h
@@ -31,8 +31,9 @@
    This special exception was added by the Free Software Foundation in
    version 2.2 of Bison.  */
 
-/* Undocumented macros, especially those whose name start with YY_,
-   are private implementation details.  Do not rely on them.  */
+/* Do not rely on features that are not documented in the manual,
+   especially those whose name start with YY_ or yy_.  They are
+   private implementation details that can be changed or removed.  */
 
 #ifndef YY_GRAM_SRC_PARSE_GRAM_H_INCLUDED
 # define YY_GRAM_SRC_PARSE_GRAM_H_INCLUDED