[PATCH] Optimization docs part 3

[Jerry Quinn <jlquinn at optonline dot net>]

This patch groups the floating point flags together.  They are spread
out in several places currently.  It's identical to the version OK'd
by Geoff Keating in
http://gcc.gnu.org/ml/gcc-patches/2002-09/msg00954.html
modulo line numbers and the changelog entry.

This patch is also against the 3.3 branch.

2002-12-17  Jerry Quinn  <jlquinn@optonline.net>

	* gcc/doc/invoke.texi (Optimization Options): Group floating
	  point flags together.


--- invoke.texi.p3	Tue Dec 17 01:04:36 2002
+++ invoke.texi	Tue Dec 17 01:18:20 2002
@@ -3487,21 +3487,6 @@
 adding it.
 
 @table @gcctabopt
-@item -ffloat-store
-@opindex ffloat-store
-Do not store floating point variables in registers, and inhibit other
-options that might change whether a floating point value is taken from a
-register or memory.
-
-@cindex floating point precision
-This option prevents undesirable excess precision on machines such as
-the 68000 where the floating registers (of the 68881) keep more
-precision than a @code{double} is supposed to have.  Similarly for the
-x86 architecture.  For most programs, the excess precision does only
-good, but a few programs rely on the precise definition of IEEE floating
-point.  Use @option{-ffloat-store} for such programs, after modifying
-them to store all pertinent intermediate computations into variables.
-
 @item -fno-default-inline
 @opindex fno-default-inline
 Do not make member functions inline by default merely because they are
@@ -3664,89 +3649,6 @@
 
 The default is @option{-ffunction-cse}
 
-@item -ffast-math
-@opindex ffast-math
-Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
-@option{-fno-trapping-math}, @option{-ffinite-math-only} and @*
-@option{-fno-signaling-nans}.
-
-This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions.
-
-@item -fno-math-errno
-@opindex fno-math-errno
-Do not set ERRNO after calling math functions that are executed
-with a single instruction, e.g., sqrt.  A program that relies on
-IEEE exceptions for math error handling may want to use this flag
-for speed while maintaining IEEE arithmetic compatibility.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions.
-
-The default is @option{-fmath-errno}.
-
-@item -funsafe-math-optimizations
-@opindex funsafe-math-optimizations
-Allow optimizations for floating-point arithmetic that (a) assume
-that arguments and results are valid and (b) may violate IEEE or
-ANSI standards.  When used at link-time, it may include libraries
-or startup files that change the default FPU control word or other
-similar optimizations.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions.
-
-The default is @option{-fno-unsafe-math-optimizations}.
-
-@item -ffinite-math-only
-@opindex ffinite-math-only
-Allow optimizations for floating-point arithmetic that assume
-that arguments and results are not NaNs or +-Infs.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications.
-
-The default is @option{-fno-finite-math-only}.
-
-@item -fno-trapping-math
-@opindex fno-trapping-math
-Compile code assuming that floating-point operations cannot generate
-user-visible traps.  These traps include division by zero, overflow,
-underflow, inexact result and invalid operation.  This option implies
-@option{-fno-signaling-nans}.  Setting this option may allow faster
-code if one relies on ``non-stop'' IEEE arithmetic, for example.
-
-This option should never be turned on by any @option{-O} option since
-it can result in incorrect output for programs which depend on
-an exact implementation of IEEE or ISO rules/specifications for
-math functions.
-
-The default is @option{-ftrapping-math}.
-
-@item -fsignaling-nans
-@opindex fsignaling-nans
-Compile code assuming that IEEE signaling NaNs may generate user-visible
-traps during floating-point operations.  Setting this option disables
-optimizations that may change the number of exceptions visible with
-signaling NaNs.  This option implies @option{-ftrapping-math}.
-
-This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
-be defined.
-
-The default is @option{-fno-signaling-nans}.
-
-This option is experimental and does not currently guarantee to
-disable all GCC optimizations that affect signaling NaN behavior.
-
 @item -fno-zero-initialized-in-bss
 @opindex fno-zero-initialized-in-bss
 If the target supports a BSS section, GCC by default puts variables that
