cppdiropts.texi: Merge documentation of -I, -iquote, -isystem, and -idirafter.

2017-01-07  Sandra Loosemore  <sandra@codesourcery.com>

	gcc/
	* doc/cppdiropts.texi: Merge documentation of -I, -iquote,
	-isystem, and -idirafter.  Copy-edit.
	* doc/cppopts.texi: Copy-edit.  Remove contradiction about 
	default for -ftrack-macro-expansion.  Delete obsolete and 
	badly-formatted implementation details about -fdebug-cpp output.
	* doc/cppwarnopts.texi: Copy-edit.

From-SVN: r244200

gcc/ChangeLog

+2017-01-07  Sandra Loosemore  <sandra@codesourcery.com>
+
+	* doc/cppdiropts.texi: Merge documentation of -I, -iquote,
+	-isystem, and -idirafter.  Copy-edit.
+	* doc/cppopts.texi: Copy-edit.  Remove contradiction about 
+	default for -ftrack-macro-expansion.  Delete obsolete and 
+	badly-formatted implementation details about -fdebug-cpp output.
+	* doc/cppwarnopts.texi: Copy-edit.
+
 2017-01-07  David Malcolm  <dmalcolm@redhat.com>
 
 	PR c++/72803

gcc/doc/cppdiropts.texi

@@ -10,61 +10,85 @@
 @c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
 
 @item -I @var{dir}
+@itemx -iquote @var{dir}
+@itemx -isystem @var{dir}
+@itemx -idirafter @var{dir}
 @opindex I
+@opindex iquote
+@opindex isystem
+@opindex idirafter
 Add the directory @var{dir} to the list of directories to be searched
-for header files.
+for header files during preprocessing.
 @ifset cppmanual
 @xref{Search Path}.
 @end ifset
