1 files changed, 78 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..861a4f0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# spout
+
+A terminal application for generating nonsense.
+
+## Installation
+
+1. Clone this repo
+2. `cargo build`
+
+## Usage
+
+### Command line options
+
+```
+Usage: spout [OPTIONS] <DIRECTORY>
+
+Arguments:
+  <DIRECTORY>  Path to data directory
+
+Options:
+  -n, --sentences <N_SENTENCES>  Number of sentences to generate [default: 1]
+      --unique                   Don't re-use entries in data files (program will fail upon running out)
+  -h, --help                     Print help
+```
+
+### Template syntax
+
+In order to generate a sentence, the program will fill in gaps in a sentence template.
+Every randomized part of a sentence is surrounded on both sides by `%%`.
+Between these markers is some kind of definition of how the gap should be filled:
+
+```
+Direct:   %%foo%%     - choose a word from the 'foo' category
+Variable: %%?foo%%    - choose a word from the category assigned to the 'foo' variable
+Multiple: %%foo|bar%% - choose a word from either the 'foo' or 'bar' category
+```
+
+Categories are sets of words/phrases that are randomly chosen from during sentence generation.
+
+Variables are randomly assigned a category from all available categories, and will be interpreted as that category throughout a sentence.
+This is useful for when you want to include multiple words from the same category, but don't care which one.
+
+Separating category names and variables with a `|` will choose between the given options. This can be used when you want to pick a word from "foo" or "bar", but not "baz".
+
+### Data files
+
+This program requires a directory of text files in a particular format in order to work.
+The directory can be anywhere on your system that you have read access.
+This directory must contain a text file named `sentences.txt`.
+It must also contain a text file for every template category that is used in the sentences file.
+The program does not enforce the latter restriction until it attempts to generate sentences, crashing if a category file is missing.
+
+The sentences file must contain exactly one sentence template per line.
+Each category file also separates words by line.
+Indeed, "words" can actually be phrases with spaces and punctuation (but not line breaks).
+In both types of file, empty lines are ignored.
+
+### Examples
+
+These examples suppose the following files and sentence templates.
+
+Example directory:
+```
+bar.txt
+baz.txt
+foo.txt
+sentences.txt
+```
+
+Example templates:
+```
+I think %%foo%% is pretty neat.
+I think %%bar%% is kind of lame.
+%%foo%% is certainly better than %%bar%%.
+I would take %%foo|baz%% over %%bar%% any day.
+%%?x%% and %%?x%% are certainly things that exist.
+```
+