Re: [PATCH] optimization docs part 2

[Geoff Keating <geoffk at geoffk dot org>]

Jerome L Quinn <jlquinn@us.ibm.com> writes:

> Here's the flag listing for the -O flags.  I scanned the sources to try to
> get these lists right, but there may still be errors.  Please let me know
> and I'll fix up the lists to match reality.

This patch also requires an assignment.

> 2002-08-30 Jerry Quinn <jlquinn@us.ibm.com>
>       * gcc/gcc/doc/invoke.texi (Optimization Options): List the options
> enabled by each -O flag.

Please make sure that the ChangeLog entry you finally commit is
properly formatted: two spaces after the date and between the name and
the e-mail address, one blank line after the header line, and one tab
before every line of the body.

> --- gcc/gcc/doc/invoke.texi.safe           2002-08-25 01:03:45.000000000
> -0400
> +++ gcc/gcc/doc/invoke.texi          2002-08-25 01:05:21.000000000 -0400
> @@ -3196,6 +3196,22 @@
>  time, without performing any optimizations that take a great deal of
>  compilation time.
> 
> +@option{-O} turns on the following optimizations:

I would say "turns on the following optimization flags", instead,
since this isn't a complete list of optimizations that are switched on by
-O1, only those that have separate flags.

> +@gccoptlist{-fdefer-pop
> +-fmerge-constants
> +-fthread-jumps
> +-floop-optimize
> +-fcrossjumping
> +-fif-conversion
> +-fif-conversion2
> +-fdelayed-branch
> +-fguess-branch-probability
> +-fcprop-registers}
> +
> +@option{-O} also turns on @option{-fomit-frame-pointer} on machines
> +where doing so does not interfere with debugging.
> +
> +

Why the two new blank lines here?

>  @item -O0
>  @opindex O0
> -Do not optimize.
> +Do not optimize.  This is equivalent to not using any optimization flags.

I think it would be clearer to write "This is the default.".  -O0 is
not the same as -O1 followed by -fno-defer-pop and so on.

>  @item -Os
>  @opindex Os
> @@ -3229,6 +3258,11 @@
>  do not typically increase code size.  It also performs further
>  optimizations designed to reduce code size.
> 
> +@option{-Os} disables the following optimization flags:
> +@gccoptlist{-falign-functions  -falign-jumps  -falign-loops
> +-falign-labels  -fprefetch-loop-arrays}
> +
> +

Should this also say something like "This enables the following
optimisation flags" (plus a list of the flags)?

Thank you for trying to do this, I find the existing structure (where
flags are listed in order according to what -Ox flag enables them)
confusing myself, and I know others also find it confusing because they
keep putting new flags in the wrong place.

-- 
- Geoffrey Keating <geoffk@geoffk.org>