[GHC] #9358: Improve flag description in the user guide

[Simon Peyton Jones]

|  >  Jan, you said you'd be willing to do this updating before 7.10
|  Yes, that's the plan. The question is do I have to make it before the
|  mid-November feature freeze?
|  Austin, what's your opinion?

Great.  Sooner the better.  Post freeze Austin has to do merging work, but not impossible.

|  >  It's more than a simple on/off  thing because the order matters.
|  Hmm.... in which cases does it matter? Can you give an example?

Well, for example, as you'll see in SimplCore, the -O1 pipeline runs the float-out twice.  So just saying "float-out is on" doesn't tell you all you might want to know.  It might be worth translating SimplCore.getCoreToDo into English and putting it in the manual as a rough idea.  But maybe that is too much, I'm not sure.  (eg it would get out of date)

Perhaps just listing what is on by default in -O1 and -O2 would get a long way.

Simon