diff --git a/README.md b/README.md
index 1c41f3f..f563a16 100644
--- a/README.md
+++ b/README.md
@@ -10,3 +10,26 @@ Python program.
 If you want to use it on the command line, you can either call `./markup.py` and pass your text to
 process through STDIN. Otherwise, you can pass in a (single) file as an argument, e.g.
 `./markup.py filename.txt`
+
+# Language
+
+This language attempts to be easy to use and extend. There are not many default macros available,
+they are added as-needed.
+
+## Examples
+
+`asdf asdf asdf` => `asdf asdf asdf`
+
+`${random 6}` => `4`
+
+`${choose a b c d}` => `d`
+
+`${round 6.4}` => `6`
+
+## Available macros
+
+* `random [X [Y]]` - chooses a random number. If no arguments are supplied, chooses a random number
+  between 0.0 and 1.0, exclusive. If one argument, chooses a random integer between 1 and the
+  number, inclusive. If two arguments, chooses a random integer between the two numbers, inclusive.
+* `choose [X [Y [Z ...]]]` - chooses a random item from the supplied list of items.
+* `round X [Y]` - rounds a number X to an optional Y digits.