add reference/conditionals

2 files changed, 41 insertions, 3 deletions

diff --git a/docs/reference/03-2_conditionals.md b/docs/reference/03-2_conditionals.md
new file mode 100644
index 0000000..59cac7f
--- /dev/null
+++ b/docs/reference/03-2_conditionals.md
@@ -0,0 +1,35 @@
+[if][] can be used to make choices at evaltime. It takes an evaltime constant
+boolean as its first argument and then either evaluates its second argument
+(the 'then' expression, if the condition was truthy) or its third argument
+(the 'else' expression, if it wasn't). The 'else' expression can be omitted if
+it is not needed.
+
+    (def print-first true)
+    (print (if print-first
+      "First!"
+      "Second :("))
+    
+    #(prints nothing)
+    (if false
+      (print "Another message"))
+
+If multiple expressions (with side effects) need to be switched, [when][] can
+be used instead: it evaluates all arguments as a block, only if the condition
+is truthy:
+
+    (def enable-things true)
+    
+    (when enable-things
+      (print "the things are enabled.")
+      (print "they should happen soon.")
+      (print "thank you for enabling them."))
+
+This is equivalent to using a [do][] block inside the [if][] expression:
+
+    (def enable-things true)
+    
+    (if enable-things
+      (do
+        (print "the things are enabled.")
+        (print "they should happen soon.")
+        (print "thank you for enabling them.")))
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 5012d0f..f0335c3 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -14,7 +14,7 @@ own module or contributing to alive, check out the
 2. [evaltime and runtime](02_evaltime-and-runtime.html)
 3. evaltime
    1. [symbol resolution](03-1_symbol-resolution.html)
-   2. if and switch
+   2. [conditionals](03-2_conditionals.html)
    3. [functions](03-3_functions.html)
    4. dynamic symbols
    5. [loops](03-5_loops.html)
@@ -22,5 +22,8 @@ own module or contributing to alive, check out the
 4. runtime
    1. result kinds
    2. pure operators
-5. [builtin listing](builtins.html)
-6. included modules
+5. compound types
+   1. arrays
+   2. structs
+6. [builtin listing](builtins.html)
+7. included modules