user-guide: Note order-dependence of flags

This supplements the description previously added in
6400c7687223c5b2141176aa92f7ff987f61aba6. See #10560 for details.

Test Plan: read it

Reviewers: austin

Subscribers: thomie, hvr

Differential Revision: https://phabricator.haskell.org/D1831

GHC Trac Issues: #10560

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index 91b62919b8..3b192ef1dc 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -85,6 +85,28 @@ all files; you cannot, for example, invoke
 ``ghc -c -O1 Foo.hs -O2 Bar.hs`` to apply different optimisation levels
 to the files ``Foo.hs`` and ``Bar.hs``.
 
+.. note::
+
+    .. index::
+       single: command-line; order of arguments
+
+    Note that command-line options are *order-dependent*, with arguments being
+    evaluated from left-to-right. This can have seemingly strange effects in the
+    presence of flag implication. For instance, consider
+    :ghc-flag:`-fno-specialise` and :ghc-flag:`-O1` (which implies
+    :ghc-flag:`-fspecialise`). These two command lines mean very different
+    things:
+
+    ``-fno-specialise -O1``
+
+        ``-fspecialise`` will be enabled as the ``-fno-specialise`` is overriden
+        by the ``-O1``.
+
+    ``-O1 -fno-specialise``
+
+        ``-fspecialise`` will not be enabled, since the ``-fno-specialise``
+        overrides the ``-fspecialise`` implied by ``-O1``.
+
 .. _source-file-options:
 
 Command line options in source files