all: display a clear warning about private macros

[Akim Demaille]

commit 73917e9e6f6598b7d520b2f723920cc7f366b6d2
Author: Akim Demaille <address@hidden>
Date:   Sun Oct 21 19:10:41 2018 +0200

    all: display a clear warning about private macros
    
    * data/bison.m4 (b4_disclaimer): New.
    * data/glr.c, data/glr.cc, data/lalr1.cc, data/yacc.c: Use it.

diff --git a/NEWS b/NEWS
index d4dd7619..7ffe90ff 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,17 @@ GNU Bison NEWS
 
 * Noteworthy changes in release ?.? (????-??-??) [?]
 
+** Implementation details
+
+  A comment in the generated code now emphasizes that users should not
+  depend upon non-documented implementation details, such as macros starting
+  with YY_.
+
+** Changes
+
+  %printers should use yyo rather than yyoutput to denote the output stream.
+
+  Variant-based symbols in C++ should use emplace() rather than build().
 
 * Noteworthy changes in release 3.1.91 (2018-10-18) [beta]
 
diff --git a/data/bison.m4 b/data/bison.m4
index f727a04d..ede25627 100644
--- a/data/bison.m4
+++ b/data/bison.m4
@@ -58,7 +58,18 @@ Bison output files to be licensed under the GNU General 
Public
 License without this special exception.
 
 This special exception was added by the Free Software Foundation in
