cpp.texi (Invocation): Revise to indicate that GCC driver options are only…

cpp.texi (Invocation): Revise to indicate that GCC driver options are only documented in the GCC manual.

2016-12-25  Sandra Loosemore  <sandra@codesourcery.com>

	gcc/
	* doc/cpp.texi (Invocation): Revise to indicate that GCC driver
	options are only documented in the GCC manual.
	* doc/cppopts.texi: Delete documentation of GCC driver options 
	-o, -Wall, -Wtraditional, -Werror, -Wsystem-headers, -w,
	-pedantic, -pedantic-errors, -std=, -ansi, --help, --target-help, 
	-v, -version.  Update -Wcomment, -Wtrigraphs, -Wundef, 
	-Wexpansion-to-defined, -Wno-endif-labels, -traditional, 
	-traditional-cpp, -trigraphs to merge text previously in GCC manual.
	* doc/invoke.texi (Option Summary): Move -trigraphs, -traditional,
	and -traditional-cpp from C dialect options to preprocessor options.
	(C Dialect Options): Likewise.
	(Warning Options): Delete documentation of -Wcomment, -Wtrigraphs, 
	-Wexpansion-to-defined, -Wundef, and -Wno-endif-labels.

From-SVN: r243923

gcc/ChangeLog

+2016-12-25  Sandra Loosemore  <sandra@codesourcery.com>
+
+	* doc/cpp.texi (Invocation): Revise to indicate that GCC driver
+	options are only documented in the GCC manual.
+	* doc/cppopts.texi: Delete documentation of GCC driver options 
+	-o, -Wall, -Wtraditional, -Werror, -Wsystem-headers, -w,
+	-pedantic, -pedantic-errors, -std=, -ansi, --help, --target-help, 
+	-v, -version.  Update -Wcomment, -Wtrigraphs, -Wundef, 
+	-Wexpansion-to-defined, -Wno-endif-labels, -traditional, 
+	-traditional-cpp, -trigraphs to merge text previously in GCC manual.
+	* doc/invoke.texi (Option Summary): Move -trigraphs, -traditional,
+	and -traditional-cpp from C dialect options to preprocessor options.
+	(C Dialect Options): Likewise.
+	(Warning Options): Delete documentation of -Wcomment, -Wtrigraphs, 
+	-Wexpansion-to-defined, -Wundef, and -Wno-endif-labels.
+
 2016-12-24  Richard Sandiford  <richard.sandiford@arm.com>
 
 	* tree-core.h (tree_base): Document the meaning of public_flag

gcc/doc/cpp.texi

@@ -4285,51 +4285,54 @@ You can also make or cancel assertions using command-line options.
 @cindex invocation
 @cindex command line
 
-Most often when you use the C preprocessor you will not have to invoke it
-explicitly: the C compiler will do so automatically.  However, the
-preprocessor is sometimes useful on its own.  All the options listed
-here are also acceptable to the C compiler and have the same meaning,
-except that the C compiler has different rules for specifying the output
-file.
-
-@emph{Note:} Whether you use the preprocessor by way of @command{gcc}
-or @command{cpp}, the @dfn{compiler driver} is run first.  This
-program's purpose is to translate your command into invocations of the
-programs that do the actual work.  Their command-line interfaces are
-similar but not identical to the documented interface, and may change
-without notice.
+Most often when you use the C preprocessor you do not have to invoke it
+explicitly: the C compiler does so automatically.  However, the
+preprocessor is sometimes useful on its own.  You can invoke the 
+preprocessor either with the @command{cpp} command, or via @command{gcc -E}.
+In GCC, the preprocessor is actually integrated with the compiler
+rather than a separate program, and both of these commands invoke
+GCC and tell it to stop after the preprocessing phase.
+
+The @command {cpp} options listed here are also accepted by
+@command{gcc} and have the same meaning.  Likewise the @command{cpp}
+command accepts all the usual @command{gcc} driver options, although those
+pertaining to compilation phases after preprocessing are ignored.
+
+Only options specific to preprocessing behavior are documented here.
+Refer to the GCC manual for full documentation of other driver options.
 
 @ignore
 @c man begin SYNOPSIS
 cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
     [@option{-I}@var{dir}@dots{}] [@option{-iquote}@var{dir}@dots{}]
