# 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$.