[doc, committed] reorder entries in cppopts.texi

[Sandra Loosemore <sandra at codesourcery dot com>]

I've checked in the attached patch to reorder entries in cppopts.texi. 
I put the most-commonly-used options (e.g. -D and -U) first, and the 
options for debugging cpp last, and tried to group the things in between 
a little better.

There's no change to actual content here, just the ordering.

-Sandra

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

	gcc/
	* doc/cppopts.texi: Reorder table entries to put the most 
	commonly-used options first and debug options last.

Index: gcc/doc/cppopts.texi
===================================================================
--- gcc/doc/cppopts.texi	(revision 243983)
+++ gcc/doc/cppopts.texi	(working copy)
@@ -39,6 +39,28 @@ are given on the command line.  All @opt
 Cancel any previous definition of @var{name}, either built in or
 provided with a @option{-D} option.
 
+@item -include @var{file}
+@opindex include
+Process @var{file} as if @code{#include "file"} appeared as the first
+line of the primary source file.  However, the first directory searched
+for @var{file} is the preprocessor's working directory @emph{instead of}
+the directory containing the main source file.  If not found there, it
+is searched for in the remainder of the @code{#include "@dots{}"} search
+chain as normal.
+
+If multiple @option{-include} options are given, the files are included
+in the order they appear on the command line.
+
+@item -imacros @var{file}
+@opindex imacros
+Exactly like @option{-include}, except that any output produced by
+scanning @var{file} is thrown away.  Macros it defines remain defined.
+This allows you to acquire all the macros from a header without also
+processing its declarations.
+
+All files specified by @option{-imacros} are processed before all files
+specified by @option{-include}.
+
 @item -undef
 @opindex undef
 Do not predefine any system-specific or GCC-specific macros.  The
@@ -177,57 +199,21 @@ a dependency output file as a side-effec
 Like @option{-MD} except mention only user header files, not system
 header files.
 
-@ifclear cppmanual
-@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
-header is used.
-
-@item -fpch-preprocess
-@opindex fpch-preprocess
-This option allows use of a precompiled header (@pxref{Precompiled
-Headers}) together with @option{-E}.  It inserts a special @code{#pragma},
-@code{#pragma GCC pch_preprocess "@var{filename}"} in the output to mark
-the place where the precompiled header was found, and its @var{filename}.
-When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma}
-and loads the PCH@.
+@item -fpreprocessed
+@opindex fpreprocessed
+Indicate to the preprocessor that the input file has already been
+preprocessed.  This suppresses things like macro expansion, trigraph
+conversion, escaped newline splicing, and processing of most directives.
+The preprocessor still recognizes and removes comments, so that you can
+pass a file preprocessed with @option{-C} to the compiler without
+problems.  In this mode the integrated preprocessor is little more than
+a tokenizer for the front ends.
 
-This option is off by default, because the resulting preprocessed output
-is only really suitable as input to GCC@.  It is switched on by
+@option{-fpreprocessed} is implicit if the input file has one of the
+extensions @samp{.i}, @samp{.ii} or @samp{.mi}.  These are the
+extensions that GCC uses for preprocessed files created by
 @option{-save-temps}.
 
-You should not write this @code{#pragma} in your own code, but it is
-safe to edit the filename if the PCH file is available in a different
-location.  The filename may be absolute or it may be relative to GCC's
-current directory.
-@end ifclear
-
-@item -include @var{file}
-@opindex include
-Process @var{file} as if @code{#include "file"} appeared as the first
-line of the primary source file.  However, the first directory searched
-for @var{file} is the preprocessor's working directory @emph{instead of}
-the directory containing the main source file.  If not found there, it
-is searched for in the remainder of the @code{#include "@dots{}"} search
-chain as normal.
-
-If multiple @option{-include} options are given, the files are included
-in the order they appear on the command line.
-
-@item -imacros @var{file}
-@opindex imacros
-Exactly like @option{-include}, except that any output produced by
-scanning @var{file} is thrown away.  Macros it defines remain defined.
-This allows you to acquire all the macros from a header without also
-processing its declarations.
-
-All files specified by @option{-imacros} are processed before all files
-specified by @option{-include}.
-
 @item -fdirectives-only
 @opindex fdirectives-only
 When preprocessing, handle directives, but do not expand macros.
@@ -267,21 +253,6 @@ enabled by default for C99 (and later C
 @opindex fno-canonical-system-headers
 When preprocessing, do not shorten system header paths with canonicalization.
 
-@item -fpreprocessed
-@opindex fpreprocessed
-Indicate to the preprocessor that the input file has already been
-preprocessed.  This suppresses things like macro expansion, trigraph
-conversion, escaped newline splicing, and processing of most directives.
-The preprocessor still recognizes and removes comments, so that you can
-pass a file preprocessed with @option{-C} to the compiler without
-problems.  In this mode the integrated preprocessor is little more than
-a tokenizer for the front ends.
-
-@option{-fpreprocessed} is implicit if the input file has one of the
-extensions @samp{.i}, @samp{.ii} or @samp{.mi}.  These are the
-extensions that GCC uses for preprocessed files created by
-@option{-save-temps}.
-
 @item -ftabstop=@var{width}
 @opindex ftabstop
 Set the distance between tab stops.  This helps the preprocessor report
@@ -289,19 +260,6 @@ correct column numbers in warnings or er
 line.  If the value is less than 1 or greater than 100, the option is
 ignored.  The default is 8.
 
-@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
-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
-
-When used without @option{-E}, this option has no effect.
-
 @item -ftrack-macro-expansion@r{[}=@var{level}@r{]}
 @opindex ftrack-macro-expansion
 Track locations of tokens across macro expansions. This allows the
@@ -350,6 +308,35 @@ or this command-line option.  Currently
 precedence if there's a conflict.  @var{charset} can be any encoding
 supported by the system's @code{iconv} library routine.
 
+@ifclear cppmanual
+@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
+header is used.
+
+@item -fpch-preprocess
+@opindex fpch-preprocess
+This option allows use of a precompiled header (@pxref{Precompiled
+Headers}) together with @option{-E}.  It inserts a special @code{#pragma},
+@code{#pragma GCC pch_preprocess "@var{filename}"} in the output to mark
+the place where the precompiled header was found, and its @var{filename}.
+When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma}
+and loads the PCH@.
+
+This option is off by default, because the resulting preprocessed output
+is only really suitable as input to GCC@.  It is switched on by
+@option{-save-temps}.
+
+You should not write this @code{#pragma} in your own code, but it is
+safe to edit the filename if the PCH file is available in a different
+location.  The filename may be absolute or it may be relative to GCC's
+current directory.
+@end ifclear
+
 @item -fworking-directory
 @opindex fworking-directory
 @opindex fno-working-directory
@@ -380,70 +367,6 @@ it does not use shell special characters
 Cancel an assertion with the predicate @var{predicate} and answer
 @var{answer}.
 
-@item -dCHARS
-@var{CHARS} is a sequence of one or more of the following characters,
-and must not be preceded by a space.  Other characters are interpreted
-by the compiler proper, or reserved for future versions of GCC, and so
-are silently ignored.  If you specify characters whose behavior
-conflicts, the result is undefined.
-
-@table @samp
-@item M
-@opindex dM
-Instead of the normal output, generate a list of @samp{#define}
-directives for all the macros defined during the execution of the
-preprocessor, including predefined macros.  This gives you a way of
-finding out what is predefined in your version of the preprocessor.
-Assuming you have no file @file{foo.h}, the command
-
-@smallexample
-touch foo.h; cpp -dM foo.h
-@end smallexample
-
-@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
-Like @samp{M} except in two respects: it does @emph{not} include the
-predefined macros, and it outputs @emph{both} the @samp{#define}
-directives and the result of preprocessing.  Both kinds of output go to
-the standard output file.
-
-@item N
-@opindex dN
-Like @samp{D}, but emit only the macro names, not their expansions.
-
-@item I
-@opindex dI
-Output @samp{#include} directives in addition to the result of
-preprocessing.
-
-@item U
-@opindex dU
-Like @samp{D} except that only macros that are expanded, or whose
-definedness is tested in preprocessor directives, are output; the
-output is delayed until the use or test of the macro; and
-@samp{#undef} directives are also output for macros tested but
-undefined at the time.
-@end table
-
-@item -P
-@opindex P
-Inhibit generation of linemarkers in the output from the preprocessor.
-This might be useful when running the preprocessor on something that is
-not C code, and will be sent to a program which might be confused by the
-linemarkers.
-@ifset cppmanual
-@xref{Preprocessor Output}.
-@end ifset
-
 @item -C
 @opindex C
 Do not discard comments.  All comments are passed through to the output
@@ -469,6 +392,16 @@ the source line.
 
 The @option{-CC} option is generally used to support lint comments.
 
+@item -P
+@opindex P
+Inhibit generation of linemarkers in the output from the preprocessor.
+This might be useful when running the preprocessor on something that is
+not C code, and will be sent to a program which might be confused by the
+linemarkers.
+@ifset cppmanual
+@xref{Preprocessor Output}.
+@end ifset
+
 @cindex traditional C language
 @cindex C language, traditional
 @item -traditional
@@ -526,3 +459,70 @@ activities.  Each name is indented to sh
 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 -dCHARS
+@var{CHARS} is a sequence of one or more of the following characters,
+and must not be preceded by a space.  Other characters are interpreted
+by the compiler proper, or reserved for future versions of GCC, and so
+are silently ignored.  If you specify characters whose behavior
+conflicts, the result is undefined.
+
+@table @samp
+@item M
+@opindex dM
+Instead of the normal output, generate a list of @samp{#define}
+directives for all the macros defined during the execution of the
+preprocessor, including predefined macros.  This gives you a way of
+finding out what is predefined in your version of the preprocessor.
+Assuming you have no file @file{foo.h}, the command
+
+@smallexample
+touch foo.h; cpp -dM foo.h
+@end smallexample
+
+@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
+Like @samp{M} except in two respects: it does @emph{not} include the
+predefined macros, and it outputs @emph{both} the @samp{#define}
+directives and the result of preprocessing.  Both kinds of output go to
+the standard output file.
+
+@item N
+@opindex dN
+Like @samp{D}, but emit only the macro names, not their expansions.
+
+@item I
+@opindex dI
+Output @samp{#include} directives in addition to the result of
+preprocessing.
+
+@item U
+@opindex dU
+Like @samp{D} except that only macros that are expanded, or whose
+definedness is tested in preprocessor directives, are output; the
+output is delayed until the use or test of the macro; and
+@samp{#undef} directives are also output for macros tested but
+undefined at the time.
+@end table
+
+@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
+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
+
+When used without @option{-E}, this option has no effect.
+