-version 2.2 of Bison.])])
+version 2.2 of Bison.])
+])
+
+
+# b4_disclaimer
+# -------------
+# 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_required_version_if(VERSION, IF_NEWER, IF_OLDER)
diff --git a/data/glr.c b/data/glr.c
index 6da6d45f..48e7d2e3 100644
--- a/data/glr.c
+++ b/data/glr.c
@@ -199,7 +199,6 @@ m4_if(b4_skeleton, ["glr.c"],
 [b4_output_begin([b4_spec_defines_file])
 b4_copyright([Skeleton interface for Bison GLR parsers in C],
              [2002-2015, 2018])[
-
 ]b4_cpp_guard_open([b4_spec_defines_file])[
 ]b4_shared_declarations[
 ]b4_cpp_guard_close([b4_spec_defines_file])[
@@ -214,9 +213,9 @@ b4_copyright([Skeleton interface for Bison GLR parsers in 
C],
 b4_output_begin([b4_parser_file_name])
 b4_copyright([Skeleton implementation for Bison GLR parsers in C],
              [2002-2015, 2018])[
-
 /* C GLR parser skeleton written by Paul Hilfinger.  */
 
+]b4_disclaimer[
 ]b4_identification[
 
 ]b4_percent_code_get([[top]])[
diff --git a/data/glr.cc b/data/glr.cc
index b6139da7..cc228995 100644
--- a/data/glr.cc
+++ b/data/glr.cc
@@ -333,9 +333,9 @@ b4_defines_if(
 [b4_output_begin([b4_spec_defines_file])
 b4_copyright([Skeleton interface for Bison GLR parsers in C++],
              [2002-2015, 2018])[
-
 // C++ GLR parser skeleton written by Akim Demaille.
 
+]b4_disclaimer[
 ]b4_cpp_guard_open([b4_spec_defines_file])[
 ]b4_shared_declarations[
 ]b4_cpp_guard_close([b4_spec_defines_file])[
diff --git a/data/lalr1.cc b/data/lalr1.cc
index 6b6d1584..467a5fde 100644
--- a/data/lalr1.cc
+++ b/data/lalr1.cc
@@ -392,6 +392,10 @@ m4_define([b4_shared_declarations],
 ]b4_percent_code_get([[provides]])[
 ]])
 
+## -------------- ##
+## Output files.  ##
+## -------------- ##
+
 b4_defines_if(
 [b4_output_begin([b4_spec_defines_file])
 b4_copyright([Skeleton interface for Bison LALR(1) parsers in C++])
@@ -403,6 +407,7 @@ b4_copyright([Skeleton interface for Bison LALR(1) parsers 
in C++])
 
 // C++ LALR(1) parser skeleton written by Akim Demaille.
 
+]b4_disclaimer[
 ]b4_cpp_guard_open([b4_spec_defines_file])[
 ]b4_shared_declarations(hh)[
 ]b4_cpp_guard_close([b4_spec_defines_file])
@@ -410,9 +415,10 @@ b4_output_end
 ])
 
 
-b4_output_begin([b4_parser_file_name])
-b4_copyright([Skeleton implementation for Bison LALR(1) parsers in C++])
-b4_percent_code_get([[top]])[]dnl
+b4_output_begin([b4_parser_file_name])[
+]b4_copyright([Skeleton implementation for Bison LALR(1) parsers in C++])[
+]b4_disclaimer[
+]b4_percent_code_get([[top]])[]dnl
 m4_if(b4_prefix, [yy], [],
 [
 // Take the name prefix into account.
diff --git a/data/lalr1.java b/data/lalr1.java
index d270850b..7a662a3d 100644
--- a/data/lalr1.java
+++ b/data/lalr1.java
@@ -82,12 +82,11 @@ m4_define([b4_define_state],[[
     ]b4_yystype[ yylval = null;
 ]])
 
-b4_output_begin([b4_parser_file_name])
-b4_copyright([Skeleton implementation for Bison LALR(1) parsers in Java],
-             [2007-2015, 2018])
-
-b4_percent_define_ifdef([package], [package b4_percent_define_get([package]);
-])[
+b4_output_begin([b4_parser_file_name])[
+]b4_copyright([Skeleton implementation for Bison LALR(1) parsers in Java],
+             [2007-2015, 2018])[
+]b4_percent_define_ifdef([package], [package b4_percent_define_get([package]);[
+]])[
 ]b4_user_pre_prologue[
 ]b4_user_post_prologue[
 ]b4_percent_code_get([[imports]])
diff --git a/data/location.cc b/data/location.cc
index 3f0f97fb..60756dc0 100644
--- a/data/location.cc
+++ b/data/location.cc
@@ -338,7 +338,6 @@ m4_ifdef([b4_position_file], [[
 m4_ifdef([b4_location_file], [[
 ]b4_output_begin([b4_dir_prefix], [b4_location_file])[
 ]b4_copyright([Locations for Bison parsers in C++])[
-
 /**
  ** \file ]b4_location_path[
  ** Define the ]b4_namespace_ref[::location class.
diff --git a/data/yacc.c b/data/yacc.c
index 880379ba..e44735a9 100644
--- a/data/yacc.c
+++ b/data/yacc.c
@@ -299,9 +299,8 @@ m4_define([b4_shared_declarations],
 ## Output files.  ##
 ## -------------- ##
 
-b4_output_begin([b4_parser_file_name])
-b4_copyright([Bison implementation for Yacc-like parsers in C])[
-
+b4_output_begin([b4_parser_file_name])[
+]b4_copyright([Bison implementation for Yacc-like parsers in C])[
 /* C LALR(1) parser skeleton written by Richard Stallman, by
    simplifying the original so-called "semantic" parser.  */
 
@@ -312,8 +311,9 @@ b4_copyright([Bison implementation for Yacc-like parsers in 
C])[
    define necessary library symbols; they are noted "INFRINGES ON
    USER NAME SPACE" below.  */
 
-]b4_identification
-b4_percent_code_get([[top]])[]dnl
+]b4_disclaimer[
+]b4_identification[
+]b4_percent_code_get([[top]])[]dnl
 m4_if(b4_api_prefix, [yy], [],
 [[/* Substitute the type names.  */
 #define YYSTYPE         ]b4_api_PREFIX[STYPE]b4_locations_if([[
@@ -1906,10 +1906,10 @@ yypushreturn:]])[
 ]b4_epilogue[]dnl
 b4_output_end
 
-b4_defines_if(
-[b4_output_begin([b4_spec_defines_file])[
+b4_defines_if([[
+]b4_output_begin([b4_spec_defines_file])[
 ]b4_copyright([Bison interface for Yacc-like parsers in C])[
-
+]b4_disclaimer[
 ]b4_shared_declarations[
-]b4_output_end
-])# b4_defines_if
+]b4_output_end[
+]])# b4_defines_if