From a2f6f95270e8d45c81b8c684858187e08b65f128 Mon Sep 17 00:00:00 2001
From: Aditya Siram <deech@localhost.localdomain>
Date: Sun, 1 Jan 2017 16:09:50 -0600
Subject: [PATCH] Add more documentation to declaring conditionals.

---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/README.md b/README.md
index 63c9cb91..034914c0 100644
--- a/README.md
+++ b/README.md
@@ -134,6 +134,49 @@ becomes
       extra-lib-dirs:
         lib/darwin
 
+Multiple conditionals must fall under one `when`, for example:
+
+    when:
+      - condition: os(darwin)
+        extra-lib-dirs: lib/darwin
+      - condition: os(linux)
+        extra-lib-dirs: /usr/lib/x64
+
+becomes
+
+    if os(darwin)
+      extra-lib-dirs:
+        lib/darwin
+    if os(linux)
+      extra-lib-dirs:
+        /usr/lib/x64
+
+If conditionals are declared under different `when` clauses only the last one
+will make it to the `.cabal` file:
+
+    when:
+      - condition: os(darwin)
+        extra-lib-dirs: lib/darwin
+    when:
+      - condition: os(linux)
+        extra-lib-dirs: /usr/lib/x64
+
+becomes:
+
+    if os(linux)
+      extra-lib-dirs:
+        /usr/lib/x64
+
+Unlike with `.cabal` files compound predicates need to be in parens, for example:
+
+    when:
+      - condition: (!os(darwin) && !os(windows))
+        ghc-options: ...
+
+If they are not the YAML parser will throw this mysterious error:
+
+    ./package.yaml:41:31: did not find expected alphabetic or numeric character while scanning an anchor
+
 Conditionals with an else branch:
 
 - Must have a `condition` field