@heroiclands/package-build 23.12.8 → 24.0.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,15 +194,15 @@ 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.
 
-Each numbered type has its own counter. Websites and Foundry number within a note; books number across their reading order. Unnumbered captions neither display nor consume a number. A map image can retain its asset-derived **Map** classification when no type is specified.
+Each numbered type has its own counter. Websites and Foundry number within a note; books number across their reading order. Unnumbered captions neither display nor consume a number. A picture whose asset declares the `map` role counts as a **Map** when no type is specified, and a reference to it reads **Map 1** on every surface: in the note's own page, in a journal, and from another note's page. The editor preview knows the role when it has the package's content index; without one it numbers the picture a **Figure**.
 
 `{{ref "#trade"}}` displays the numbered label as a link. `form="full"` includes caption text and `form="title"` displays the caption alone. Use title form for an unnumbered caption. Cross-note references can name the note address before the anchor, such as `{{ref "place-harbor#trade"}}`; the displayed number belongs to the target on the surface rendering it. Links inside caption text contribute their visible text to references, so the reference does not contain a nested link.
 
@@ -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 lang=en}
 The lantern burns beside the gate,
 The harbor sleeps below.
 
@@ -379,22 +382,82 @@ And keeps a light aglow.
 ```
 ````
 
-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
-`map` the mapping its text is rewritten by; see
+The optional `form` attribute records the author's intent; the build does not
+infer stress, rhyme or pronunciation. `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.
+special punctuation for stress, pauses or refrains. A poem's metre, rhyme or
+syllable pattern is described in the note's prose. `scan` names a metre the
+package declares, and the build counts the poem's beats against it, as the next
+section describes.
 