-If you use more than
-one @option{-I} option, the directories are scanned in left-to-right
-order; the standard system directories come after.
+If @var{dir} begins with @samp{=}, then the @samp{=} is replaced
+by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
+
+Directories specified with @option{-iquote} apply only to the quote 
+form of the directive, @code{@w{#include "@var{file}"}}.
+Directories specified with @option{-I}, @option{-isystem}, 
+or @option{-idirafter} apply to lookup for both the
+@code{@w{#include "@var{file}"}} and
+@code{@w{#include <@var{file}>}} directives.
+
+You can specify any number or combination of these options on the 
+command line to search for header files in several directories.  
+The lookup order is as follows:
+
+@enumerate
+@item
+For the quote form of the include directive, the directory of the current
+file is searched first.
+
+@item
+For the quote form of the include directive, the directories specified
+by @option{-iquote} options are searched in left-to-right order,
+as they appear on the command line.
+
+@item
+Directories specified with @option{-I} options are scanned in
+left-to-right order.
 
-This can be used to override a system header
+@item
+Directories specified with @option{-isystem} options are scanned in
+left-to-right order.
+
+@item
+Standard system directories are scanned.
+
+@item
+Directories specified with @option{-idirafter} options are scanned in
+left-to-right order.
+@end enumerate
+
+You can use @option{-I} to override a system header
 file, substituting your own version, since these directories are
-searched before the system header file directories.  However, you should
+searched before the standard system header file directories.  
+However, you should
 not use this option to add directories that contain vendor-supplied
-system header files (use @option{-isystem} for that).
+system header files; use @option{-isystem} for that.
+
+The @option{-isystem} and @option{-idirafter} options also mark the directory
+as a system directory, so that it gets the same special treatment that
+is applied to the standard system directories.
+@ifset cppmanual
+@xref{System Headers}.
+@end ifset
 
 If a standard system include directory, or a directory specified with
 @option{-isystem}, is also specified with @option{-I}, the @option{-I}
 option is ignored.  The directory is still searched but as a
 system directory at its normal position in the system include chain.
 This is to ensure that GCC's procedure to fix buggy system headers and
-the ordering for the @code{include_next} directive are not inadvertently changed.
+the ordering for the @code{#include_next} directive are not inadvertently
+changed.
 If you really need to change the search order for system directories,
 use the @option{-nostdinc} and/or @option{-isystem} options.
 @ifset cppmanual
 @xref{System Headers}.
 @end ifset
 
-If @var{dir} begins with @code{=}, then the @code{=} is replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
-@item -iquote @var{dir}
-@opindex iquote
-Search @var{dir} only for header files requested with
-@code{@w{#include "@var{file}"}}; they are not searched for
-@code{@w{#include <@var{file}>}}, before all directories specified by
-@option{-I} and before the standard system directories.
-@ifset cppmanual
-@xref{Search Path}.
-@end ifset
-If @var{dir} begins with @code{=}, then the @code{=} is replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
-@item -isystem @var{dir}
-@opindex isystem
-Search @var{dir} for header files, after all directories specified by
-@option{-I} but before the standard system directories.  Mark it
-as a system directory, so that it gets the same special treatment as
-is applied to the standard system directories.
-@ifset cppmanual
-@xref{System Headers}.
-@end ifset
-If @var{dir} begins with @code{=}, then the @code{=} is replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
 @item -I-
 @opindex I-
 Split the include path.
@@ -86,14 +110,6 @@ file directory as the first search directory for @code{@w{#include
 @xref{Search Path}.
 @end ifset
 
-@item -idirafter @var{dir}
-@opindex idirafter
-Search @var{dir} for header files, but do it @emph{after} all
-directories specified with @option{-I} and the standard system directories
-have been exhausted.  @var{dir} is treated as a system include directory.
-If @var{dir} begins with @code{=}, then the @code{=} will be replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
 @item -iprefix @var{prefix}
 @opindex iprefix
 Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
@@ -124,8 +140,10 @@ target-specific C++ headers.
 @item -nostdinc
 @opindex nostdinc
 Do not search the standard system directories for header files.
-Only the directories you have specified with @option{-I} options
-(and the directory of the current file, if appropriate) are searched.
+Only the directories explicitly specified with @option{-I},
+@option{-iquote}, @option{-isystem}, and/or @option{-idirafter}
+options (and the directory of the current file, if appropriate) 
+are searched.
 
 @item -nostdinc++
 @opindex nostdinc++

gcc/doc/cppopts.texi

@@ -16,7 +16,7 @@ Predefine @var{name} as a macro, with definition @code{1}.
 @item -D @var{name}=@var{definition}
 The contents of @var{definition} are tokenized and processed as if
 they appeared during translation phase three in a @samp{#define}
-directive.  In particular, the definition will be truncated by
+directive.  In particular, the definition is truncated by
 embedded newline characters.
 
 If you are invoking the preprocessor from a shell or shell-like
@@ -25,8 +25,8 @@ characters such as spaces that have a meaning in the shell syntax.
 
 If you wish to define a function-like macro on the command line, write
 its argument list with surrounding parentheses before the equals sign
-(if any).  Parentheses are meaningful to most shells, so you will need
-to quote the option.  With @command{sh} and @command{csh},
+(if any).  Parentheses are meaningful to most shells, so you should
+quote the option.  With @command{sh} and @command{csh},
 @option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
 
 @option{-D} and @option{-U} options are processed in the order they
@@ -92,7 +92,7 @@ This option does not suppress the preprocessor's debug output, such as
 rules you should explicitly specify the dependency output file with
 @option{-MF}, or use an environment variable like
 @env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}).  Debug output
-will still be sent to the regular output stream as normal.
+is still sent to the regular output stream as normal.
 
 Passing @option{-M} to the driver implies @option{-E}, and suppresses
 warnings with an implicit @option{-w}.
@@ -105,15 +105,14 @@ directly or indirectly, from such a header.
 
 This implies that the choice of angle brackets or double quotes in an
 @samp{#include} directive does not in itself determine whether that
-header will appear in @option{-MM} dependency output.  This is a
-slight change in semantics from GCC versions 3.0 and earlier.
+header appears in @option{-MM} dependency output.
 
 @anchor{dashMF}
 @item -MF @var{file}
 @opindex MF
 When used with @option{-M} or @option{-MM}, specifies a
 file to write the dependencies to.  If no @option{-MF} switch is given
-the preprocessor sends the rules to the same place it would have sent
+the preprocessor sends the rules to the same place it would send
 preprocessed output.
 
 When used with the driver options @option{-MD} or @option{-MMD},
@@ -154,7 +153,7 @@ default CPP takes the name of the main input file, deletes any
 directory components and any file suffix such as @samp{.c}, and
 appends the platform's usual object suffix.  The result is the target.
 
-An @option{-MT} option will set the target to be exactly the string you
+An @option{-MT} option sets the target to be exactly the string you
 specify.  If you want multiple targets, you can specify them as a single
 argument to @option{-MT}, or use multiple @option{-MT} options.
 
@@ -269,8 +268,7 @@ option makes the preprocessor and the compiler consume more
 memory. The @var{level} parameter can be used to choose the level of
 precision of token location tracking thus decreasing the memory
 consumption if necessary. Value @samp{0} of @var{level} de-activates
-this option just as if no @option{-ftrack-macro-expansion} was present
-on the command line. Value @samp{1} tracks tokens locations in a
+this option. Value @samp{1} tracks tokens locations in a
 degraded mode for the sake of minimal memory overhead. In this mode
 all tokens resulting from the expansion of an argument of a
 function-like macro have the same location. Value @samp{2} tracks
@@ -312,10 +310,10 @@ supported by the system's @code{iconv} library routine.
 @item -fpch-deps
 @opindex fpch-deps
 When using precompiled headers (@pxref{Precompiled Headers}), this flag
-will cause the dependency-output flags to also list the files from the
-precompiled header's dependencies.  If not specified only the
-precompiled header would be listed and not the files that were used to
-create it because those files are not consulted when a precompiled
+causes the dependency-output flags to also list the files from the
+precompiled header's dependencies.  If not specified, only the
+precompiled header are listed and not the files that were used to
+create it, because those files are not consulted when a precompiled
 header is used.
 
 @item -fpch-preprocess
@@ -340,11 +338,11 @@ current directory.
 @item -fworking-directory
 @opindex fworking-directory
 @opindex fno-working-directory
-Enable generation of linemarkers in the preprocessor output that will
+Enable generation of linemarkers in the preprocessor output that
 let the compiler know the current working directory at the time of
-preprocessing.  When this option is enabled, the preprocessor will
-emit, after the initial linemarker, a second linemarker with the
-current working directory followed by two slashes.  GCC will use this
+preprocessing.  When this option is enabled, the preprocessor
+emits, after the initial linemarker, a second linemarker with the
+current working directory followed by two slashes.  GCC uses this
 directory, when it's present in the preprocessed input, as the
 directory emitted as the current working directory in some debugging
 information formats.  This option is implicitly enabled if debugging
@@ -380,6 +378,7 @@ directive line have the effect of turning that line into an ordinary
 source line, since the first token on the line is no longer a @samp{#}.
 
 @item -CC
+@opindex CC
 Do not discard comments, including during macro expansion.  This is
 like @option{-C}, except that comments contained within macros are
 also passed through to the output file where the macro is expanded.
@@ -480,7 +479,7 @@ touch foo.h; cpp -dM foo.h
 @end smallexample
 
 @noindent
-will show all the predefined macros.
+shows all the predefined macros.
 
 @ifclear cppmanual
 If you use @option{-dM} without the @option{-E} option, @option{-dM} is
@@ -515,14 +514,10 @@ undefined at the time.
 
 @item -fdebug-cpp
 @opindex fdebug-cpp
-This option is only useful for debugging GCC.  When used with
-@option{-E}, dumps debugging information about location maps.  Every
+This option is only useful for debugging GCC.  When used from CPP or with
+@option{-E}, it dumps debugging information about location maps.  Every
 token in the output is preceded by the dump of the map its location
-belongs to.  The dump of the map holding the location of a token would
-be:
-@smallexample
-@{@samp{P}:@file{/file/path};@samp{F}:@file{/includer/path};@samp{L}:@var{line_num};@samp{C}:@var{col_num};@samp{S}:@var{system_header_p};@samp{M}:@var{map_address};@samp{E}:@var{macro_expansion_p},@samp{loc}:@var{location}@}
-@end smallexample
+belongs to.
 
-When used without @option{-E}, this option has no effect.
+When used from GCC without @option{-E}, this option has no effect.
 

gcc/doc/cppwarnopts.texi

@@ -46,14 +46,14 @@ This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}.
 @opindex Wunused-macros
 Warn about macros defined in the main file that are unused.  A macro
 is @dfn{used} if it is expanded or tested for existence at least once.
-The preprocessor will also warn if the macro has not been used at the
+The preprocessor also warns if the macro has not been used at the
 time it is redefined or undefined.
 
 Built-in macros, macros defined on the command line, and macros
 defined in include files are not warned about.
 
 @emph{Note:} If a macro is actually used, but only used in skipped
-conditional blocks, then CPP will report it as unused.  To avoid the
+conditional blocks, then the preprocessor reports it as unused.  To avoid the
 warning in such a case, you might improve the scope of the macro's
 definition by, for example, moving it into the first skipped block.
 Alternatively, you could provide a dummy use with something like:
@@ -67,7 +67,7 @@ Alternatively, you could provide a dummy use with something like:
 @opindex Wno-endif-labels
 @opindex Wendif-labels
 Do not warn whenever an @code{#else} or an @code{#endif} are followed by text.
-This usually happens in code of the form
+This sometimes happens in older programs with code of the form
 
 @smallexample
 #if FOO
@@ -78,6 +78,5 @@ This usually happens in code of the form
 @end smallexample
 
 @noindent
-The second and third @code{FOO} should be in comments, but often are not
-in older programs.  This warning is on by default.
-
+The second and third @code{FOO} should be in comments.
+This warning is on by default.