Write some amount of documentation

docs/logic.md

@@ -0,0 +1,89 @@
+# Logic
+
+Boolean operations and conditional execution.
+
+## Boolean Operators
+
+```forth
+1 1 and   ( 1 )
+0 1 or    ( 1 )
+1 not     ( 0 )
+1 0 xor   ( 1 )
+1 1 nand  ( 0 )
+0 0 nor   ( 1 )
+```
+
+## Conditional Execution
+
+Execute a quotation if condition is true:
+
+```forth
+{ "kick" s . } coin ?     ( 50% chance )
+{ 0.5 gain } step 0 = ?   ( only on step 0 )
+```
+
+Execute if false:
+
+```forth
+{ "snare" s . } coin !?   ( if NOT coin )
+```
+
+## If-Else
+
+```forth
+{ "kick" s } { "snare" s } coin ifelse .
+```
+
+Stack: `(true-quot false-quot bool --)`
+
+## Pick
+
+Choose from multiple quotations:
+
+```forth
+{ 60 } { 64 } { 67 } step 3 mod pick note
+```
+
+Stack: `(quot1 quot2 ... quotN n -- result)`
+
+## Apply
+
+Execute a quotation unconditionally:
+
+```forth
+{ 2 * } apply   ( doubles top of stack )
+```
+
+## Examples
+
+Conditional parameter:
+
+```forth
+"kick" s
+  { 0.8 } { 0.4 } iter 2 mod = ifelse gain
+.
+```
+
+Multi-way branching:
+
+```forth
+"synth" s
+  { c4 } { e4 } { g4 } { c5 } step 4 mod pick note
+.
+```
+
+## Words
+
+| Word | Stack | Description |
+|------|-------|-------------|
+| `and` | (a b -- bool) | Logical and |
+| `or` | (a b -- bool) | Logical or |
+| `not` | (a -- bool) | Logical not |
+| `xor` | (a b -- bool) | Exclusive or |
+| `nand` | (a b -- bool) | Not and |
+| `nor` | (a b -- bool) | Not or |
+| `?` | (quot bool --) | Execute if true |
+| `!?` | (quot bool --) | Execute if false |
+| `ifelse` | (t-quot f-quot bool --) | If-else |
+| `pick` | (..quots n --) | Execute nth quotation |
+| `apply` | (quot --) | Execute unconditionally |