This patch is for PR 47823, which was about the documentation for
"#pragma once" being buried in a strange location in the CPP manual.
I've put the primary documentation for it with the other preprocessor
pragmas in the CPP manual, and added a blurb to the pragmas chapter in
the GCC manual explaining that preprocessor pragmas are documented in
the CPP manual.
-Sandra
2018-11-12 Sandra Loosemore <san...@codesourcery.com>
PR preprocessor/47823
gcc/
* doc/cpp.texi (Alternatives to Wrapper #ifndef): Move #pragma once
documentation to...
(Pragmas): ...here.
* doc/extend.texi (Pragmas): Note additional pragmas documented
in the CPP manual.
Index: gcc/doc/cpp.texi
===================================================================
--- gcc/doc/cpp.texi (revision 266042)
+++ gcc/doc/cpp.texi (working copy)
@@ -958,10 +958,7 @@ prevent the file from ever being read ag
@samp{#import} and @samp{#include} to refer to the same header file.
Another way to prevent a header file from being included more than once
-is with the @samp{#pragma once} directive. If @samp{#pragma once} is
-seen when scanning a header file, that file will never be read again, no
-matter what.
-
+is with the @samp{#pragma once} directive (@pxref{Pragmas}).
@samp{#pragma once} does not have the problems that @samp{#import} does,
but it is not recognized by all preprocessors, so you cannot rely on it
in a portable program.
@@ -3550,12 +3547,14 @@ idea of the directory containing the cur
@node Pragmas
@chapter Pragmas
+@cindex pragma directive
+
The @samp{#pragma} directive is the method specified by the C standard
for providing additional information to the compiler, beyond what is
conveyed in the language itself. The forms of this directive
(commonly known as @dfn{pragmas}) specified by C standard are prefixed with
@code{STDC}. A C compiler is free to attach any meaning it likes to other
-pragmas. All GNU-defined, supported pragmas have been given a
+pragmas. Most GNU-defined, supported pragmas have been given a
@code{GCC} prefix.
@cindex @code{_Pragma}
@@ -3658,6 +3657,12 @@ contained in the pragma must be a single
the @samp{#warning} and @samp{#error} directives, these pragmas can be
embedded in preprocessor macros using @samp{_Pragma}.
+@item #pragma once
+If @code{#pragma once} is seen when scanning a header file, that
+file will never be read again, no matter what. It is a less-portable
+alternative to using @samp{#ifndef} to guard the contents of header files
+against multiple inclusions.
+
@end ftable
@node Other Directives
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi (revision 266042)
+++ gcc/doc/extend.texi (working copy)
@@ -22064,6 +22064,10 @@ code originally written for other compil
we do not recommend the use of pragmas; @xref{Function Attributes},
for further explanation.
+The GNU C preprocessor recognizes several pragmas in addition to the
+compiler pragmas documented here. Refer to the CPP manual for more
+information.
+
@menu
* AArch64 Pragmas::
* ARM Pragmas::
