[commit: ghc] master: users_guide: Describe order-dependence of -f and -O flags (6400c76)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/6400c7687223c5b2141176aa92f7ff987f61aba6/ghc

>---------------------------------------------------------------

commit 6400c7687223c5b2141176aa92f7ff987f61aba6
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Fri Jul 3 19:36:12 2015 +0200

    users_guide: Describe order-dependence of -f and -O flags
    
    The behavior of the -f and -O options can be quite surprising.
    Document this fact. At some point this behavior should likely be changed.
    
    Test Plan: documentation only
    
    Reviewers: austin, trofi
    
    Reviewed By: austin, trofi
    
    Subscribers: thomie, bgamari
    
    Differential Revision: https://phabricator.haskell.org/D1008
    
    GHC Trac Issues: #10560


>---------------------------------------------------------------

6400c7687223c5b2141176aa92f7ff987f61aba6
 docs/users_guide/flags.xml |  2 +-
 docs/users_guide/using.xml | 23 +++++++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index a0be2cb..b7345cb 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1753,7 +1753,7 @@
   <sect2>
     <title>Optimisation levels</title>
 
-    <para>These options are described in more detail in <xref linkend="options-optimise"/></para>
+    <para>These options are described in more detail in <xref linkend="options-optimise"/>.</para>
 
     <informaltable>
       <tgroup cols="4" align="left" colsep="1" rowsep="1">
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 4d4b01f..5642ea5 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -2105,6 +2105,29 @@ _  = rhs3        -- No warning: lone wild-card pattern
     <emphasis>machine-specific</emphasis> optimisations to be turned
     on/off.</para>
 
+    <para>Most of these options are boolean and have options to turn them both
+    “on” and “off” (beginning with the prefix
+    <option>no-</option>). For instance, while <option>-fspecialise</option>
+    enables specialisation, <option>-fno-specialise</option> disables it. When
+    multiple flags for the same option appear in the command-line they are
+    evaluated from left to right. For instance <option>-fno-specialise
+    -fspecialise</option> will enable specialisation.
+    </para>
+
+    <para>It is important to note that the <option>-O*</option> flags are roughly
+    equivalent to combinations of <option>-f*</option> flags. For this reason,
+    the effect of the <option>-O*</option> and <option>-f*</option> flags is
+    dependent upon the order in which they occur on the command line.
+    </para>
+
+    <para>For instance, take the example of <option>-fno-specialise
+    -O1</option>. Despite the <option>-fno-specialise</option> appearing in the
+    command line, specialisation will still be enabled. This is the case
+    as <option>-O1</option> implies <option>-fspecialise</option>, overriding
+    the previous flag. By contrast, <option>-O1 -fno-specialise</option> will
+    compile without specialisation, as one would expect.
+    </para>
+
     <sect2 id="optimise-pkgs">
       <title><option>-O*</option>: convenient “packages” of optimisation flags.</title>