-    [@option{-W}@var{warn}@dots{}]
     [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}]
     [@option{-MP}] [@option{-MQ} @var{target}@dots{}]
     [@option{-MT} @var{target}@dots{}]
-    [@option{-P}] [@option{-fno-working-directory}]
-    [@option{-x} @var{language}] [@option{-std=}@var{standard}]
-    @var{infile} @var{outfile}
+    @var{infile} [[@option{-o}] @var{outfile}]
 
-Only the most useful options are listed here; see below for the remainder.
+Only the most useful options are given above; see below for a more
+complete list of preprocessor-specific options.  
+In addition, @command{cpp} accepts most @command{gcc} driver options, which
+are not listed here.  Refer to the GCC documentation for details.
 @c man end
 @c man begin SEEALSO
 gpl(7), gfdl(7), fsf-funding(7),
-gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and
-@file{binutils}.
+gcc(1), and the Info entries for @file{cpp} and @file{gcc}.
 @c man end
 @end ignore
 
 @c man begin OPTIONS
-The C preprocessor expects two file names as arguments, @var{infile} and
+The @command{cpp} command expects two file names as arguments, @var{infile} and
 @var{outfile}.  The preprocessor reads @var{infile} together with any
 other files it specifies with @samp{#include}.  All the output generated
 by the combined input files is written in @var{outfile}.
 
 Either @var{infile} or @var{outfile} may be @option{-}, which as
 @var{infile} means to read from standard input and as @var{outfile}
-means to write to standard output.  Also, if either file is omitted, it
+means to write to standard output.  If either file is omitted, it
 means the same as if @option{-} had been specified for that file.
+You can also use the @option{-o @var{outfile}} option to specify the 
+output file.
 
 Unless otherwise noted, or the option ends in @samp{=}, all options
 which take an argument may have that argument appear either immediately
@@ -4343,7 +4346,10 @@ options may @emph{not} be grouped: @option{-dM} is very different from
 @w{@samp{-d -M}}.
 
 @cindex options
+
+@table @gcctabopt
 @include cppopts.texi
+@end table
 @c man end
 
 @node Environment Variables

gcc/doc/cppopts.texi

@@ -9,7 +9,6 @@
 @c If this file is included with the flag ``cppmanual'' set, it is
 @c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
 
-@table @gcctabopt
 @item -D @var{name}
 @opindex D
 Predefine @var{name} as a macro, with definition @code{1}.
@@ -67,64 +66,38 @@ of system headers are not defeated
 If @var{dir} begins with @code{=}, then the @code{=} will be replaced
 by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
 
-@item -o @var{file}
-@opindex o
-Write output to @var{file}.  This is the same as specifying @var{file}
-as the second non-option argument to @command{cpp}.  @command{gcc} has a
-different interpretation of a second non-option argument, so you must
-use @option{-o} to specify the output file.
-
-@item -Wall
-@opindex Wall
-Turns on all optional warnings which are desirable for normal code.
-At present this is @option{-Wcomment}, @option{-Wtrigraphs},
-@option{-Wmultichar} and a warning about integer promotion causing a
-change of sign in @code{#if} expressions.  Note that many of the
-preprocessor's warnings are on by default and have no options to
-control them.
-
 @item -Wcomment
 @itemx -Wcomments
 @opindex Wcomment
 @opindex Wcomments
 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
 comment, or whenever a backslash-newline appears in a @samp{//} comment.
-(Both forms have the same effect.)
+This warning is enabled by @option{-Wall}.
 
 @item -Wtrigraphs
 @opindex Wtrigraphs
 @anchor{Wtrigraphs}
-Most trigraphs in comments cannot affect the meaning of the program.
-However, a trigraph that would form an escaped newline (@samp{??/} at
-the end of a line) can, by changing where the comment begins or ends.
-Therefore, only trigraphs that would form escaped newlines produce
-warnings inside a comment.
+Warn if any trigraphs are encountered that might change the meaning of
+the program.  Trigraphs within comments are not warned about,
+except those that would form escaped newlines.
 
 This option is implied by @option{-Wall}.  If @option{-Wall} is not
 given, this option is still enabled unless trigraphs are enabled.  To
 get trigraph conversion without warnings, but get the other
 @option{-Wall} warnings, use @samp{-trigraphs -Wall -Wno-trigraphs}.
 
-@item -Wtraditional
-@opindex Wtraditional
-Warn about certain constructs that behave differently in traditional and
-ISO C@.  Also warn about ISO C constructs that have no traditional C
-equivalent, and problematic constructs which should be avoided.
-@ifset cppmanual
-@xref{Traditional Mode}.
-@end ifset
-
 @item -Wundef
 @opindex Wundef
-Warn whenever an identifier which is not a macro is encountered in an
-@samp{#if} directive, outside of @samp{defined}.  Such identifiers are
-replaced with zero.
+@opindex Wno-undef
+Warn if an undefined identifier is evaluated in an @code{#if} directive.
+Such identifiers are replaced with zero.
 
 @item -Wexpansion-to-defined
 @opindex Wexpansion-to-defined
 Warn whenever @samp{defined} is encountered in the expansion of a macro
 (including the case where the macro is expanded by an @samp{#if} directive).
 Such usage is not portable.
+This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}.
 
 @item -Wunused-macros
 @opindex Wunused-macros
@@ -147,9 +120,10 @@ Alternatively, you could provide a dummy use with something like:
 #endif
 @end smallexample
 
-@item -Wendif-labels
+@item -Wno-endif-labels
+@opindex Wno-endif-labels
 @opindex Wendif-labels
-Warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
+Do not warn whenever an @code{#else} or an @code{#endif} are followed by text.
 This usually happens in code of the form
 
 @smallexample
@@ -164,33 +138,6 @@ This usually happens in code of the form
 The second and third @code{FOO} should be in comments, but often are not
 in older programs.  This warning is on by default.
 
-@item -Werror
-@opindex Werror
-Make all warnings into hard errors.  Source code which triggers warnings
-will be rejected.
-
-@item -Wsystem-headers
-@opindex Wsystem-headers
-Issue warnings for code in system headers.  These are normally unhelpful
-in finding bugs in your own code, therefore suppressed.  If you are
-responsible for the system library, you may want to see them.
-
-@item -w
-@opindex w
-Suppress all warnings, including those which GNU CPP issues by default.
-
-@item -pedantic
-@opindex pedantic
-Issue all the mandatory diagnostics listed in the C standard.  Some of
-them are left out by default, since they trigger frequently on harmless
-code.
-
-@item -pedantic-errors
-@opindex pedantic-errors
-Issue all the mandatory diagnostics, and make all mandatory diagnostics
-into errors.  This includes mandatory diagnostics that GCC issues
-without @samp{-pedantic} but treats as warnings.
-
 @item -M
 @opindex M
 @cindex @command{make}
@@ -369,60 +316,6 @@ which selected both the language and the standards conformance level.
 This option has been removed, because it conflicts with the @option{-l}
 option.
 
-@item -std=@var{standard}
-@itemx -ansi
-@opindex ansi
-@opindex std=
-Specify the standard to which the code should conform.  Currently CPP
-knows about C and C++ standards; others may be added in the future.
-
-@var{standard}
-may be one of:
-@table @code
-@item c90
-@itemx c89
-@itemx iso9899:1990
-The ISO C standard from 1990.  @samp{c90} is the customary shorthand for
-this version of the standard.
-
-The @option{-ansi} option is equivalent to @option{-std=c90}.
-
-@item iso9899:199409
-The 1990 C standard, as amended in 1994.
-
-@item iso9899:1999
-@itemx c99
-@itemx iso9899:199x
-@itemx c9x
-The revised ISO C standard, published in December 1999.  Before
-publication, this was known as C9X@.
-
-@item iso9899:2011
-@itemx c11
-@itemx c1x
-The revised ISO C standard, published in December 2011.  Before
-publication, this was known as C1X@.
-
-@item gnu90
-@itemx gnu89
-The 1990 C standard plus GNU extensions.  This is the default.
-
-@item gnu99
-@itemx gnu9x
-The 1999 C standard plus GNU extensions.
-
-@item gnu11
-@itemx gnu1x
-The 2011 C standard plus GNU extensions.
-
-@item c++98
-The 1998 ISO C++ standard plus amendments.
-
-@item gnu++98
-The same as @option{-std=c++98} plus GNU extensions.  This is the
-default for C++ code.
-@end table
-
 @item -I-
 @opindex I-
 Split the include path.  Any directories specified with @option{-I}
@@ -714,9 +607,11 @@ touch foo.h; cpp -dM foo.h
 @noindent
 will show all the predefined macros.
 
+@ifclear cppmanual
 If you use @option{-dM} without the @option{-E} option, @option{-dM} is
 interpreted as a synonym for @option{-fdump-rtl-mach}.
 @xref{Developer Options, , ,gcc}.
+@end ifclear
 
 @item D
 @opindex dD
@@ -778,28 +673,38 @@ the source line.
 
 The @option{-CC} option is generally used to support lint comments.
 
-@item -traditional-cpp
+@cindex traditional C language
+@cindex C language, traditional
+@item -traditional
+@itemx -traditional-cpp
 @opindex traditional-cpp
-Try to imitate the behavior of old-fashioned C preprocessors, as
+@opindex traditional
+
+Try to imitate the behavior of pre-standard C preprocessors, as
 opposed to ISO C preprocessors.
 @ifset cppmanual
 @xref{Traditional Mode}.
 @end ifset
+@ifclear cppmanual
+See the GNU CPP manual for details.
+@end ifclear
+
+Note that GCC does not otherwise attempt to emulate a pre-standard 
+C compiler, and these options are only supported with the @option{-E} 
+switch, or when invoking CPP explicitly.
 
 @item -trigraphs
 @opindex trigraphs
-Process trigraph sequences.
-@ifset cppmanual
-@xref{Initial processing}.
-@end ifset
-@ifclear cppmanual
+Support ISO C trigraphs.
 These are three-character sequences, all starting with @samp{??}, that
 are defined by ISO C to stand for single characters.  For example,
 @samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character
-constant for a newline.  By default, GCC ignores trigraphs, but in
-standard-conforming modes it converts them.  See the @option{-std} and
-@option{-ansi} options.
+constant for a newline.
+@ifset cppmanual
+@xref{Initial processing}.
+@end ifset
 
+@ifclear cppmanual
 The nine trigraphs and their replacements are
 
 @smallexample
@@ -808,23 +713,15 @@ Replacement:      [    ]    @{    @}    #    \    ^    |    ~
 @end smallexample
 @end ifclear
 
+By default, GCC ignores trigraphs, but in
+standard-conforming modes it converts them.  See the @option{-std} and
+@option{-ansi} options.
+
 @item -remap
 @opindex remap
 Enable special code to work around file systems which only permit very
 short file names, such as MS-DOS@.
 
-@item --help
-@itemx --target-help
-@opindex help
-@opindex target-help
-Print text describing all the command-line options instead of
-preprocessing anything.
-
-@item -v
-@opindex v
-Verbose mode.  Print out GNU CPP's version number at the beginning of
-execution, and report the final form of the include path.
-
 @item -H
 @opindex H
 Print the name of each header file used, in addition to other normal
@@ -833,9 +730,3 @@ activities.  Each name is indented to show how deep in the
 printed, even if they are found to be invalid; an invalid precompiled
 header file is printed with @samp{...x} and a valid one with @samp{...!} .
 
-@item -version
-@itemx --version
-@opindex version
-Print out GNU CPP's version number.  With one dash, proceed to
-preprocess as normal.  With two dashes, exit immediately.
-@end table

gcc/doc/invoke.texi

@@ -185,8 +185,7 @@ in the following sections.
 -fms-extensions -fplan9-extensions -fsso-struct=@var{endianness}
 -fallow-single-precision  -fcond-mismatch -flax-vector-conversions @gol
 -fsigned-bitfields  -fsigned-char @gol
--funsigned-bitfields  -funsigned-char @gol
--trigraphs -traditional -traditional-cpp}
+-funsigned-bitfields  -funsigned-char}
 
 @item C++ Language Options
 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
@@ -472,7 +471,8 @@ Objective-C and Objective-C++ Dialects}.
 -imultilib @var{dir} -isysroot @var{dir} @gol
 -M  -MM  -MF  -MG  -MP  -MQ  -MT  -nostdinc  @gol
 -P  -fdebug-cpp -ftrack-macro-expansion -fworking-directory @gol
--remap -trigraphs  -undef  -U@var{macro}  @gol
+-remap -traditional -traditional-cpp -trigraphs  @gol
+-undef  -U@var{macro}  @gol
 -Wp,@var{option} -Xpreprocessor @var{option} -no-integrated-cpp}
 
 @item Assembler Option
@@ -2101,22 +2101,6 @@ fields declared using a typedef.  @xref{Unnamed Fields,,Unnamed
 struct/union fields within structs/unions}, for details.  This is only
 supported for C, not C++.
 
-@item -trigraphs
-@opindex trigraphs
-Support ISO C trigraphs.  The @option{-ansi} option (and @option{-std}
-options for strict ISO C conformance) implies @option{-trigraphs}.
-
-@cindex traditional C language
-@cindex C language, traditional
-@item -traditional
-@itemx -traditional-cpp
-@opindex traditional-cpp
-@opindex traditional
-Formerly, these options caused GCC to attempt to emulate a pre-standard
-C compiler.  They are now only supported with the @option{-E} switch.
-The preprocessor continues to support a pre-standard mode.  See the GNU
-CPP manual for details.
-
 @item -fcond-mismatch
 @opindex fcond-mismatch
 Allow conditional expressions with mismatched types in the second and
@@ -3838,13 +3822,6 @@ of error, as programmers often forget that this type is signed on some
 machines.
 This warning is enabled by @option{-Wall}.
 
-@item -Wcomment
-@opindex Wcomment
-@opindex Wno-comment
-Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
-comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
-This warning is enabled by @option{-Wall}.
-
 @item -Wno-coverage-mismatch
 @opindex Wno-coverage-mismatch
 Warn if feedback profiles do not match when using the
@@ -4610,13 +4587,6 @@ This warning is enabled by default for C and C++ programs.
 Warn when @code{__sync_fetch_and_nand} and @code{__sync_nand_and_fetch}
 built-in functions are used.  These functions changed semantics in GCC 4.4.
 
-@item -Wtrigraphs
-@opindex Wtrigraphs
-@opindex Wno-trigraphs
-Warn if any trigraphs are encountered that might change the meaning of
-the program (trigraphs within comments are not warned about).
-This warning is enabled by @option{-Wall}.
-
 @item -Wunused-but-set-parameter
 @opindex Wunused-but-set-parameter
 @opindex Wno-unused-but-set-parameter
@@ -5458,21 +5428,6 @@ Warn when a declaration is found after a statement in a block.  This
 construct, known from C++, was introduced with ISO C99 and is by default
 allowed in GCC@.  It is not supported by ISO C90.  @xref{Mixed Declarations}.
 
-@item -Wexpansion-to-defined
-@opindex Wexpansion-to-defined
-Warn whenever @samp{defined} is encountered in the expansion of a macro.
-This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}.
-
-@item -Wundef
-@opindex Wundef
-@opindex Wno-undef
-Warn if an undefined identifier is evaluated in an @code{#if} directive.
-
-@item -Wno-endif-labels
-@opindex Wno-endif-labels
-@opindex Wendif-labels
-Do not warn whenever an @code{#else} or an @code{#endif} are followed by text.
-
 @item -Wshadow
 @opindex Wshadow
 @opindex Wno-shadow
@@ -11371,9 +11326,9 @@ This option may be useful in conjunction with the @option{-B} or
 @option{-wrapper} options to specify an alternate preprocessor or
 perform additional processing of the program source between
 normal preprocessing and compilation.
-@end table
 
 @include cppopts.texi
+@end table
 
 @node Assembler Options
 @section Passing Options to the Assembler