-To number and caption a poem, put a leading numbered caption before the poetry fence:
+#### Metre
+
+`scan=` names a metre declared once in the package, as an entry of a `doc`
+note's `data.metres`:
+
+```yaml
+data:
+  metres:
+    - { name: hexameter, beats: 6, kind: accentual }
+```
+
+`name` is lowercase letters, digits and `-`, unique in the package. `beats` is
+the beats of one line, a whole number above zero. `kind` is `accentual`, the
+only kind: a beat falls on a stressed syllable, and the length of a syllable
+is not counted.
+
+A verse fence that states `scan=` with the declared name, and `lang=` with a
+language whose `note` names a language note stating
+[`data.sounds.stress`](../reference/format-details.md#a-languages-register-sounds-and-history),
+is counted line by line. A line that cannot have the metre's beats is a warning
+at that line:
+
+````markdown
+```verse {form=epic scan=hexameter lang=vyl}
+Thiruthriman sorimamen, ul alathas kedis alatha valmazor,
+```
+````
+
+> ``this line has 4 beats (5 with secondary beats); the metre `hexameter` has 6``
+
+Beats are counted this way:
+
+- **Syllables** are vowel groups. A vowel is a letter whose base is `a`, `e`,
+  `i`, `o` or `u`, and a pair the language lists in
+  `data.sounds.syllables.vowelPairs` is one syllable.
+- **Every word of two or more syllables has one beat**, on its stressed
+  syllable. The language's stress rule places it: `two` for a word of two
+  syllables, `longer` for a word of three or more, and a vowel carrying the
+  rule's `mark` is stressed wherever it sits.
+- **A one-syllable noun, verb, adjective, numeral or name has a beat.** A
+  one-syllable particle, preposition, conjunction, adverb or pronoun has none.
+  The `class` of the lexicon entry decides, so the language's lexicon is read
+  through `lang=` as it is for the word check, and a form the language's rules
+  derive takes its word's class. A word whose entries differ in class is a
+  beat that may be left out.
+- **A one-syllable word the lexicon does not hold is a content word** and has a
+  beat. The word check reports the word separately.
+- **A word of four or more syllables may take a second, lighter beat on its
+  first syllable** where the line needs it, unless its stress is already
+  there. A line scans when its count can be the metre's, choosing second beats
+  as needed; the warning gives the count without them and, in brackets, with
+  all of them.
+- The caesura is not written.
+
+`scan=` is refused where it cannot mean anything: a name no `data.metres`
+declares, a fence with no `lang=`, a language without a stress rule, and a verse
+in columns. A fence with no `scan=` is not counted. Readers see nothing of the
+count; the fence carries `data-scan` with the metre's name.
+
+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 +465,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 +590,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:
 
@@ -571,7 +715,8 @@ vyl zaron` converts a passage, both through the build's own code; see
 the language's [`note`](../configuration.md#languages) names its language note.
 Each word, case folded, is one of:
 
-1. **a lexicon word**: a `data.words[].form` of the language;
+1. **a lexicon word**: a `data.words[].form` of the language, or one of its
+   `variants`, which takes every rule below as its word does;
 2. **a word of a registered name**: a word of a `name` in the language note's
    own `data.register`, under any `tongue` but `translation`. A name of several
    words is checked word by word, so `Revothar Baremzator` admits `Revothar`
@@ -590,7 +735,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
@@ -629,6 +823,94 @@ A run with `lang=` and no `map=`, a run with `map=` and no
 `lang=`, a bare BCP 47 tag and a declared language with no `note` are not
 checked.
 
+### Logographic maps
+
+**A script that writes meanings is written from the dictionary, never by
+sound.** Its mapping note states `logographic: true`, and every word of a run
+under it is written from the language's lexicon. The map's rows write only the
+text between words: the spaces, the points, and anything else with no letter
+in it. A word never falls through to the rows, so a word the lexicon gives no
+writing is an error rather than a guess.
+
+A word of the run is written by the first of these that gives a writing:
+
+1. **The word's own `native` entry** for the map, the one for the run's face
+   where an entry names one, else the one for no face. A word written its own
+   way, such as a set compound, states this even where its parts would give
+   another writing.
+2. **Its parts.**
+   - **A word stating `built`** is written by its pieces' writings joined in
+     order. A piece is a word of the lexicon, matched exactly and then with its
+     joining hyphens taken off, or an affix of `data.affixes` with a `native`
+     entry of its own. A word piece is written by this same rule, so a compound
+     of compounds resolves all the way down.
+   - **A noun's plural and a verb's present forms** are written by the stem's
+     writing followed by the ending's, which `data.grammar.native` states once
+     per ending: `plural`, or one of the persons `I`, `you`, `heShe`, `we`,
+     `youAll` and `they`. The forms themselves are the ones the language's
+     rules give, as for the lexicon check.
+   - **A hyphenated word no entry states** is written by each of its parts in
+     turn, so `Gar-halzunet` is `Gar-`'s writing followed by `halzunet`'s.
+3. **Otherwise the word is an error** at the word. Coin the word or give it a
+   writing, or write the signs directly.
+
+A word is matched case folded, because the script has no capitals: `Halzi` and
+`halzi` both find the entries `Halzi` and `halzi`. **Where one roman form
+stands for entries written differently**, or where one has a writing and
+another has none, the run cannot tell which sense is meant, and the word is an
+error naming every entry's gloss. Write that word directly in signs, picking
+the sense by its gloss from `package-build lexicon khel --map zethu`. Signs typed
+in the run are no word, and pass through as typed. Entries that share a form
+and are written alike are written so.
+
+Khelathi in Zethu, with its roots, an affix and the plural written once:
+
+```yaml
+affixes:
+  - form: "-unet"
+    gloss: "a thing made of"
+    native:
+      - { map: zethu, text: "\U0001EBC7" }
+grammar:
+  plural:
+    - { ending: "", becomes: "im" }
+  native:
+    - { ending: plural, map: zethu, text: "\U0001EBE1" }
+words:
+  - form: halzi
+    class: n
+    field: "The body"
+    gloss: heart
+    native:
+      - { map: zethu, text: "\U0001EABB" }
+  - form: halzunet
+    class: n
+    field: "Counting-house and water-works"
+    gloss: the account
+    built: [halzi, -unet]
+```
+
+`[halzi halzunet halziim]{lang=khel font=khelathi-zethu-glyphs map=zethu}` is
+written U+1EABB, then U+1EABB U+1EBC7, then U+1EABB U+1EBE1, with the spaces
+the rows write between them. A word of the run that resolves to nothing is
+reported once per run:
+
+> `` `zamlu` has no `zethu` writing in the `khel` lexicon, and its parts do not give one; state one, or write the word directly in signs ``
+
+The lexicon check still applies: every word of the run is a word of its
+language, a registered name or a regular form of one. A registered name is
+written like any other word, so a name with no writing is an error; a foreign
+name is written deliberately, in signs or through a map that rewrites a
+sign-by-sign notation.
+
+An affix's `native` and `data.grammar.native` are read only under a logographic
+map, so either one naming any other map is an error at the entry, and an ending
+of a person is an error where `data.grammar.verbs` states no `persons`. A
+word's `native` under a logographic map is not held to what the rows give,
+because the rows spell no word. `package-build lexicon khel --map zethu` lists
+every word with its writing and where it comes from, and marks the words that
+have none.
+
 ### Mapping notes
 
 A mapping note is a `doc` note whose `data.map` lists the rewrites:
@@ -678,6 +960,10 @@ How Vylari's roman spelling is written in the Semaron chancery hand.
   reaches only code points up to U+FFFF. A row matches and writes whole code
   points.
 - **`vowels`** lists the characters `before: vowel` reads as vowels.
+- **`logographic: true`** marks a script that writes meanings: every word of
+  a run is written from the lexicon, and the rows write only the text between
+  words; see [logographic maps](#logographic-maps). A row whose `from` holds a
+  letter could never apply on such a map, and is an error at the row.
 
 How a map reads text:
 
@@ -730,8 +1016,10 @@ 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.
+  Text set in a face is the one exception: it takes `*…*` and `**…**`, as
+  [emphasis in a script](#emphasis-in-a-script) describes.
 - **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: `[`
@@ -743,6 +1031,67 @@ defines `[^id]:`. A bracket with no partner takes a backslash, `\[`.
 Text marked with a real language's tag alone keeps its Markdown, so
 `[ad _astra_]{lang=la}` and an English poem with emphasis are both accepted.
 
+### Emphasis in a script
+
+Inside a run set in a face, `*…*` and `**…**` are written exactly as in
+English. No script marks a stressed word by a bold or a slant, so the build sets
+emphasis by the scribal convention the text's language or its script states:
+
+| Convention | On the site and in Foundry                         | In the book           |
+| ---------- | -------------------------------------------------- | --------------------- |
+| `rubric`   | `<em class="emph-rubric">`, in red                 | in the book's red ink |
+| `overline` | `<em class="emph-overline">`, with a line above it | under an overline     |
+| none       | `<em>` with no class, in the face's Regular        | in the face's Regular |
+
+`**…**` gives a `<strong>` in the same way. The element stays an `<em>` or a
+`<strong>`, so a screen reader and a copied passage keep the emphasis.
+
+**The convention is the language's, else the script's.** A run's `lang=`
+language, through the note its [`languages.<name>.note`](../configuration.md#languages)
+names, may state `data.emphasis`; otherwise the script note listing the run's
+face states it in `data.script`; otherwise there is none. A script note:
+
+```yaml
+---
+shortcode: semaronscrpt
+name: { full: Semaron Script }
+type: skill
+subType: script
+data:
+  script:
+    fonts: [semaron-kuriale]
+    emphasis: rubric
+---
+```
+
+So a tongue that states nothing takes its script's convention. Provenzal set in
+Semaron is rubric:
+
+```markdown
+The lintel reads [a _stressed_ word]{lang=prv font=semaron-kuriale map=semaron}.
+```
+
+and renders on the site as
+
+```html
+<span class="script hl-semaron-kuriale" lang="art-x-prv" data-pagefind-ignore="true"
+  >… <em class="emph-rubric">…</em> …</span
+>
+```
+
+**A language may mark emphasis with a word** instead of a mark:
+`data.emphasis: words` on its language note. Emphasis in a run of that language
+is then an error at the emphasis, and the remedy is the word the language
+stresses with. A language may also state `rubric` or `overline`, which it takes
+in every script it is written in.
+
+`_…_` is emphasis equal to `*…*`, and `__…__` equal to `**…**`, so a note keeps
+its meaning when a formatter rewrites one pair to the other. A strikethrough is
+an error in a face; an escaped `\*`, or a star that pairs with none, is a character the map and the
+face are checked for. A stressed word is best enclosed whole: a star inside a
+word splits it, so a map's row or a lexicon word that crosses the star is not
+matched.
+
 ### Errors
 
 Each of these is an error at its line and column, reported by `lint`, the site
@@ -760,11 +1109,16 @@ that `lint` reports and that fails nothing:
 | `` `ch` maps to U+F0299 in the map `semaron`, which the font `semaron-kuriale` does not draw ``                                                                                                                                                                | Correct the row's `to`.                                                                                                   |
 | `` `zaron` is written U+F0299 by the lexicon of `vyl` for the map `semaron`, which the font `semaron-kuriale` does not draw ``                                                                                                                                 | Correct the word's `native` text.                                                                                         |
 | `` `Orlan` is capitalised, and the native form the lexicon of `vyl` states for `orlan` under the map `semaron` does not begin as the rows spell its first letter, so the rows cannot capitalise it; state `Orlan` as a word of its own with its native form `` | State the capitalised word as a lexicon word of its own with its native form.                                             |
+| `` `zamlu` has no `zethu` writing in the `khel` lexicon, and its parts do not give one; state one, or write the word directly in signs ``                                                                                                                      | Give the word, or its pieces and endings, a writing for the map, or write its signs directly.                             |
+| `` `nelgir` stands for 2 words of the `khel` lexicon that the map `zethu` writes differently, “a god” and “god”; write the word directly in signs, choosing by its sense in `package-build lexicon khel --map zethu` ``                                        | Write the signs of the sense meant, from the lexicon listing.                                                             |
+| `` `halzi` has no `zethu` writing: the map `zethu` is logographic, and the run names no `lang=` whose lexicon writes it; mark the run with its language, or write the word directly in signs ``                                                                | Mark the run with `lang=`, or write its signs directly.                                                                   |
 | `` `thiruthrimar` is not a word of the `vyl` lexicon, a registered name, or a regular form of one; coin it in the lexicon (or register the name) first ``                                                                                                      | Coin the word in the language note's `data.words`, register the name in its own `data.register`, or correct the spelling. |
 | `` `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.                                                              |
+| ``text marked `lang=prv font=semaron-kuriale map=semaron` takes emphasis only as `*…*`, `_…_`, `**…**` or `__…__` ``                                                                                                                                           | Write the emphasis with stars or underscores.                                                                             |
+| `` `vyl` marks emphasis with a word, not a mark; write the word ``                                                                                                                                                                                             | Remove the emphasis marks and write the word the language stresses with.                                                  |
 | ``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,11 +1135,53 @@ 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).
 
+### Tying words to the core vocabulary
+
+A setting can name the concepts every language of it has a word for, and measure
+each language against them without reading a gloss. Three things state it:
+
+1. **A concept list** in the `data.concepts` of a `doc` note: each concept has
+   an `id` (lowercase letters, digits and `-`, unique in the package), a short
+   `gloss` and a `group` the report lists it under.
+2. **`core: true`** in the `data` of each language note that must cover the list.
+3. **`concept`** on each word that serves a concept: one id, or a list of ids
+   for a word that serves several.
+
+```yaml
+# Docs/Core_Concepts.md
+type: doc
+subType: reference
+data:
+  concepts:
+    - { id: see-verb, gloss: to see, group: senses }
+    - { id: smell-noun, gloss: "a smell; a scent", group: senses }
+    - { id: knee, gloss: the knee, group: body }
+
+# Skills/Vylari.md
+type: skill
+subType: language
+data:
+  core: true
+  words:
+    - { form: veda, class: n, field: Senses, gloss: a sight, concept: see-verb }
+```
+
+A `concept` that names no entry of the list is an error at the id, with the
+nearest id offered: `` `smel-noun` is not a core concept; did you mean
+`smell-noun`? ``. A language reads the words of its `data.family` chain as its
+own, so a parent's tagged word covers the daughter's concept.
+
+`package-build core` lists, for each language that states `core: true`, the
+concepts it has no word for, by group with counts. A missing concept is never an
+error: the report is the work list, and `--language <name> --json` serves an
+agent working through one language. See
+[the command reference](../commands.md#package-build-core).
+
 ## Footnotes and definition lists
 
 Write a footnote reference as `[^id]` and its definition as `[^id]: text`.
@@ -869,6 +1265,18 @@ plain words, not a checkbox — write what is done into the item itself:
 - the ferry crossing: owed
 ```
 
+## Fenced code
+
+A fence that names a language highlight.js knows is highlighted when the page is built, so a Foundry journal and the editor preview show a listing with its keywords, strings and comments coloured. The colours follow the light or dark scheme the page is in. A fence with no language, or a language highlight.js does not know, is shown as plain text.
+
+````markdown
+```js
+const lantern = "lit"; // the harbor light
+```
+````
+
+A fence named `sql`, `pagelist` or `verse` is not a listing: a query is replaced by its table, and verse is set as a poem.
+
 ## SQL generated tables
 
 A fence marked `sql` is replaced by a table built from the content index. The query reads the frontmatter of every indexed note, so a table is written once and stays true as notes are added.
@@ -889,11 +1297,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.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -907,7 +1315,7 @@ A column's heading is its SQL alias, so `AS "Name"` is what a reader sees. A cel
 | `edges`            | One row per entry of a language note's `data.sounds.edges`: the `edge` and its `sounds` as a list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `clusters`         | One row per language note stating `data.sounds.clusters`, with its `max`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `cluster_groups`   | One row per group of a language note's `data.sounds.clusters.groups`: `what`, `clusters` as a list, and `use`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `stress`           | One row per language note stating `data.sounds.stress`, with its `stress`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `stress`           | One row per language note stating `data.sounds.stress`, with its `two`, `longer` and `mark` (`NULL` where unstated).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `finals`           | One row per entry of a language note's `data.sounds.finals`: `final` and `like`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `syllables`        | One row per language note stating `data.sounds.syllables`: each rule a column, the harmony as `harmony_back`, `harmony_front`, `harmony_neutral`, `harmony_neutralAs` and `harmony_partners`, a list of `{ vowel, partner }`.                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `joining`          | One row per entry of a language note's `data.sounds.joining`: `first`, `second`, `written` and `example`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -1223,7 +1631,7 @@ The stress rule, the syllable rules and the finals. A rule of `syllables` is a c
 
 ````markdown
 ```sql
-SELECT 'Stress falls on' AS "Rule", stress AS "Value"
+SELECT 'Stress falls on' AS "Rule", two || ' of two syllables, ' || longer || ' of more' AS "Value"
 FROM stress WHERE language = 'thalorna-note-skill-vylarilng'
 ```
 
@@ -1642,92 +2050,56 @@ A page list names this package's own pages. A **stub** — a note with neither a
 
 See [page-list details](../reference/format-details.md#page-lists) for the directive's full behaviour.
 
-## Theme shortcodes
-
-The Hugo theme that renders every site defines four shortcodes. An author writes one in a note body as `{{< name … >}}`, and only the website renders it. The shared note pipeline leaves a shortcode in the source untouched, so the compendium packs and the printed book carry the call as literal text. Use a shortcode only on a page whose purpose is the website. Where a construct must reach all three surfaces, use one of the constructs earlier on this page, which every surface resolves.
-
-A shortcode takes either positional arguments or named ones, and a single call cannot mix the two. `{{< glyph "anubis" >}}` and `{{< glyph slug="anubis" frame="tablet" >}}` are both valid; `{{< glyph "anubis" frame="tablet" >}}` is refused by Hugo. A call to a shortcode that has a required argument and omits it fails the site build with the note's position.
-
-### `cartouche`
+## Signs: glyphs and cartouches
 
-Renders a named SVG seal as an ornamental accent, as a block figure or inline with text. The image is read from `img/cartouches/<slug>.svg` in the consuming site's static files.
+A **glyph** is a small picture set in a line of text, such as the sign that writes a deity's name. A **cartouche** is a framed seal set among the words around it. Both are pictures the package ships, and both render on every surface: the Foundry journals, the website, the editor preview and the book.
 
-| Parameter | Value              | Default            | What it does                                                                                          |
-| --------- | ------------------ | ------------------ | ----------------------------------------------------------------------------------------------------- |
-| `slug`    | the SVG's basename | required           | Names the file. May be given as the first positional argument when no other parameter is used.        |
-| `size`    | `inline`           | block              | `inline` flows the image with the surrounding text. Any other value adds a `cartouche-<value>` class. |
-| `align`   | `left` or `right`  | centered           | Floats the figure so prose wraps around it.                                                           |
-| `height`  | a CSS length       | set by the theme   | Sets the image's height, for example `10rem` or `160px`. The width follows the image's aspect ratio.  |
-| `alt`     | text               | the humanized slug | The image's text alternative.                                                                         |
-| `caption` | text               | none               | A caption under the image. Block mode only; an inline cartouche ignores it.                           |
+Each is a bracket span: a glyph has the `.glyph` class and a cartouche has the `.cartouche` class.
 
 ```markdown
-{{< cartouche "takheperu" >}}
+The name [Ra]{.glyph slug=ra} is written with one sign.
 
-{{< cartouche slug="aukhelathu" height="10rem" align="right" >}}
+| God    | Sign                                              |
+| ------ | ------------------------------------------------- |
+| Anubis | [Anubis, jackal]{.glyph slug=anubis frame=tablet} |
 
-{{< cartouche slug="anubis" caption="Anpu" >}}
-
-The sign {{< cartouche slug="ra" size="inline" >}} stands for the sun.
+The seal [Au'Khelathu]{.cartouche slug=aukhelathu height=10rem align=right caption="Au'Khelathu"} is cut above the gate.
 ```
 
-The first call centers the `takheperu` seal as a block. The second floats the `aukhelathu` seal to the right at ten rem tall, with the following paragraph wrapping around it. The third adds a caption under the seal. The fourth sets the seal in the line of text.
-
-### `exturl`
-
-Renders a web address as a code-styled string followed by a button that copies it to the clipboard. It exists for an address a reader is meant to paste somewhere, such as a server address or a manifest URL, where a clickable link would be the wrong affordance. The address is the first positional argument and the shortcode takes no other.
-
-| Parameter          | Value                     | Default | What it does                                                           |
-| ------------------ | ------------------------- | ------- | ---------------------------------------------------------------------- |
-| first (positional) | the text to show and copy | none    | The string displayed in the code element and written to the clipboard. |
-
-```markdown
-Install from {{< exturl "https://example.org/module/manifest.json" >}} in the module browser.
-```
-
-The page shows the address in a code element with a copy icon beside it. Selecting the icon copies the address and briefly marks the button as copied. The text is not a link.
+Each picture is named by `slug` and is a file the package ships: a glyph is `assets/icons/<slug>.svg` and a cartouche is `assets/images/cartouches/<slug>.svg`. Each surface serves the file at the address it serves every other [image](#images-and-protected-content) at. Draw the SVG with `stroke="currentColor"` and `fill="none"` to take the colour of the surface it appears on.
 
 ### `glyph`
 
-Renders an icon-scale SVG, such as a deity-name cluster, a category icon or an ornamental mark, in the line of text or as a block. The image is `icons/<slug>.svg`, resolved against the consuming site's `params.cdnBaseURL`. This is an image drawn from the site's icon directory; it is a separate construct from the `:icon name:` font glyphs of the [icon guide](../guides/icons.md), which every surface renders from the package's declared `icons` registry.
-
-| Parameter | Value               | Default            | What it does                                                                                                  |
-| --------- | ------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------- |
-| `slug`    | the SVG's basename  | required           | Names the file. May be given as the first positional argument when no other parameter is used.                |
-| `frame`   | `tablet`            | none               | Sets the glyph inside a limestone rectangular frame, so rows of different intrinsic width line up in a table. |
-| `size`    | `inline` or `block` | 1.8em tall         | `inline` is small and flows with the text. `block` centers the glyph as a standalone line.                    |
-| `alt`     | text                | the humanized slug | The image's text alternative.                                                                                 |
-
-```markdown
-| God    | Glyph                                      |
-| ------ | ------------------------------------------ |
-| Anubis | {{< glyph slug="anubis" frame="tablet" >}} |
+The label between the brackets is the picture's text alternative, read aloud by a screen reader and printed in the book when the package ships no file for the sign. An empty label takes the humanized slug.
 
-The name {{< glyph "ra" >}} is written with one sign.
+| Attribute | Value               | Default    | What it does                                                                                                  |
+| --------- | ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `slug`    | the SVG's basename  | required   | Names the file `icons/<slug>.svg`.                                                                            |
+| `frame`   | `tablet`            | none       | Sets the glyph inside a limestone rectangular frame, so rows of different intrinsic width line up in a table. |
+| `size`    | `inline` or `block` | 1.8em tall | `inline` is small and flows with the text. `block` centers the glyph as a standalone line.                    |
 
-{{< glyph slug="ra" size="block" alt="Sun god Ra" >}}
-```
+A glyph takes no `#id`, no other class and no other attribute. Write the alternative text as the label; an `alt=` attribute is refused, as is any attribute the glyph does not take. A glyph with a finding is drawn as an ordinary span, and the finding names the line and column of the span.
 
-### `pagelist`
+This is a separate construct from the `:icon name:` font glyphs of the [icon guide](../guides/icons.md), which every surface renders from the package's declared `icons` registry.
 
-Renders the pages carrying a tag as a list of links, ordered as asked. The group is expressed by intent: a page joins by being tagged and leaves by being untagged. The shortcode lists the site's own pages by the tags the site's taxonomy holds.
+### `cartouche`
 
-The ` ```pagelist ` fence described under [Page lists](#page-lists) is a different construct with its own attributes. The fence is answered by the content pipeline and reaches Foundry and the book; the shortcode is the site's alone.
+The label between the brackets is the picture's text alternative, read aloud by a screen reader and printed in the book when the package ships no file for the seal. An empty label takes the humanized slug. The seal is drawn as a figure at the place the span stands in the sentence.
 
-| Parameter | Value                       | Default       | What it does                                                                                          |
-| --------- | --------------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
-| `tag`     | a tag                       | required      | The taxonomy term to list, matched case-insensitively. May be given as the first positional argument. |
-| `section` | a top-level section name    | every section | Restricts the list to one section of the site, such as `rules`.                                       |
-| `sort`    | `title`, `weight` or `date` | `title`       | The order of the list. `date` puts the newest first.                                                  |
-| `desc`    | `true`                      | off           | Shows each page's description beneath its link. Any other value leaves descriptions out.              |
+| Attribute | Value              | Default          | What it does                                                                                                                           |
+| --------- | ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `slug`    | the SVG's basename | required         | Names the file `images/cartouches/<slug>.svg`.                                                                                         |
+| `align`   | `left` or `right`  | centered         | Floats the figure on the website and in Foundry so prose wraps around it. The book sets it at that side of its own line.               |
+| `height`  | a length           | set by the theme | Sets the image's height, a number followed by `rem`, `em`, `px`, `pt`, `cm`, `mm` or `in`. The width follows the image's aspect ratio. |
+| `caption` | text               | none             | A caption under the image.                                                                                                             |
 
 ```markdown
-{{< pagelist tag="key-concept" >}}
+The seal [Ta Kheperu]{.cartouche slug=takheperu} is cut above the gate.
 
-{{< pagelist tag="key-concept" section="rules" sort="weight" desc="true" >}}
+The seal of [Anpu]{.cartouche slug=anubis caption="Anpu"} is cut below it.
 ```
 
-The first call lists every page tagged `key-concept` alphabetically by title. The second lists only those in the `rules` section, in weight order, each followed by its description. A tag that no page carries produces a build warning naming the tag and the note's position, and the list is left out.
+The first span centers the `takheperu` seal and takes its alternative text from the label. The second adds a caption under the `anubis` seal. A cartouche takes no `#id`, no other class and no other attribute; write the alternative text as the label, because an `alt=` attribute is refused, as is `size=`. A cartouche with a finding is drawn as an ordinary span, and the finding names the line and column of the span. A `:::cartouche` fence is not a cartouche: it is reported like any other unknown block and draws nothing.
 
 ## Expressions
 
@@ -1744,7 +2116,7 @@ There are {{words (sql "SELECT COUNT(*) FROM notes WHERE type = 'being'")}} bein
 - **An expression is one line.** It may not contain a line break or a brace.
 - **A failed expression leaves its own text in the page** and reports the line and column it is written on, so the page is readable and the fault is locatable.
 - **`\{{` writes an expression without evaluating it**, for an example in prose.
-- **`{{{…}}}`, `{{<…}}` and `{{%…}}` are left alone.** A Hugo shortcode is not an expression.
+- **`{{{…}}}` is left alone.**
 - **An expression inside a code fence is left alone.**
 - Helpers nest, with the inner call in parentheses: `{{words (sql "…")}}`.