From e8fa45fc3ba2ae78a9f58401342d924e12c40682 Mon Sep 17 00:00:00 2001
From: Chris Mounce <christophermounce@gmail.com>
Date: Sun, 20 Jul 2025 11:57:54 -0700
Subject: [PATCH] Add documentation

---
 README.md               | 57 +++++++++++++++++++++++++++++++++++++++++
 mzp_peg_macro/README.md |  5 ++++
 2 files changed, 62 insertions(+)
 create mode 100644 README.md
 create mode 100644 mzp_peg_macro/README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3189218
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+# Marzipan
+Marzipan is a macro processor for [ZZT](https://en.wikipedia.org/wiki/ZZT).
+It extends the ZZT-OOP scripting language while still maintaining compatibility with ZZT 3.2: all language features compile down to vanilla ZZT-OOP.
+
+## Features
+- **Anonymous labels:** Like assembly code, ZZT-OOP control flow relies heavily on gotos.
+    Anonymous labels reduce the cognitive overhead of writing such code.
+    `:@` defines a label with a unique name, and `@f`/`@b` reference the nearest anonymous label forward/backward of the current line.
+- **Local labels:** Label names with a dot are scoped to a single section of an object's program.
+    This allows you to reuse a name like `.loop` multiple times in a single object's code.
+    Marzipan will replace this with a distinct name per section: `loop_` in one section, `loopa` in the next section, etc.
+- **Macro language (WIP):** Lines starting with `%` invoke a Marzipan macro.
+    Macros work by text substitution; for example, `%include "foo.txt"` will insert the contents of a text file at the current line.
+
+Here's an example of what anonymous labels look like in practice:
+
+```
+@Treasure chest
+#end
+:touch                  'Event handler, user touched the chest.
+#if key @f              'Jump to anonymous label. Marzipan compiles `@f` to `_`...
+The chest is locked.
+#end
+:@                      '...and this compiles to `:_`.
+You unlock the chest.
+There's a bunch of gems inside!
+#give gems 20
+#die
+
+:shot                   'Event handler, user shot at the chest.
+#if shotgun @f          'This time, Marzipan compiles `@f` to `a`...
+Nothing happens.
+#end
+:@                      '...and this compiles to `:a`.
+The chest shatters!
+Gems fly everywhere.
+#put w green gem
+#put e green gem
+#become green gem
+```
+
+## Usage
+Marzipan reads and writes ZZT world files, a binary file format.
+You will need either ZZT itself or an external ZZT editor (such as [KevEdit](https://github.com/cknave/kevedit)) to work with them.
+
+```
+marzipan WORLD.ZZT -o ./dest_folder/WORLD.ZZT
+```
+
+A disclaimer: **Marzipan is experimental.**
+It hasn't eaten my code yet, but I cannot guarantee it will treat your code with kindness.
+If you use it, make sure to keep backups of your work. (You were already keeping backups, right?)
+
+## Planned features
+- Extending the macro system to a full language with variables, custom macro definitions, etc.
+- Code minification, for generated code that bumps up against ZZT 3.2's size limits.
+- Lints for ZZT-OOP, such as dead code analysis.
diff --git a/mzp_peg_macro/README.md b/mzp_peg_macro/README.md
new file mode 100644
index 0000000..6268ae9
--- /dev/null
+++ b/mzp_peg_macro/README.md
@@ -0,0 +1,5 @@
+A PEG parser generator built for [Marzipan](https://github.com/cmounce/marzipan).
+
+Currently tightly coupled to Marzipan's specific needs and not designed for general use.
+It might evolve into a standalone library in the future if there's broader interest.
+But until then, you probably want something like [pest](https://pest.rs/) if you're looking for a PEG parser.