@heroiclands/package-build 20.3.1 → 20.5.0

package/docs/content-format.md

@@ -80,7 +80,7 @@ A tag that classifies the subject is different, because something queries it. A
 settlement tagged `village` appears in the list of villages and an untagged one
 does not, so `vilage` does not merely look wrong: it removes the note from an
 index, silently, and the index still renders. That is the same failure a
-misspelled `data:` key used to be, and it gets the same answer — the vocabulary
+misspelled `data:` key is, and it gets the same answer — the vocabulary
 is declared, so a near miss is a finding that names what you probably meant.
 
 | group               | applies to             | tags                                                                                                                                                                                                                                                                                                                 |
@@ -146,9 +146,9 @@ the corpus moves, with the block winning. A field says so by naming each: its
 shared source, and the legacy in-block key it is being swept off. Reading it
 from the legacy position is _reported_, so the sweep has a progress signal, and
 the note compiles to the identical document either way — the same read-both,
-report-one shape every other retirement in this format uses. Until #305 the two
-were one declaration, so a field could name only one of them, and a row this
-table stated was reachable only by a note that had already moved.
+report-one shape every other retirement in this format uses. As one
+declaration the two would let a field name only one of them, and a row this
+table states would be reachable only by a note that had already moved.
 
 **A field whose spelling means something else at the note level has no shared
 source.** The fallback assumes the two vocabularies agree about what a name
@@ -166,8 +166,8 @@ them.** A data model declares everything a document stores, and part of that is
 what _play_ writes: an affliction's `onsetDate` is the world time its onset
 fired at. Writing `<system>.system.<field>` reaches such a field as directly as
 any other — the block is a verbatim passthrough, and the field really is in the
-schema — so until #330 a note could stamp one, and the compiled pack shipped one
-world's play state to every world that installed it.
+schema — so a note left free to stamp one ships that world's play state to
+every world that installs the compiled pack.
 
 So a field the document writes for itself is **declared as such**, and the
 declaration says both halves of the fact: authoring it is an error naming the
@@ -225,7 +225,7 @@ is a gap in the vocabulary rather than something to write into every note: an
 override that thousands of notes need is a missing subType value.
 
 **A type's `subType` values are stated in one shape**, so that they can be read
