[doc,committed] make #pragma once documentation easier to find

Message ID ba264ac7-70f4-0898-73dd-69145a409ca4@codesourcery.com
State New
Headers show
Series
  • [doc,committed] make #pragma once documentation easier to find
Related show

Commit Message

Sandra Loosemore Nov. 13, 2018, 2:13 a.m.
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

Patch

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::