From 25a12c1def1ec5ebcdb6fe0b6c1f2a8d4a6fa731 Mon Sep 17 00:00:00 2001
From: Aleteoryx <alyx@aleteoryx.me>
Date: Sun, 8 Sep 2024 13:39:32 -0400
Subject: [PATCH] document the format properly

---
 FORMAT.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  3 ++
 2 files changed, 89 insertions(+)
 create mode 100644 FORMAT.md

diff --git a/FORMAT.md b/FORMAT.md
new file mode 100644
index 0000000..4779a34
--- /dev/null
+++ b/FORMAT.md
@@ -0,0 +1,86 @@
+# Directory Structure
+
+The TPL web wizard expects to find a file `templates/list.txt` at its
+mountpoint. Each line of list.txt `list.txt` should correspond to an
+existing directory `templates/<line content>/`, containing a file
+`meta.json`. This repository is already setup to provide this.
+
+Each entry corresponds to a license, whose data will be loaded from the
+referenced `meta.json` file.
+
+# `meta.json`
+
+This file contains license metadata and the overall template structure.
+It has the following fields:
+
+```js
+{
+  "name": string, // the string to be used in the license selector
+  "description": string, // a friendly description, currently unused
+  "version": string, // the current revision of the license
+  "format": [string] // a set of template references, explained below
+}
+```
+
+Template references instruct the wizard to optionally load a piece of
+text. At their simplest, they are a path to be appended to the
+templates directory path, e.g. `"/NC/main.txt"`. If a colon (`:`) is
+present in the reference string, the text before the colon will be used
+as the name of an optional segment, for example
+`"Include Plain English?:/NC/plain.txt"`. The wizard will create a
+checkbox toggle to control this segment. If the text before the colon
+is prefixed with a plus (`+`), the checkbox will be enabled by default,
+e.g. `"+Include Liability?:/liability.txt"`.
+
+The wizard will load each referenced file, perform substitutions as
+detailed below, and then append each enabled segment into the final
+license. Look at the `meta.json` files of existing licenses for
+examples of how to structure the `format` array.
+
+```json
+{
+  "name": "Example License",
+  "description": "This is an example license from the documentation",
+  "version": "1.0",
+  "format": [
+    "/example/critical-section.txt",
+    "Include A Thing?:/example/maybe-2nd-section.txt",
+    "+You should include this thing.:/example/maybe-3rd-or-2nd.txt",
+    "/other-license/shared-section.txt",
+  ]
+}
+```
+
+# Substitutions
+
+In any license text file, regions of the form `$<name>[:<filters>]$`,
+e.g. `$creator:lower$` are substituted with other text. The value of
+`name` is interpreted like so:
+
+- `type`: Replaced with the "Work Type", as selected by the user
+- `creator`: Replaced with the "Creator Type", as selected by the user
+- `medium`: Replaced with the "Medium Type", as selected by the user
+- `author_verb`: `filters` is interpreted as a string of the form
+`<single>|<plural>`, and one is printed based on whether `creator` is
+a single individual, e.g. `author`, or a group e.g. `artists`. Filters
+are not applied if this is selected, as `author_verb` makes special use
+of the value of `filters`.
+
+If the value of `name` is unknown, it is substituted verbatim, e.g.
+`$foo$` would be replaced with `foo`.
+
+The value of `filters` is interpreted like so:
+
+- `caps`: if included in `filters`, converts the result of `name` to
+all-uppercase.
+- `lower`: if included in `filters`, converts the result of `name` to
+all-lowercase.
+
+`lower` takes precedence over `caps`. While most strings default to
+all-lowercase, it is considered good form to still include `:lower`,
+for clarity.
+
+    This is an example section of a fake license. The $creator:lower$
+    $author_verb:hopes|hope$ that this is useful in contributing to the
+    $type:lower$.
+
diff --git a/README.md b/README.md
index 2c52805..0431331 100644
--- a/README.md
+++ b/README.md
@@ -34,5 +34,8 @@ TPL accepts contributions! The main author is no lawyer, and is mostly
 basing the language here off of existing licenses. If there are
 loopholes or flaws in these, please [let them know][1]!
 
+For documentation on the templating format, go [here][2].
+
 [0]: https://aleteoryx.tilde.institute/tpl
 [1]: mailto:~aleteoryx/tpl-discuss@lists.amehut.dev
+[2]: https://git.amehut.dev/~aleteoryx/tpl/tree/master/item/FORMAT.md
-- 
2.43.4