-and compared to the vocabulary that enforces them (#345). Under the type's
+and compared to the vocabulary that enforces them. Under the type's
 heading, write `**subType**:` on a line of its own, then one bullet per value —
 `- <value>` or `- <value>: <definition>` — and nothing else between the marker
 and the list. A type that has no `subType`, or whose values are not enumerated
@@ -295,7 +295,7 @@ at the note's top level and `portrait` moved under `data:`, because a note's
 token art is a fact about the _note as a published artefact_ while the portrait
 is a fact about the _subject_.
 
-**A `data:` source is still read at the top level, for now.** `data:` (#128) did
+**A `data:` source is still read at the top level, for now.** `data:` did
 not invent the facts it holds — it gathered them out of the top level, where
 `portrait:` sat beside `img:` — so every key it collected has a **pre-`data:`
 spelling** that is read after the declared one and reported as retiring. Write
@@ -328,7 +328,7 @@ NA on both sides for that type, and its table says so.
 template priority on an Actor and not on an Item: `hm3/actors.mjs` writes
 `flags.hm3.templatePriority`, and HM3's Item pass writes no equivalent, so an HM3
 item compiled from a template note loses the fact that it is one
-(`HeroicLands/package-build#283`). The row states the mapping the format makes;
+The row states the mapping the format makes;
 the gap is in the pass, not in the table.
 
 #### An asset path's first segment says which package owns it
@@ -346,7 +346,10 @@ there are exactly three answers:
 
 `<assetRoot>` is `<packageKind>/<foundryPackage>/assets`, derived from the
 configuration — `systems/sohl/assets` for the system,
-`modules/sohl-thalorna/assets` for that module. So one authored
+`modules/sohl-thalorna/assets` for that module. A `documentation` package has
+no asset root at all, because Foundry installs no such package and serves no
+files for it: there, the third row is refused, and a note names the owning
+package (`systems/…`, `modules/…`) or a URL. So one authored
 `icons/relic.svg` means "my own `assets/icons/relic.svg`" in whichever package
 writes it, while an authored `systems/sohl/assets/icons/noun/shield.svg` names
 the system's file and is left exactly as written wherever it appears. That
@@ -449,7 +452,7 @@ The shared mapping table above names it `data.templatePriority`, targeting
 
 > **`archetype` is the retiring spelling.** It is still read, in the `sohl:`
 > block and at the top level, so a tree sweeps on its own schedule
-> (`HeroicLands/package-build#266`) — but the frontmatter linter refuses it, and
+> — but the frontmatter linter refuses it, and
 > what is compiled and emitted is `templatePriority` on all three sides.
 >
 > It is more than a rename, and the collision is **already live** rather than
@@ -481,7 +484,7 @@ real priority** — the one SoHL's own templates ship at — not an absence.
 it.** SoHL records it in `system`; HM3 keeps it under its own flag scope,
 `flags.hm3`, and a note that is not a template writes nothing there rather than a
 `null` nothing reads. Both of HM3's passes write it — an Item's flag was missing
-until `HeroicLands/package-build#283`, which made an item note's priority reach
+until an item note's priority reached
 SoHL and stop at HM3, with nothing said on either side.
 
 **How a winner is chosen.** Opening a Create dialog gathers every candidate
@@ -543,7 +546,7 @@ folder pass for a folder, the journals pass for a documentation journal, this
 rule for everything else. Re-deriving one from the `canonical` key alone reads
 correctly and is wrong for a folder, and wrong in a way nothing outside the
 build can detect: the result is a plausible 16-character id that resolves to
-nothing (#310).
+nothing.
 
 **Why the address and not an authored string.** A note used to declare an
 opaque 16-character `id` — 6,343 of them across the four content trees — which
@@ -674,7 +677,7 @@ the journals pack having to declare anything. A folder nothing references
 materialises nowhere.
 
 That derivation is what makes a whole class of defect unrepresentable. The
-folder used to be declared twice, once per pack, in two files free to disagree:
+folder declared twice, once per pack, sits in two files free to disagree:
 `sohl-thalorna` was missing 57 of its item folders from its journal folder file
 and `sohl-kethira-basic` had no journal folder file at all, so both emitted
 documentation journals into folders their own pack never declared — silently.
@@ -689,7 +692,7 @@ the first.
 
 > **`folder:` was a Foundry id**, resolved against a per-pack
 > `*-folders.yaml` — five files per tree. Both halves are **retired** together
-> (#260): the id spelling has nothing left to resolve against once the YAML is
+> : the id spelling has nothing left to resolve against once the YAML is
 > gone, and the YAML has no reader once the spelling is refused. A note that
 > still writes `folder:` fails the build, naming `packFolder` and the line to
 > rewrite, rather than being ignored — a retired field left ignored reads to
@@ -812,26 +815,26 @@ Only a type whose own document carries a system is redirected this way. A
 documents are core ones already at `none`, so `macro-autoattack` names the Macro
 and `docmacro-autoattack` its journal — two live addresses.
 
-**An address is lowercase throughout** (#340). Every segment — package,
+**An address is lowercase throughout**. Every segment — package,
 system, type and shortcode alike — is `^[a-z0-9]+$`, so a capital anywhere in an
 address is an error naming the lowercase form.
 
-The shortcode was the exception until #340: it was case-sensitive and routinely
+The shortcode is the one that would otherwise be case-sensitive and routinely
 mixed (`Clb`, `LtShoe`, `HsTunic`) while the address built from it was lowercased
 wholesale, so the authored name and its address disagreed. Two names differing
 only in case are two names nobody can tell apart, and they collapsed onto one
 address, one `_id` and one URL with nothing to report it.
 
 **Parsing is positional counting from the right, and nothing else.** Every
-segment is alphanumeric — shortcodes, **types** and **subTypes** are all
-`^[a-z0-9]+$`, systems come from a closed registry, and `contentPackage` is
-alphanumeric — so the hyphen is purely a separator. There is no longest-match
+segment is lowercase alphanumeric — shortcodes, **types** and **subTypes** are
+all `^[a-z0-9]+$`, systems come from a closed registry, and `contentPackage` is
+`^[a-z0-9]+$` too — so the hyphen is purely a separator. There is no longest-match
 against a roster and no vocabulary check before splitting.
 
 **`type` and `subType` are held to that charset, not merely expected to meet
-it** (#206). A type is the first segment of every address, so a hyphen in one is
+it**. A type is the first segment of every address, so a hyphen in one is
 read back as a segment boundary that was never meant as one. A `subType` reaches
-no address since #204 retired sections, but it is held to the same rule all the
+no address, sections being retired, but it is held to the same rule all the
 same: it is a vocabulary term the whole toolchain keys on, one closed set away
 from being an address again, and a charset that holds for two of the three
 segments and half of a fourth is a rule nobody can state. Both are checked
@@ -846,7 +849,7 @@ One declared value broke the rule and has been renamed: a `doc`'s `user-guide`
 is now **`userguide`**. The old spelling was accepted for one transitional
 release, as a warning naming the replacement, so the 43 `sohl` notes authoring
 it were not invalidated by the release that renamed them. Every consumer tree
-has swept, so the acceptance is gone (#210) and `user-guide` is refused by the
+has swept, so the acceptance is gone and `user-guide` is refused by the
 charset check — it contains a hyphen, which is the reason that always applied.
 No retirement-specific code outlived the sweep.
 
@@ -870,17 +873,17 @@ There is one namespace, and the pipe is required:
 | `[[WikiLink\|Text]]` | an address  | `Text`                     |
 | `[[Name]]`           | nothing     | a finding                  |
 
-**A link written without a label addresses nothing** (#180), and the correction
+**A link written without a label addresses nothing**, and the correction
 is always the same: write `[[type-shortcode|Text]]`.
 
-The bare form used to name an **alias** — a note's own display name, or one of
+The bare form does not name an **alias** — a note's own display name, or one of
 the names it listed in `aliases:` — looked up within the citing note's type. It
 was measured before it was retired, and the namespace was empty in practice:
 across 8,305 wikilinks in three content trees, **not one** bare link resolved to
 a note. What the index behind it did do was fold every note's `name.full` into
 itself, so two notes of one type could not share a display name — a rules page
 and a user guide page both called "Gear" were a build failure whose every
-available fix moved a published URL (#179).
+available fix moved a published URL.
 
 The top-level `aliases:` that fed it is **retired** and refused. The nested
 `name.aliases:` is **not**: it is reserved for a use that does not exist yet, so
@@ -901,7 +904,7 @@ page it is written on. It is the label that is required, not a target.
 
 #### Every address resolves, and every build says so the same way
 
-An address that names no note **fails the build** (#184) — in the link checker,
+An address that names no note **fails the build** — in the link checker,
 in the pack compilers and in the site build alike.
 
 It was a warning in the checker and, in the site build, nothing at all while any
@@ -909,21 +912,21 @@ linkable package had no vendored manifest. The reasoning was that `[[Sunless
 Vault]]` might be a placeholder for a note somebody meant to write. That was a
 property of the **bare** form, which is retired, and the intent behind it has a
 real spelling now: a note tagged `draft` exists, resolves, compiles and
-publishes, and a link to it renders visibly marked (#183). So an address landing
+publishes, and a link to it renders visibly marked. So an address landing
 nowhere is a typo or an omission, and both want fixing.
 
 There are six ways a link can fail, and each is one **error** with one message
 wherever it is met:
 
-| finding          | what it means                                   | the fix                                                |
-| ---------------- | ----------------------------------------------- | ------------------------------------------------------ |
-| `unlabelled`     | no `\|`, so the link addresses nothing          | write `[[type-shortcode\|Text]]`                       |
-| `not-an-address` | labelled, but the target is not an address      | write the address, not the name                        |
-| `not-lowercase`  | any segment of the address is capitalised       | lowercase it — every segment is lowercase              |
-| `unknown-type`   | qualified, but names no type this build knows   | correct the type segment                               |
-| `unresolved`     | parses as an address; nothing publishes it      | fix the shortcode, or qualify to reach another package |
-| `ambiguous`      | _unreachable since #336; kept for the manifest_ | —                                                      |
-| `unknown-anchor` | the address resolves; the `#section` does not   | correct the anchor                                     |
+| finding          | what it means                                 | the fix                                                |
+| ---------------- | --------------------------------------------- | ------------------------------------------------------ |
+| `unlabelled`     | no `\|`, so the link addresses nothing        | write `[[type-shortcode\|Text]]`                       |
+| `not-an-address` | labelled, but the target is not an address    | write the address, not the name                        |
+| `not-lowercase`  | any segment of the address is capitalised     | lowercase it — every segment is lowercase              |
+| `unknown-type`   | qualified, but names no type this build knows | correct the type segment                               |
+| `unresolved`     | parses as an address; nothing publishes it    | fix the shortcode, or qualify to reach another package |
+| `ambiguous`      | _unreachable; kept for the manifest_          | —                                                      |
+| `unknown-anchor` | the address resolves; the `#section` does not | correct the anchor                                     |
 
 `ambiguous` no longer fires. An omitted segment defaults rather than wildcarding,
 so a written target expands to one canonical address and a lookup returns one
@@ -1021,10 +1024,10 @@ having nothing worth summarising.
 Every note in **both** groups still produces its JournalEntry and its web page.
 The difference is only whether a system Actor or Item is created as well.
 
-That has been true of actors only since #337. A being used to produce its Actor
-and nothing else, which left it the one system-bearing note with no address at
-`none` — so a prose link naming it had nowhere to land. It now carries a
-documentation journal like every other such note, addressed
+That includes actors. A being producing its Actor and nothing else would be
+the one system-bearing note with no address at `none`, leaving a prose link
+naming it nowhere to land. It carries a documentation journal like every other
+such note, addressed
 `<package>-none-docbeing-<shortcode>` beside the Actor's
 `<package>-<system>-being-<shortcode>`.
 
@@ -1116,7 +1119,7 @@ still rendered — the finding is the point, not withholding the output.
 ##### In SQL, over the content index
 
 `dataview` is being replaced by **SQL**, queried over the content index, and both
-fences work while the corpus is converted (#246). The query is real SQL, run by
+fences work while the corpus is converted. The query is real SQL, run by
 DuckDB — not a dialect maintained by this package.
 
 ````markdown
@@ -1148,7 +1151,7 @@ relational operations:
 | `_section` | Emits a headed table per distinct value, in the order the rows arrive. |
 
 `_section` is why one query replaces the forty near-identical blocks a grouped
-table used to need: the authored `ORDER BY` decides the section order too.
+table would otherwise need: the authored `ORDER BY` decides the section order too.
 
 **Beware `packFolder`.** It is a note's _pack_ folder, not its directory — the
 directory is `file.folder`. (The `folder` field it replaced is retired; a query
@@ -1351,7 +1354,7 @@ sohl:
         durability: 0
 ```
 
-**A top-level `shortcode:` is retired** (#334). It selected a template, while the
+**A top-level `shortcode:` is retired**. It selected a template, while the
 `system.shortcode` beside it was the compiled item's identity — one word for two
 things — and it could not say which package a template came from, so an address
 resolved into a dependency only because no local pack claimed it and would have
@@ -1391,7 +1394,7 @@ shortcode)` — compendium/world reconciliation, template shadowing, cohort
 membership, effect and expression references. A `name` cannot stand in: it is
 presentation, free to be localized or to diverge.
 
-**Reordering the list moves no id.** The key used to carry the entry's position,
+**Reordering the list moves no id.** A key carrying the entry's position
 so inserting an item renumbered every id after it and a re-import created new
 documents beside the old ones — while nothing about those documents had changed,
 only their neighbours. The same is now true of a note's journal pages: an
@@ -1612,7 +1615,7 @@ the heading its page is published under; an affiliation's `system.title` is _the
 style of address the office carries_, Ajaw or Warden, which a being holds by
 virtue of its rank. So the top-level key is **not** a shared source for this
 field, and a note that writes one is stating its own heading and nothing else
-(#218). Author the style of address on the membership — the `system.title` of the
+. Author the style of address on the membership — the `system.title` of the
 entry in a being's `sohl.items` — or, on a catalogue note that genuinely carries
 one, at `sohl.system.title`.
 
@@ -2111,11 +2114,11 @@ depicts what it depicts. A place's maps are therefore derived — every map whos
 The three differ only in the canvas defaults derived for them, which is why they
 are subTypes of one type rather than three types.
 
-> The three were **types** until package-build#174, which is the shape the notes
-> in the wild still carry. Both are read: a note still writing `type: battlemap`
-> is reported and told what to write instead, exactly as a note writing
-> `type: character` is (SoHL#1580). A consumer's `sections` config keys off the
-> type, so it takes one `map` entry where it carried three.
+> The three are also readable as **types**, which is the shape notes in the
+> wild still carry: a note writing `type: battlemap` is reported and told what
+> to write instead, exactly as a note writing `type: character` is. A
+> consumer's `sections` config keys off the type, so it takes one `map` entry
+> rather than three.
 
 **NoteLocation** is `[GridLocation, anchor]` where the `anchor` is an anchor identified in the body of the note, and `GridLocation` represents a particular grid location on the document.
 
@@ -2153,24 +2156,13 @@ compilation, and the server-side migration shim is version-gated on
 single Level is synthesised from `img`, `overlay`, `levelName` and
 `backgroundColor`.
 
-> **`img`, at the note's top level, as every other type's artwork is.** A map
-> alone named it `image` and read it out of the `sohl:` block, so one idea had
-> two spellings and this table had to hedge rather than state a rule
-> ([package-build#142](https://github.com/HeroicLands/package-build/issues/142)).
-> Art is not system-specific — a Scene is a core Foundry document, and a second
-> system would want the identical art — so the field sits beside every other
-> note's `img` rather than inside a system block.
+> **`img`, at the note's top level, as every other type's artwork is.** Art is
+> not system-specific — a Scene is a core Foundry document, and a second system
+> would want the identical art — so the field sits beside every other note's
+> `img` rather than inside a system block.
 >
-> `image` was **retired in favour of it**, in the three steps `package:` took
-> (#56), and all three have now run
-> ([package-build#149](https://github.com/HeroicLands/package-build/issues/149)).
-> Through the window both spellings were read, `img` won where a note carried
-> both, and a note still writing `image` got a located **warning** rather than a
-> refusal — it compiled to the byte-identical document, so failing a build over
-> it would have redded a tree that had done nothing wrong. The trees were then
-> swept, and the alias dropped. `image` is now simply not a key a map has: in a
-> `sohl:` block it is reported as unknown, and either way the note is refused
-> for the `img` it never declared.
+> `image` is **not a key a map has**: in a `sohl:` block it is reported as
+> unknown, and either way the note is refused for the `img` it never declared.
 
 **Two unit conventions, deliberately.** Geometry — walls, doors, lights, tiles,
 sounds, region shapes — is authored in **pixels**, Foundry's native storage,
@@ -2277,9 +2269,15 @@ Content prepared to be played — a situation with its cast, places, and possibl
 - rules: The rules of the game, independent of medium — valid at a table with paper and dice.
 - userguide: How to operate the Foundry implementation to play by the rules.
 - reference: Out-of-world lookup material about the setting or system — correspondences, conversions, glossaries.
+- howto: A task with an outcome, written as the steps that reach it.
+- concept: An explanation of how something works and why it is shaped that way, read to understand rather than to follow.
 
 A `doc` declares no properties of its own.
 
+The field is a genre and only a genre: it says what kind of page this is, never
+who reads it. A page written for a developer is a `howto` or a `concept` like
+any other, and the audience is the section it sits in.
+
 **A page that introduces a type is an ordinary note, named by convention.**
 Write `type: doc`, `subType: reference`, `shortcode: <type>` — so the
 affiliations introduction is `doc-affiliation`, addressed and linked like
@@ -2289,8 +2287,8 @@ way (`homepage-root`).
 
 There is no landing page and no section. A `README.md` used to _be_ its
 section's landing, and a `subType: collection` note with a top-level `section:`
-key was a second way to say the same thing. All of it is retired — the second
-rule in #202, the first in #204 — because a section appears in **no address**: a
+key was a second way to say the same thing. All of it is retired, because a
+section appears in **no address**: a
 page publishes at `/<package>/<type>-<shortcode>/`, which names no directory. A
 section is what Hugo calls a content directory, and the note format does not
 carry one.
@@ -2440,7 +2438,7 @@ an Adventure pack declared first still compiles last.
 
 Foundry's `Folder` — the grouping documents are filed in, and the last document
 this package compiled from bespoke configuration (`*-folders.yaml`, five files
-per tree) rather than from a note. Those files are retired (#260); a pack that
+per tree) rather than from a note. Those files are retired; a pack that
 still names one is refused.
 
 ```yaml
@@ -2463,8 +2461,9 @@ data:
 A folder is addressed `<package>-none-folder-<shortcode>` — **`none`**, because a
 `Folder` is a core Foundry document like a `JournalEntry` or a `Scene`, not a
 system's. Its shortcode is [an address segment](#the-canonical-address) like
-every other, so it is strictly alphanumeric: `possessionscooking`, never
-`possessions-cooking`, which would read as two segments and resolve to nothing.
+every other, so it is strictly lowercase alphanumeric: `possessionscooking`,
+never `possessions-cooking`, which would read as two segments and resolve to
+nothing.
 
 **`color` must be quoted**, and YAML gives no third option: `color: #7a4b2a`
 parses as `null` (a `#` after a space opens a comment) and `color: 000000` parses
@@ -2519,4 +2518,4 @@ the namespace is **`folder`**, not the `document` one [every other note hashes
 under](#the-document-id): a folder and an item sharing a shortcode would
 otherwise derive the same id, and Foundry keys the two in separate collections
 so neither would complain. The content index publishes this value, so a consumer
-reads a folder's id rather than recomputing one (#310).
+reads a folder's id rather than recomputing one.