organization of optimization options in manual

[Jeff Law]

On 01/14/15 16:48, Sandra Loosemore wrote:
> The "Options That Control Optimization" section of the manual is
> currently divided into three parts (not subsections, just separate
> option lists):
>
> (1) General options like -O[n]
>
> (2) Options that individually control options enabled by default at some
> -O[n] setting
>
> (3) Options controlling optimizations that aren't enabled by default, or
> that are experimental
>
> I've noted that a lot of options that belong in group (3) have been
> added to group (2), and at least one from (2) into group (3).  I'm
> thinking that the distinction between (2) and (3) is not really useful
> anyway; there are already both lists of which options are enabled at
> each -O level, and info in the descriptions of individual options to say
> what -O levels they're enabled at.
>
> What would you think about reorganizing this section to add some
> subsections grouping options by purpose, instead?  E.g., loop
> optimizations, floating-point optimizations, inlining, LTO, profiling
> options, etc?  The section is almost 60 pages long in the printed manual
> and adding some structure would probably make it easier for users to
> find things.
>
> The other option would be just to list the options alphabetically, but
> the index already does that if readers know the name of what they're
> looking for (or they can search for it in their browser).
With the section being ~60 pages, my first thought is we have way too 
many options!  But that's not likely to change.  Though perhaps the 
process will encourage some culling of options that really don't make 
sense anymore.

I think it's really just grown organically and putting more structure 
into it would probably be worth the effort.  The question I have is once 
we've identified the high level buckets, how much stuff are we likely 
going to have in the miscellaneous bucket.  If the misc bucket is still 
big then folks are still going to struggle with finding the information 
they want/need (or think they want/need).



Jeff