@@ -4262,11 +4164,6 @@
 Perform aggressive dead-code elimination in SSA form.  Requires @option{-fssa}.
 Like @option{-fssa}, this is an experimental feature.
 
-@item -fsingle-precision-constant
-@opindex fsingle-precision-constant
-Treat floating point constant as single precision constant instead of
-implicitly converting it to double precision constant.
-
 @item -frename-registers
 @opindex frename-registers
 Attempt to avoid false dependencies in scheduled code by making use
@@ -4284,6 +4181,116 @@
 and occasionally eliminate the copy.
 
 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
+
+@end table
+
+The following options control compiler behavior regarding floating
+point arithmetic.  These options trade off between speed and
+correctness.  All must be specifically enabled.
+
+@table @gcctabopt
+@item -ffloat-store
+@opindex ffloat-store
+Do not store floating point variables in registers, and inhibit other
+options that might change whether a floating point value is taken from a
+register or memory.
+
+@cindex floating point precision
+This option prevents undesirable excess precision on machines such as
+the 68000 where the floating registers (of the 68881) keep more
+precision than a @code{double} is supposed to have.  Similarly for the
+x86 architecture.  For most programs, the excess precision does only
+good, but a few programs rely on the precise definition of IEEE floating
+point.  Use @option{-ffloat-store} for such programs, after modifying
+them to store all pertinent intermediate computations into variables.
+
+@item -ffast-math
+@opindex ffast-math
+Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
+@option{-fno-trapping-math}, @option{-ffinite-math-only} and @*
+@option{-fno-signaling-nans}.
+
+This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications for
+math functions.
+
+@item -fno-math-errno
+@opindex fno-math-errno
+Do not set ERRNO after calling math functions that are executed
+with a single instruction, e.g., sqrt.  A program that relies on
+IEEE exceptions for math error handling may want to use this flag
+for speed while maintaining IEEE arithmetic compatibility.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications for
+math functions.
+
+The default is @option{-fmath-errno}.
+
+@item -funsafe-math-optimizations
+@opindex funsafe-math-optimizations
+Allow optimizations for floating-point arithmetic that (a) assume
+that arguments and results are valid and (b) may violate IEEE or
+ANSI standards.  When used at link-time, it may include libraries
+or startup files that change the default FPU control word or other
+similar optimizations.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications for
+math functions.
+
+The default is @option{-fno-unsafe-math-optimizations}.
+
+@item -ffinite-math-only
+@opindex ffinite-math-only
+Allow optimizations for floating-point arithmetic that assume
+that arguments and results are not NaNs or +-Infs.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications.
+
+The default is @option{-fno-finite-math-only}.
+
+@item -fno-trapping-math
+@opindex fno-trapping-math
+Compile code assuming that floating-point operations cannot generate
+user-visible traps.  These traps include division by zero, overflow,
+underflow, inexact result and invalid operation.  This option implies
+@option{-fno-signaling-nans}.  Setting this option may allow faster
+code if one relies on ``non-stop'' IEEE arithmetic, for example.
+
+This option should never be turned on by any @option{-O} option since
+it can result in incorrect output for programs which depend on
+an exact implementation of IEEE or ISO rules/specifications for
+math functions.
+
+The default is @option{-ftrapping-math}.
+
+@item -fsignaling-nans
+@opindex fsignaling-nans
+Compile code assuming that IEEE signaling NaNs may generate user-visible
+traps during floating-point operations.  Setting this option disables
+optimizations that may change the number of exceptions visible with
+signaling NaNs.  This option implies @option{-ftrapping-math}.
+
+This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
+be defined.
+
+The default is @option{-fno-signaling-nans}.
+
+This option is experimental and does not currently guarantee to
+disable all GCC optimizations that affect signaling NaN behavior.
+
+@item -fsingle-precision-constant
+@opindex fsingle-precision-constant
+Treat floating point constant as single precision constant instead of
+implicitly converting it to double precision constant.
 
 @item --param @var{name}=@var{value}
 @opindex param