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

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index b8a1aa6d5bfe4aa51509bf3e0e3878d58a526955..69836112db41f7a73a102aa70a0221460ada18db 100644 (file)
--- a/doc/bison.texi
+++ b/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}.
 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}
 @end deffn
 
 @deffn {Directive} %defines @var{defines-file}