[PATCH 01/16] skeletons: make the warning about implementation details clearer

[Akim Demaille]

* data/skeletons/bison.m4 (b4_disclaimer): Here.
* data/skeletons/lalr1.d, data/skeletons/lalr1.java: Use it.
---
 data/skeletons/bison.m4   | 5 +++--
 data/skeletons/lalr1.d    | 2 +-
 data/skeletons/lalr1.java | 1 +
 data/skeletons/yacc.c     | 2 +-
 src/parse-gram.c          | 7 ++++---
 src/parse-gram.h          | 5 +++--
 6 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/data/skeletons/bison.m4 b/data/skeletons/bison.m4
index c83ae70e..33359f10 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..55990bd8 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..50dca5bf 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
-- 
2.26.2