[PATCH] optimization docs reorg

[Jerome L Quinn <jlquinn at us dot ibm dot com>]

Hi, All.  I've been frustrated for a long time by the docs on the
optimization
flags in gcc.  In particular, the wording is very unclear and in fact wrong
in
 some places regarding which flags are active at what optimization levels.

Finally taking matters in my own hands, I reworked the section so that it
at
least makes more sense to me.  It also correlates with the main line as of
a
couple of days ago.

There are six patches:

patch 1: minor grammar and spelling fixes
patch 2: Explicitly list the flags active at each -O level
patch 3: For each flag, list the levels it is active at, if any
patch 4: Regroup the floating point flags together
         None are enabled by default, so they make sense together
patch 5: Regroup other experimental and non-default flags together
patch 6: Clean up description of O2 in particular and regroups a few more
flags.

I don't have an FSF approval filed, so I hope this stuff is small enough to
go in (assuming people like it).

Here is the first patch:

2002-08-30 Jerry Quinn <jlquinn@us.ibm.com>
      * gcc/gcc/doc/invoke.texi (Optimization Options): Fix grammar and
spelling.

--- gcc/gcc/doc/invoke.texi.orig           2002-08-25 00:26:03.000000000
-0400
+++ gcc/gcc/doc/invoke.texi          2002-08-25 01:02:16.000000000 -0400
@@ -3329,7 +3329,7 @@
 @opindex finline-limit
 By default, gcc limits the size of functions that can be inlined.  This
flag
 allows the control of this limit for functions that are explicitly marked
as
-inline (ie marked with the inline keyword or defined within the class
+inline (i.e., marked with the inline keyword or defined within the class
 definition in c++).  @var{n} is the size of functions that can be inlined
in
 number of pseudo instructions (not counting parameter handling).  The
default
 value of @var{n} is 600.
@@ -3362,10 +3362,11 @@

 @item -fmerge-constants
 Attempt to merge identical constants (string constants and floating point
-constants) accross compilation units.
+constants) across compilation units.

-This option is default for optimized compilation if assembler and linker
-support it.  Use @option{-fno-merge-constants} to inhibit this behavior.
+This option is the default for optimized compilation if assembler and
+linker support it.  Use @option{-fno-merge-constants} to inhibit this
+behavior.

 @item -fmerge-all-constants
 Attempt to merge identical constants and identical variables.
@@ -3547,7 +3548,7 @@

 @emph{Note:} When compiling a program using computed gotos, a GCC
 extension, you may get better runtime performance if you disable
-the global common subexpression elmination pass by adding
+the global common subexpression elimination pass by adding
 @option{-fno-gcse} to the command line.

 @item -fgcse-lm
@@ -3782,7 +3783,7 @@
 subsections @code{text.hot} for most frequently executed functions and
 @code{text.unlikely} for unlikely executed functions.  Reordering is done
by
 the linker so object file format must support named sections and linker
must
-place them in resonable way.
+place them in a reasonable way.

 Also profile feedback must be available in to make this option effective.
See
 @option{-fprofile-arcs} for details.
@@ -3987,7 +3988,7 @@
 @itemx tracer-dynamic-coverage-feedback

 This value is used to limit superblock formation once given percentage of
-executed instructions is covered.  This limits unnecesary code size
expansion.
+executed instructions is covered.  This limits unnecessary code size
expansion.

 The @option{tracer-dynamic-coverage-feedback} is used only when profile
 feedback is available.  The real profiles (as opposed to statically
estimated
@@ -3995,7 +3996,7 @@

 @item tracer-max-code-growth
 Stop tail duplication once code growth has reached given percentage.  This
is
-rather hokey argument, as most of the duplicates will be elliminated later
in
+rather hokey argument, as most of the duplicates will be eliminated later
in
 cross jumping, so it may be set to much higher values than is the desired
code
 growth.

@@ -4010,7 +4011,7 @@
 Stop forward growth if the best edge do have probability lower than this
 threshold.

-Similary to @option{tracer-dynamic-coverage} two values are present, one
for
+Similarly to @option{tracer-dynamic-coverage} two values are present, one
for
 compilation for profile feedback and one for compilation without.  The
value
 for compilation with profile feedback needs to be more conservative
(higher) in
 order to make tracer effective.