Write some amount of documentation

docs/arithmetic.md

@@ -0,0 +1,84 @@
+# Arithmetic
+
+Basic math operations. All arithmetic words pop their operands and push the result.
+
+## Basic Operations
+
+```
+3 4 +      ( 7 )
+10 3 -     ( 7 )
+3 4 *      ( 12 )
+10 3 /     ( 3.333... )
+10 3 mod   ( 1 )
+```
+
+Division always produces a float. Use `floor` if you need an integer result.
+
+## Negative Numbers
+
+```
+5 neg      ( -5 )
+-3 abs     ( 3 )
+```
+
+## Rounding
+
+```
+3.7 floor  ( 3 )
+3.2 ceil   ( 4 )
+3.5 round  ( 4 )
+```
+
+## Min and Max
+
+```
+3 7 min    ( 3 )
+3 7 max    ( 7 )
+```
+
+## Power and Root
+
+```
+2 3 pow    ( 8 )
+9 sqrt     ( 3 )
+```
+
+## Examples
+
+Calculate a frequency ratio:
+
+```
+440 2 12 / pow *   ( 440 * 2^(1/12) ≈ 466.16 )
+```
+
+Clamp a value between 0 and 1:
+
+```
+1.5 0 max 1 min    ( 1 )
+-0.5 0 max 1 min   ( 0 )
+```
+
+Scale a 0-1 range to 200-800:
+
+```
+0.5 600 * 200 +    ( 500 )
+```
+
+## Words
+
+| Word | Stack | Description |
+|------|-------|-------------|
+| `+` | (a b -- sum) | Add |
+| `-` | (a b -- diff) | Subtract |
+| `*` | (a b -- prod) | Multiply |
+| `/` | (a b -- quot) | Divide |
+| `mod` | (a b -- rem) | Modulo |
+| `neg` | (a -- -a) | Negate |
+| `abs` | (a -- \|a\|) | Absolute value |
+| `floor` | (a -- n) | Round down |
+| `ceil` | (a -- n) | Round up |
+| `round` | (a -- n) | Round to nearest |
+| `min` | (a b -- min) | Minimum |
+| `max` | (a b -- max) | Maximum |
+| `pow` | (a b -- a^b) | Power |
+| `sqrt` | (a -- √a) | Square root |