I am about to start a project to incrementally move chunks of
invoke.texi around to better organize this very long chapter of the
manual. For reference, the current top-level structure looks like this:
@chapter GCC Command Options
@section Option Summary
@section Options Controlling the Kind of Output
@section Compiling C++ Programs
@section Options Controlling C Dialect
@section Options Controlling C++ Dialect
@section Options Controlling Objective-C and Objective-C++ Dialects
@section Options to Control Diagnostic Messages Formatting
@section Options to Request or Suppress Warnings
@section Options for Debugging Your Program or GCC
@section Options That Control Optimization
@section Options Controlling the Preprocessor
@section Passing Options to the Assembler
@section Options for Linking
@section Options for Directory Search
@section Specifying Subprocesses and the Switches to Pass to Them
@section Specifying Target Machine and Compiler Version
@section Hardware Models and Configurations
@section Options for Code Generation Conventions
@section Environment Variables Affecting GCC
@section Using Precompiled Headers
Here's what I'm planning:
1. Integrate the 1-paragraph section "Specifying Target Machine and
Compiler Version" into the top-level introduction. (This paragraph
essentially just says that the name of the program is "gcc" or
"<target>-gcc".)
2. Move "Specifying Subprocesses and the Switches to Pass to Them"
(which is about spec file details) to the end of the chapter.
3. Move "Options for Code Generation Conventions" ahead of "Hardware
Models and Configurations", which is where target-specific options are
covered -- the idea being to cover all the target-independent options
before the target-specific ones.
4. Move "Using Precompiled Headers" to extend.texi. There's nothing in
this section about "GCC Command Options" (it's about search paths,
consistency rules, etc for PCH files.)
5. Create a new section "Program Instrumentation Options" and
consolidate all the options relevant to profiling, run-time error
checking, and related functionality there from the various sections
where they now reside. This includes -fvtable-verify, -fsanitize and
friends, -fcheck-pointer-bounds and friends, stack checking, etc.
6. Split "Options for Debugging Your Program or GCC" into two separate
sections, since it seems to me that options for enabling or controlling
DWARF generation (etc) are of interest to a much different audience than
all the options for controlling dumps, compiler statistics, etc.
Any complaints about this plan? Please speak up ASAP if you have other
suggestions!
-Sandra
