[GHC] #14214: Users guide lies about default optimization level

[GHC]

#14214: Users guide lies about default optimization level
-------------------------------------+-------------------------------------
        Reporter:  bgamari           |                Owner:  (none)
            Type:  bug               |               Status:  new
        Priority:  high              |            Milestone:  8.4.1
       Component:  Compiler          |              Version:  8.2.1
      Resolution:                    |             Keywords:
Operating System:  Unknown/Multiple  |         Architecture:
 Type of failure:  Documentation     |  Unknown/Multiple
  bug                                |            Test Case:
      Blocked By:                    |             Blocking:
 Related Tickets:                    |  Differential Rev(s):
       Wiki Page:                    |
-------------------------------------+-------------------------------------

Comment (by harendra):

 There are a number of issues with the documentation of optimization
 options. I guess all those can be dealt with in this ticket.

 1) The inconsistency described above in the ticket description is in the
 "Flag Reference" chapter:

 {{{

 Flag    Description     Type    Reverse
 -O0     Disable optimisations (default) dynamic -O
 }}}

 2) I would also suggest that we have another column in the "6.6.15.
 Individual optimisations" section to indicate which optimization levels
 enable each option. It could be in the form "0, 1, 2". This will really
 help in quickly identifying the options applicable to a particular level.

 3) 6.3.1. -O*: convenient “packages” of optimisation flags. This section
 should perhaps mention what is the default?

 4) 6.3.1. -O*: convenient “packages” of optimisation flags. This section
 says: "The easiest way to see what -O (etc.) “really mean” is to run with
 -v, then stand back in amazement." But when I tried it "-v" did not tell
 me what options are enabled.

 5) Some flags are documented like this:
 {{{
 -fno-opt-coercion
 Default:        off
 Turn off the coercion optimiser.
 }}}

 This is confusing. It says "Default: off", the double negation would mean
 that "-fopt-coercion" is "on". Is that the case? Is there a "-fopt-
 coercion"? If yes, can we document that instead? If not, we can be more
 explicit about the double negation.

-- 
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/14214#comment:2>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler