@heroiclands/package-build 23.12.8 → 23.13.0

package/docs/authoring/links-and-markup.md

@@ -91,7 +91,11 @@ the attribute adds no book presentation.
 
 `package-build lint` warns when an indexed name or alias uses `.name`
 instead of a link, when the same name is marked or linked again, or when a
-`.name` span or Markdown link uses a short form before its full name. Only
+`.name` span or Markdown link uses a short form before its full name. A
+`.name` span with a `data-type` is compared only with notes of that type (and
+subtype, when it names one), so a lineage that shares its name with a place
+note is marked `[Theinuvael]{.name data-type="affiliation/lineage"}` and
+draws no warning to link the place. Only
 marked names and authored link labels count toward these rules. A wikilink
 introduces its note under whatever label reads naturally, so
 `[[place-arden|Arden]]` needs no earlier `Arden Vale`, and an article
@@ -108,9 +112,8 @@ A name span can sit inside emphasis:
 ```
 
 The marked name is `Joe Blow`. Sites and books display `.name` text in bold, including
-inside an emphasized phrase. A whole bold span matching an indexed name or
-alias receives an advisory to mark or link that name; bold containing an
-explicit name span or link needs no such advisory.
+inside an emphasized phrase. Bold itself is emphasis, never a name: a bold
+label such as `**Strength**:` draws no warning, whatever names the index holds.
 
 These are warnings at each occurrence's `file:line:column`; they do not make
 a valid package fail. The check reads authored prose outside headings,
@@ -191,11 +194,11 @@ The caption attaches to exactly the next supported block:
 | Markdown table                       | `table`       | Table          |
 | Image, Markdown or wikilink          | `figure`      | Figure         |
 | SQL fence, including backtick SQL    | `table`       | Table          |
-| Poetry fence                         | `poetry`      | Poem           |
+| Verse fence                          | `verse`       | Poem           |
 | Any other code fence                 | `code`        | Code           |
 | Paragraph, quote block or fenced div | `prose`       | Prose          |
 
-The optional `type` attribute overrides inference and accepts `figure`, `table`, `poetry`, `code`, `prose`, and `example`. `type=example` uses **Example 1**, **Example 2**, and so on. It does not allow an unsupported target. A heading, list, thematic break, another caption or end of document after a caption is an error. Caption markers without separating spaces or caption text are errors too.
+The optional `type` attribute overrides inference and accepts `figure`, `table`, `verse`, `code`, `prose`, and `example`. `type=example` uses **Example 1**, **Example 2**, and so on. It does not allow an unsupported target. A heading, list, thematic break, another caption or end of document after a caption is an error. Caption markers without separating spaces or caption text are errors too.
 
 Identifiers are optional and must be unique within the note. Classes are unrestricted; `.border` uses the shared border style, while other classes can be styled by the medium. On a captioned table or SQL fence, `.full-width` sets the table across the page in a PDF book instead of in one column (`: Regional trade routes {.full-width}`); the other surfaces ignore it. Named attributes use `key=value`, with quoted values for text containing spaces. Use `#id` and `.class` rather than `id=` and `class=`; event-handler attributes are refused.
 
@@ -338,9 +341,9 @@ A secret block can contain alerts and general divs. It cannot contain another se
 
 Foundry renders a secret section; the website renders an expandable spoiler, and the book renders a labeled box. An untitled secret takes its normal default title, and a Foundry secret without an id receives an id derived from its body. The presentation does not make published HTML private: deliberately inspecting generated source can reveal its content. Use YAML comments for information that must never be published.
 
-### Poetry
+### Verse
 
-Use a code fence with the language `poetry` to preserve verse lines and stanzas. Every nonblank source line
+Use a code fence with the language `verse` to preserve verse lines and stanzas. Every nonblank source line
 is one verse line; blank lines separate stanzas. Inline emphasis, links and
 footnotes work as they do in prose. The fence itself adds no title, caption or
 number.
@@ -366,11 +369,11 @@ an error. Interior spaces are preserved on a best-effort basis.
 
 For example, a line with four leading spaces and a line with six leading spaces
 render at levels zero and `i1` respectively. This also works when the entire
-fence is indented inside a list item. Poetry is upright by default; use normal
+fence is indented inside a list item. Verse is upright by default; use normal
 Markdown emphasis when italics are part of the poem.
 
 ````markdown
-```poetry {form=ballad meter="common meter" rhyme=ABCB syllables="8,6,8,6" lang=en}
+```verse {form=ballad meter="common meter" rhyme=ABCB syllables="8,6,8,6" lang=en}
 The lantern burns beside the gate,
 The harbor sleeps below.
 
@@ -383,18 +386,19 @@ The optional `form`, `meter` and `rhyme` attributes record the author's intent;
 the build does not infer stress, rhyme or pronunciation. `syllables` gives a
 positive count for each verse line in order, separated by commas, with blank
 stanza lines omitted. The build checks the number of counts, not the syllables
-spoken. `lang` names the poem's language, `font` the font it is set in and
+spoken. `numstep` numbers the lines, and `col1` and `col2` set the poem in
+columns; see below. `lang` names the poem's language, `font` the font it is set in and
 `map` the mapping its text is rewritten by; see
 [marking language, font and mapping](#marking-language-font-and-mapping). An optional `#id`
 addresses the poem itself. There are no `title` or `lines` attributes, and no
 special punctuation for stress, pauses or refrains.
 
-To number and caption a poem, put a leading numbered caption before the poetry fence:
+To number and caption a poem, put a leading numbered caption before the verse fence:
 
 ````markdown
 :@ A song sung by the harbor watch. {#watch-song}
 
-```poetry {form=ballad}
+```verse {form=ballad}
 The watch has gone to sea,
 The lantern marks the shore.
 ```
@@ -402,9 +406,90 @@ The lantern marks the shore.
 
 This uses the **Poem** counter, so `{{ref "#watch-song"}}` reads **Poem 1**. Use `:` for a caption without a number.
 
+#### Line numbers
+
+`numstep=N` numbers the poem's lines, counting every verse line from the first
+to the last across stanzas. `numstep=1` numbers every line, `numstep=5` every
+fifth line, and `numstep=0`, the default, numbers none. The numbers sit in a
+margin beside the lines, in a muted tone.
+
+````markdown
+```verse {numstep=5 lang=en}
+The lantern burns beside the gate,
+…
+```
+````
+
+#### Verse in columns
+
+A poem can be set beside its translation, line for line. `col1=` names what
+the left column shows and `col2=` what the right column shows, and each
+column stacks one or more **entries**, joined by `:`. An entry is
+`language[/mapping[/font]]`:
+
+- **`language`** names a language the poem's lines give, as `lang=` does.
+- **`mapping`** names a [mapping note](#mapping-notes), which rewrites the
+  line before it is set. Left out, the line is set as written.
+- **`font`** names a face or a generic family, as `font=` does. Left out, the
+  line is set in the roman serif.
+
+A poem has at most two columns, and either may be left out. In every column
+the first entry is set in the normal tone and each later one in grey.
+
+With columns, the poem's body is written as **verse lines**, each a group of
+lines separated by a blank line. Each line of a group is a span giving the
+verse line in one language, `[text]{lang=…}`, or plain text in the poem's
+`lang=`. The spans of a group may come in any order: each entry takes the
+span in its own language. A line holding only `***` breaks the stanza.
+
+Here the left column sets the Vylari in Semaron Kuriale through the `semaron`
+mapping, and the right column gives the English over the Vylari in roman:
+
+````markdown
+```verse {numstep=5 lang=vyl col1=vyl/semaron/semaron-kuriale col2=en:vyl}
+[Thiruthriman sorimamen,]{lang=vyl}
+[The hallowed boundary I sing,]{lang=en}
+
+[ul alathas kedis alatha valmazor, ul talothoi]{lang=vyl}
+[and the one who walked it, and the stones]{lang=en}
+
+***
+
+[set down in the grass of the six hills]{lang=en}
+lendthoi ir yormalis ol selthur malkothoi
+
+[before a wall stood on any of them.]{lang=en}
+pra kembothos us urkis ol alathoi thalezor.
+```
+````
+
+The Vylari is written once, in roman, and the script is never typed: the
+first entry of `col1=` maps the Vylari line into Semaron, and the second entry
+of `col2=` sets the same line as written. The last two verse lines give their
+Vylari as plain text, which takes the poem's `lang=vyl`.
+
+Every target sets each verse line as one row: its number, when the poem is
+numbered, then each column. Each row holds its columns level, so a long line
+on one side never puts the other out of step. On a narrow screen or a narrow
+journal, a row stacks its columns in order. A part set in a right-to-left face
+stays in its column and runs right to left within it. The book sets the poem
+as a grid with a row per verse line.
+
+**The rules of a verse in columns:**
+
+- `font=` and `map=` belong to the entries, not to the poem.
+- Every verse line gives one span for each language its columns name, and
+  none for a language they do not.
+- A line of a verse in columns is not indented, and a span there takes only
+  `lang=`.
+- `syllables` gives one count per verse line, not per written line.
+
+Each finding is an error at the text that is wrong; see
+[a verse in columns](../diagnostics.md#a-worked-case-a-verse-in-columns).
+
 ## Marking language, font and mapping
 
-Three keys go in the attribute block a span, a fenced div or a poetry fence
+Three keys go in the attribute block a span, a fenced div or a verse fence
 already takes. Each is optional, and each does one thing:
 
 - **`lang=`** names the language of the text. It becomes the element's
@@ -446,13 +531,13 @@ Daimela, helthos.
 A poem takes the keys on its fence, beside its other attributes:
 
 ````markdown
-```poetry {form=epic lang=vyl font=semaron-kuriale map=semaron}
+```verse {form=epic lang=vyl font=semaron-kuriale map=semaron}
 Zaron tholmeza,
   daimela, helthos.
 ```
 ````
 
-**A run inside a div or a poetry fence inherits its keys**, and its own keys
+**A run inside a div or a verse fence inherits its keys**, and its own keys
 override them. Here the gloss keeps the passage's language and map, and is set
 in the page's serif:
 
@@ -590,7 +675,56 @@ Each word, case folded, is one of:
      is `a`, `e`, `i`, `o` or `u`), letters such as `replaces: a` take the
      place of those letters, and a stem that closes otherwise takes the suffix
      whole. An affix that states no `replaces` makes no form here, whatever its
-     `attaches` says, because `attaches` is prose.
+     `attaches` says, because `attaches` is prose. A suffix stating
+     `attachesTo: [n, adj]` attaches only to words of those classes, and one
+     stating no `attachesTo` attaches to a word of every class;
+   - an agreeing form, where the language states `data.grammar.agreement`: a
+     word of one of its `classes` closing on one of its `endings` takes each
+     other ending in its place, and each form takes the `plural` rule;
+   - a participle, where the language states `data.grammar.participles`: a
+     verb closing on one of its `root` endings drops it, and each suffix it
+     names attaches to the root, agreeing where it closes on an agreement
+     ending.
+
+**Agreement and participles, worked through in Vylari.** Vylari's adjectives
+and pronouns agree with their noun by its endings, and its participles are
+suffixes on the verb root. Its note states both beside its plural rule:
+
+```yaml
+affixes:
+  - form: "-andar"
+    gloss: "doing it: the present participle"
+    replaces: vowel
+  - form: "-thos"
+    gloss: "done, suffered: the past participle"
+grammar:
+  plural:
+    - { ending: os, becomes: oi }
+    - { ending: on, becomes: oi }
+    - { ending: a, becomes: ai }
+  agreement:
+    classes: [adj, pron]
+    endings: [os, a, on]
+  participles:
+    root: [athen, ethen]
+    affixes: ["-andar", "-thos"]
+```
+
+With those, a run accepts:
+
+| Lexicon word      | Rule        | Forms accepted                                    |
+| ----------------- | ----------- | ------------------------------------------------- |
+| _alathos_, pron.  | agreement   | _alatha_, _alathon_, _alathoi_, _alathai_         |
+| _dokathen_, v.    | participles | _dokandar_ (_dok-_ + _-andar_), _dokthos_         |
+| _dokathen_, v.    | both        | _doktha_, _dokthon_, _dokthoi_, _dokthai_         |
+| _marendos_, n. m. | neither     | _marendoi_ by the plural rule alone; no _marenda_ |
+| _solkatora_, v.   | participles | none: the verb closes on no `root` ending         |
+
+_-andar_ closes on no agreement ending, so _dokandar_ does not agree. A
+near miss such as _alathe_ or _dokendar_ is still an unknown word.
+`package-build lexicon vyl --map semaron --derived` lists every form the rules
+give, each beside the word it comes from, so a puzzling finding can be checked
+against what the rules produce.
 
 A compound that is not a word whole is split at its hyphens and en dashes, and
 each part is checked, so `zaron-lonak` passes when `zaron` and `lonak` do. An
@@ -731,7 +865,7 @@ plain text.
 - **A span or a verse line** holds no emphasis, link, image, footnote,
   wikilink, code or HTML, and no span but a marked one inside a div or a fence.
 - **A div** holds paragraphs and line breaks only: no heading, list, block
-  quote, code fence, poetry fence, table, rule, footnote definition or nested
+  quote, code fence, verse fence, table, rule, footnote definition or nested
   block. Mark a poem's own fence instead of a div around it.
 
 The text is read as written, so characters a run types need no escaping: `[`
@@ -764,7 +898,7 @@ that `lint` reports and that fails nothing:
 | `` `thuravark-carved` is not a font of the map `semaron`; it is for `semaron-kuriale` ``                                                                                                                                                                       | Set the run in a face the map lists, or list the face in `data.map.fonts`.                                                |
 | ``text marked `lang=vyl` is plain text and holds no emphasis``                                                                                                                                                                                                 | Remove the markup, or escape the character with a backslash.                                                              |
 | ``a div marked `lang=vyl font=semaron-kuriale map=semaron` holds paragraphs and line breaks only, not a list``                                                                                                                                                 | Move the list out of the div.                                                                                             |
-| `` `font=` is read on a span, a div or a poetry fence, not on a secret block ``                                                                                                                                                                                | Put a marked div inside the secret block.                                                                                 |
+| `` `font=` is read on a span, a div or a verse fence, not on a secret block ``                                                                                                                                                                                 | Put a marked div inside the secret block.                                                                                 |
 | `` `vly` is read as a BCP 47 tag; did you mean the declared language `vyl`? `` (a warning)                                                                                                                                                                     | Write the declared name, or ignore it when the tag is meant.                                                              |
 
 A character the face does not draw is reported once per run, at its first
@@ -781,7 +915,7 @@ SELECT owner, kind, tag, font, line FROM runs WHERE lang = 'vyl' ORDER BY owner,
 ```
 ````
 
-Its columns are `owner`, `kind` (`span`, `block` or `poetry`), `lang` as written,
+Its columns are `owner`, `kind` (`span`, `block` or `verse`), `lang` as written,
 the `tag` it resolves to (`NULL` when it resolves to none), `font`, `map`, `line`
 and `column`. A run inside a div or a fence records the keys it inherits. See
 [the `runs` relation](../reference/format-details.md#content-tables).
@@ -889,11 +1023,11 @@ A column's heading is its SQL alias, so `AS "Name"` is what a reader sees. A cel
 | `entries`          | Every note, stubs included.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `events`           | One row per event a `lore`, `place` or `affiliation` note writes in `data.events`, with `whenSort` to order them by date.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `names`            | Each authored `.name` span, with its containing NOTE Address, visible text, optional type/subtype and source line/column.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `runs`             | Each span, div and poetry fence marked with `lang=`, `font=` or `map=`, with its containing NOTE Address, its `kind`, `lang` as written, the `tag` it resolves to, `font`, `map`, and source line/column. See [marking language, font and mapping](#marking-language-font-and-mapping).                                                                                                                                                                                                                                                                                                                                                |
+| `runs`             | Each span, div and verse fence marked with `lang=`, `font=` or `map=`, with its containing NOTE Address, its `kind`, `lang` as written, the `tag` it resolves to, `font`, `map`, and source line/column. See [marking language, font and mapping](#marking-language-font-and-mapping).                                                                                                                                                                                                                                                                                                                                                 |
 | `maps`             | One row per row of a mapping note's `data.map`, with its containing NOTE Address, the map's `name`, the `font` whose own row it is (`NULL` for a shared row), the row's 1-based place as `"row"`, and its `"from"`, `"to"`, `before` and `"at"`. See [mapping notes](#mapping-notes).                                                                                                                                                                                                                                                                                                                                                  |
 | `natives`          | One row per native form a language note's word states in `native`, with that note as its `language`, the word's place as `word`, its `form`, the entry's place as `native`, and its `map`, `font` and `"text"`. See [what `map=` takes](#what-map-takes).                                                                                                                                                                                                                                                                                                                                                                              |
 | `words`            | One row per word a language note writes in `data.words`, with that note as its `language`, its `position` and what it is built from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `affixes`          | One row per affix a language note writes in `data.affixes`, with that note as its `language`, its `position`, and each key the affix states: `form` (`NULL` on a zero affix), `zero`, `kind`, `given`, `"where"`, `gloss`, `attaches`, `replaces`, `lengthens`, `front`, `examples`, `barredAfter` and `tones`, then `written`, the form as a table prints it, `∅` for a zero affix.                                                                                                                                                                                                                                                   |
+| `affixes`          | One row per affix a language note writes in `data.affixes`, with that note as its `language`, its `position`, and each key the affix states: `form` (`NULL` on a zero affix), `zero`, `kind`, `given`, `"where"`, `gloss`, `attaches`, `replaces`, `attachesTo`, `lengthens`, `front`, `examples`, `barredAfter` and `tones`, then `written`, the form as a table prints it, `∅` for a zero affix.                                                                                                                                                                                                                                     |
 | `fields`           | One row per field a language note writes in `data.fields`, with that note as its `language`, its `position`, and the field's `name` and what it `holds`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `glossary`         | One row per entry a culture or an affiliation writes in `data.glossary`, with the `note` it belongs to and the `language` it resolves to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `language_lineage` | One row per language note and each language it inherits words from through `data.family`, itself included at `depth` 0. Join it to `words` for a language's words with inherited ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

package/docs/commands.md

@@ -2492,7 +2492,7 @@ with visible text, nullable type/subtype and original source line/column.
 Local and dependency SQL schemas expose them through `names`; they travel in
 the metadata artifact.
 
-Metadata also includes each own note's spans, divs and poetry fences marked with
+Metadata also includes each own note's spans, divs and verse fences marked with
 `lang=`, `font=` or `map=` under `runs`, with the language as written, the tag
 it resolves to, the font, the map and the original source line/column. Local
 and dependency SQL schemas expose them through `runs`, and each mapping note's
@@ -3058,7 +3058,7 @@ List a language's words with their native forms under a map.
 **SYNOPSIS**
 
 ```
-package-build lexicon <language> --map <map> [--font <slug>] [--json]
+package-build lexicon <language> --map <map> [--font <slug>] [--derived] [--json]
 ```
 
 **DESCRIPTION**
@@ -3071,17 +3071,27 @@ word has one, else the rows' spelling, each exactly as
 by tabs, the word's `form`, its native form, `exception` or `rows`, its `class`
 and its `gloss`. Writes nothing.
 
+With `--derived`, the forms the language's own rules derive from those words
+follow them: plurals, verb forms, replacing suffixes, agreeing forms and
+participles, exactly the regular forms
+[the mapped-run word check](authoring/links-and-markup.md#a-mapped-runs-words)
+accepts. Each is listed once, case folded as the check compares it, and spelled
+by the rows; a form that is itself a lexicon word is not repeated. Every line
+then has a sixth column: the lexicon word a derived form comes from, empty for
+the lexicon's own words. A derived line carries its word's `class` and `gloss`.
+
 **OPTIONS**
 
 | Positional | Type   | Default | Description                                         |
 | ---------- | ------ | ------- | --------------------------------------------------- |
 | `language` | string | —       | A declared language whose `note` names its lexicon. |
 
-| Option   | Type    | Default                    | Description                                                                |
-| -------- | ------- | -------------------------- | -------------------------------------------------------------------------- |
-| `--map`  | string  | —                          | Required: the `data.map.name` of a mapping note.                           |
-| `--font` | string  | the map's one face, if one | The face; required when the map lists more than one.                       |
-| `--json` | boolean | `false`                    | Print a JSON array of `{ form, native, exception, class, gloss }` instead. |
+| Option      | Type    | Default                    | Description                                                                                            |
+| ----------- | ------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `--map`     | string  | —                          | Required: the `data.map.name` of a mapping note.                                                       |
+| `--font`    | string  | the map's one face, if one | The face; required when the map lists more than one.                                                   |
+| `--derived` | boolean | `false`                    | Also list the forms the language's rules derive, each with the word it comes from.                     |
+| `--json`    | boolean | `false`                    | Print a JSON array of `{ form, native, exception, class, gloss }` instead; a derived form adds `from`. |
 
 **EXIT STATUS**
 
@@ -3097,6 +3107,11 @@ $ package-build lexicon vyl --map semaron | head -3
 zaron	<native form>	exception	n	an oath
 lonak	<native form>	rows	n	a road
 thizaron	<native form>	rows	n	a seal
+$ package-build lexicon vyl --map semaron --derived | grep -P '\talathos$'
+alatha	<native form>	rows	pron	he, that one	alathos
+alathon	<native form>	rows	pron	he, that one	alathos
+alathoi	<native form>	rows	pron	he, that one	alathos
+alathai	<native form>	rows	pron	he, that one	alathos
 ```
 
 **SEE ALSO**

package/docs/configuration.md

@@ -1975,7 +1975,7 @@ named first in the generated manifest's `styles`.
 The sheet carries what every package's compiled content needs to read in
 Foundry as it does in the preview and on the site: definition lists (an
 infobox and the markdown `Term` / `: definition` syntax both emit one),
-poetry, alerts, inline spoilers, marked names in bold, unresolved links and
+verse, alerts, inline spoilers, marked names in bold, unresolved links and
 captioned blocks. It is scoped to the journal, enriched-field and editor
 containers so it cannot reach Foundry's own interface, where `.name` and `dl`
 style Foundry's and the system's own elements.

package/docs/content-format.md

@@ -27,11 +27,11 @@ Start with [your first note](authoring/first-note.md). It explains the smallest
 
 A nonempty note body creates one system-agnostic Foundry JournalEntry. Content before the first H1 becomes an introduction page; every H1 starts another JournalEntryPage. A lower-level heading with an explicit `{#anchor}` starts a page too, so a link can address it. The same prose becomes a web page and can be selected for a book. The content index records the note and its frontmatter for queries and navigation.
 
-Leading `:` captions describe the next supported block; `:@` captions also number it. The optional type accepts `figure`, `table`, `poetry`, `code`, `prose`, and `example`. Captions support identifiers, classes and named attributes; unsupported following blocks are errors. See [captions and numbered references](authoring/links-and-markup.md#captions-and-numbered-references).
+Leading `:` captions describe the next supported block; `:@` captions also number it. The optional type accepts `figure`, `table`, `verse`, `code`, `prose`, and `example`. Captions support identifiers, classes and named attributes; unsupported following blocks are errors. See [captions and numbered references](authoring/links-and-markup.md#captions-and-numbered-references).
 
-A code fence with language `poetry` keeps verse lines, stanza breaks and relative indentation. Its numbered caption uses the **Poem** label. Generic `:::` divs and `[inline spans]{.class}` accept attributes. See [poetry](authoring/links-and-markup.md#poetry), [fenced divs](authoring/links-and-markup.md#fenced-divs) and [inline spans](authoring/links-and-markup.md#inline-spans).
+A code fence with language `verse` keeps verse lines, stanza breaks and relative indentation. Its numbered caption uses the **Poem** label. Generic `:::` divs and `[inline spans]{.class}` accept attributes. See [verse](authoring/links-and-markup.md#verse), [fenced divs](authoring/links-and-markup.md#fenced-divs) and [inline spans](authoring/links-and-markup.md#inline-spans). `numstep=N` numbers every Nth line. `col1=` and `col2=` set the poem in at most two columns, each a `:`-joined stack of `language[/mapping[/font]]` entries, the first in the normal tone and the rest in grey; with columns, each blank-line group of `[text]{lang=…}` spans is one verse line, every entry sets the span in its language, and a `***` line breaks the stanza. See [verse in columns](authoring/links-and-markup.md#verse-in-columns).
 
-A span, a generic div or a poetry fence marks its text's language with `lang=`, the font it is set in with `font=` and a mapping with `map=`, each optional, and the runs inside a div or a fence inherit its keys. `lang=` is a name the package declares in `languages` or a BCP 47 tag, and gives the language tag alone. `font=` is a face of the installed `@heroiclands/fonts`, named by its class without `hl-`, or `mono`, `serif` or `sans`. `map=` names a mapping note: a `doc` note whose `data.map` lists the fonts it is drawn in and rows that rewrite the text before it is set, a font's own rows first. With `lang=` naming a language whose configured `note` names its language note, a word whose entry states a `native` form for the map is written by it, and the rows spell every other word. Every word of such a run is a lexicon form, a word of a name the language note's own register lists under a tongue other than `translation`, or a form a plural row, the verb pattern or an affix stating `replaces` derives from a lexicon form, and any other word is an error at the word. A character a face does not draw, after the map, is an error at the character it came from. Text with a font, a map or a declared language is plain. Every marked construct is a row of the `runs` relation, every mapping row of the `maps` relation, and every native form of the `natives` relation. See [marking language, font and mapping](authoring/links-and-markup.md#marking-language-font-and-mapping).
+A span, a generic div or a verse fence marks its text's language with `lang=`, the font it is set in with `font=` and a mapping with `map=`, each optional, and the runs inside a div or a fence inherit its keys. `lang=` is a name the package declares in `languages` or a BCP 47 tag, and gives the language tag alone. `font=` is a face of the installed `@heroiclands/fonts`, named by its class without `hl-`, or `mono`, `serif` or `sans`. `map=` names a mapping note: a `doc` note whose `data.map` lists the fonts it is drawn in and rows that rewrite the text before it is set, a font's own rows first. With `lang=` naming a language whose configured `note` names its language note, a word whose entry states a `native` form for the map is written by it, and the rows spell every other word. Every word of such a run is a lexicon form, a word of a name the language note's own register lists under a tongue other than `translation`, or a form a plural row, the verb pattern or an affix stating `replaces` derives from a lexicon form, and any other word is an error at the word. A character a face does not draw, after the map, is an error at the character it came from. Text with a font, a map or a declared language is plain. Every marked construct is a row of the `runs` relation, every mapping row of the `maps` relation, and every native form of the `natives` relation. See [marking language, font and mapping](authoring/links-and-markup.md#marking-language-font-and-mapping).
 
 Mark a name without a note as `[Name]{.name data-type="being"}`; the optional
 classification uses the declared note vocabulary. The [name-marking

package/docs/diagnostics.md

@@ -254,6 +254,48 @@ problems, listing every conflict at once. Stating `data.culture` on the note
 resolves it. The rules are under
 [Culture in the index](reference/format-details.md#culture-in-the-index).
 
+## A worked case: a verse in columns
+
+A [verse in columns](authoring/links-and-markup.md#verse-in-columns) is
+checked line by line, and every finding sits on the text that makes it wrong.
+Each is an error, from `package-build lint` and from every build that sets the
+page.
+
+A verse line that leaves out a language its columns name is located at the
+group's first line, and names the column that asks for it. A language given
+twice is located at the second span, and one no column sets at its span:
+
+```text
+assets/content/Lore/Walking_of_the_Line.md:14:1: error: this verse line has no `en` line, which `col2=` sets
+assets/content/Lore/Walking_of_the_Line.md:18:1: error: this verse line gives `en` twice; give each language once
+assets/content/Lore/Walking_of_the_Line.md:22:1: error: no column sets `khel`; a verse line gives the languages `col1=` and `col2=` name
+```
+
+A finding about the columns themselves is located in the opening line, at the
+key or at the entry. A third column is located at its key; a malformed entry
+at the entry; an unknown mapping or font at that part of its entry, with the
+nearest name the package knows:
+
+```text
+assets/content/Lore/Walking_of_the_Line.md:9:85: error: `col3=` is not a column: a verse has at most two, `col1=` and `col2=`
+assets/content/Lore/Walking_of_the_Line.md:9:81: error: `vyl/a/b/c` in `col2=` is not an entry: an entry is `language[/mapping[/font]]`
+assets/content/Lore/Walking_of_the_Line.md:9:45: error: `vyl-semron` is not a map: `map=` names the `data.map.name` of a mapping note; did you mean `vyl-semaron`?
+```
+
+The text an entry sets is checked as a span with that entry's keys, and its
+findings sit on the character of the verse line they come from. A character
+the face does not draw, after the mapping, is located at the character as the
+note wrote it:
+
+```text
+assets/content/Lore/Walking_of_the_Line.md:19:8: error: `7` (U+0037) is not drawn by the font `semaron-kuriale`, and the map `vyl-semaron` has no row for it
+```
+
+A key that names nothing is the one finding: a line set through an unknown
+mapping or font is not then checked against a face or a lexicon it cannot
+reach. A verse in columns with any finding is set as its lines are written,
+and the build fails on the error.
+
 ## Summary counts and prose are not findings
 
 A run's progress and summary lines — `42 address(es) across 10 note(s).`,