headers: move CPP guards into YY_*_INCLUDED to avoid collisions

See <http://lists.gnu.org/archive/html/bug-bison/2012-09/msg00016.html>.

* data/c.m4 (b4_cpp_guard): Prepend YY_ and append _INCLUDED.
* tests/headers.at: Adjust.
* NEWS, doc/bison.texi: Document.

NEWS

@@ -26,6 +26,17 @@ GNU Bison NEWS
     foo.y:5.10-25: result type clash on merge function 'merge': <t3> != <t2>
     foo.y:4.13-27:     previous declaration
 
+** Header guards (yacc.c, glr.c, glr.cc)
+
+  In order to avoid collisions, the header guards are now
+  YY_<PREFIX>_<FILE>_INCLUDED, instead of merely <PREFIX>_<FILE>.
+  For instance the header generated from
+
+    %define api.prefix "calc"
+    %defines "lib/parse.h"
+
+  will use YY_CALC_LIB_PARSE_H_INCLUDED as guard.
+
 * Noteworthy changes in release 2.6.2 (2012-08-03) [stable]
 
 ** Bug fixes

data/c.m4

@@ -30,7 +30,7 @@ m4_define([b4_tocpp],
 # ------------------
 # A valid C macro name to use as a CPP header guard for FILE.
 m4_define([b4_cpp_guard],
-[b4_tocpp(m4_defn([b4_prefix])/[$1])])
+[[YY_]b4_tocpp(m4_defn([b4_prefix])/[$1])[_INCLUDED]])
 
 
 # b4_cpp_guard_open(FILE)

doc/bison.texi

@@ -5124,6 +5124,23 @@ Values, ,Semantic Values of Tokens}.
 If you have declared @code{%code requires} or @code{%code provides}, the output
 header also contains their code.
 @xref{%code Summary}.
+
+@cindex Header guard
+The generated header is protected against multiple inclusions with a C
+preprocessor guard: @samp{YY_@var{PREFIX}_@var{FILE}_INCLUDED}, where
+@var{PREFIX} and @var{FILE} are the prefix (@pxref{Multiple Parsers,
+,Multiple Parsers in the Same Program}) and generated file name turned
+uppercase, with each series of non alphanumerical characters converted to a
+single underscore.
+
+For instance with @samp{%define api.prefix "calc"} and @samp{%defines
+"lib/parse.h"}, the header will be guarded as follows.
+@example
+#ifndef YY_CALC_LIB_PARSE_H_INCLUDED
+# define YY_CALC_LIB_PARSE_H_INCLUDED
+...
+#endif /* ! YY_CALC_LIB_PARSE_H_INCLUDED */
+@end example
 @end deffn
 
 @deffn {Directive} %defines @var{defines-file}

tests/headers.at

@@ -167,13 +167,14 @@ AT_BISON_CHECK([-d -o AT_SKEL_CC_IF([$1.cc $1.yy], [$1.c $1.y])])
 AT_SKEL_CC_IF([],
   [AT_CHECK([$EGREP yy $1.h], [1])])
 
-# Ignore comments. Ignore YYPARSE_PARAM (obsolete) and
-# YYPUSH_MORE(_DEFINED)? (whose definition is constant).
+# Check there is not 'YY' left.
+# Ignore comments, YYPARSE_PARAM (obsolete), YYPUSH_MORE(_DEFINED)?
+# (constant definition), YY_\w+_INCLUDED (header guards).
 #
 # YYDEBUG (not renamed) can be read, but not changed.
 AT_CHECK([[sed -ne 's,/\*[^*]*\*/,,g;s,//.*,,' \
                 -e '/YY/p' ]$1.AT_SKEL_CC_IF([hh], [h])[ |
-     $EGREP -wv 'YY(PARSE_PARAM|PUSH_MORE(_DEFINED)?)|(defined|if) YYDEBUG']],
+     $EGREP -wv 'YY(PARSE_PARAM|PUSH_MORE(_DEFINED)?|_[0-9A-Z_]+_INCLUDED)|(defined|if) YYDEBUG']],
          [1])
 
 AT_LANG_COMPILE([$1.o])