@heroiclands/package-build 25.2.1 → 25.4.0

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

@@ -260,7 +260,7 @@ 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          |
-| Verse fence                          | `verse`       | Poem           |
+| Verse div                            | `verse`       | Poem           |
 | Any other code fence                 | `code`        | Code           |
 | Paragraph, quote block or fenced div | `prose`       | Prose          |
 
@@ -409,65 +409,48 @@ Foundry renders a secret section; the website renders an expandable spoiler, and
 
 ### Verse
 
-Use a code fence with the language `verse` to preserve verse lines and stanzas.
-Each nonblank source line is one verse line. A blank line separates verse units;
-`***` on a line by itself separates stanzas. Neither separator is numbered.
-The fence itself adds no title, caption or number.
+A `.verse` div sets a version of a work, whether poetry or prose. `/` ends a
+logical line. Source newlines otherwise join with whitespace, so prose can wrap
+across source lines. A blank line or `//` ends a stanza (a paragraph); a line
+of `--- {.canto}`, preceded by a blank line, ends a canto (a section). The last line before either
+boundary needs no `/`. A literal slash in text is written `\/`; slashes inside
+Markdown syntax, such as a link destination, remain syntax.
 
-Leading periods set indentation: one `.` per level. They are removed
-from the displayed line. Leading spaces are ignored and do not set indentation.
-Periods inside the first inline span also set indentation when that span begins
-the line; periods in later spans are literal text. Interior spaces between text
-and spans are preserved. Tabs anywhere in the poem are an error. Each medium
-sets the actual width of an indent level, with every higher level wider than the
-preceding one.
+Leading periods at the beginning of a logical line set indentation, one `.` per
+level, and are removed from the display. They may follow `/` on the same source
+line. Leading spaces do not set indentation. A period beginning a continuation
+source line is literal text when the preceding text has no logical line ending.
+Periods inside the first inline span can set indentation; periods in later spans
+are literal. Tabs inside a verse div are errors. The div body is opaque to Markdown block syntax:
+lines beginning `- `, `1. `, `# `, `> ` or four spaces stay verse text.
 
-Levels 1 through 8 use the `i1`–`i8` indent classes. Deeper levels retain
-their full depth in the generated indent width.
+These two bodies have the same lines and indentation:
 
-For example, `.A line` is indented one level, while `  ..A line` is indented
-two levels: the spaces do not count. Verse is upright by default. English text
-can use Markdown emphasis; emphasis inside a span whose effective language is
-not English is an error. See [emphasis in a script](#emphasis-in-a-script).
-
-A verse line can mix plain English, language-marked spans and more English on
-one authored line. Spaces are kept exactly as written between those runs; the
-spans add no spaces of their own. A period at the start of the first span also
-sets that line's indentation:
+```markdown
+::: {.verse lang=en}
+To be or not to be,/
+..that is the question!
+:::
 
-````markdown
-```verse {lang=en}
-..The [boundary]{lang=en} is [thiruthriman]{lang=vyl} again.
-[.The boundary]{lang=en} is [thiruthriman]{lang=vyl} again.
+::: {.verse lang=en}
+To be or not to be,/..that is the question!
+:::
 ```
-````
-
-Both lines have one verse number apiece when numbering is enabled. In the
-second, the leading period inside the first span is removed and indents the
-whole line.
-
-````markdown
-```verse {form=ballad lang=en}
-The lantern burns beside the gate,
-The harbor sleeps below.
 
-***
+Verse is upright by default. English text accepts Markdown emphasis; other
+languages use their declared [script emphasis](#emphasis-in-a-script). Inline
+links, names, language spans and footnotes keep their ordinary meanings.
+The optional `form=` records the author's literary form, `lang=` identifies the
+language, and `font=` selects a face. `enc=` selects an encoding document. An
+optional `#id` addresses the div. `scan=` checks a declared metre.
 
-The keeper guards the road till dawn,
-And keeps a light aglow.
-```
-````
-
-The optional `form` attribute records the author's intent; the build does not
-infer stress, rhyme or pronunciation. `numstep` numbers the logical rows, and `cols`
-sets the poem's column count; 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 encoding](#marking-language-font-and-encoding). An optional `#id`
-addresses the poem itself. There are no `title` or `lines` attributes, and no
-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.
+On a div, a concrete `enc=` draws the original in its script on the left and the same text
+in Roman on the right. Write the original once, with no column prefixes. Each
+logical line aligns with its counterpart at full weight; indentation and breaks
+match. `⟦…⟧` codage draws glyphs on the left and remains codage on the right.
+Names, nested language choices and `lang=zxx` gaps retain their scope. A div
+with no `enc=`, or with `enc=default`, has one Roman column. The content index's
+`runs` relation records the authored original once, in its language and encoding.
 
 #### Metre
 
@@ -485,21 +468,21 @@ 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
+A verse div 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}
+```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``
 
-`scan=` uses the fence's one language to count beats. If a verse line contains
+`scan=` uses the div's one language to count beats. If a verse line contains
 a run in another language, the build does not scan that run with the fence
 language's stress rules; it reports an error at the line:
 
@@ -530,91 +513,196 @@ Beats are counted this way:
 - 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.
+declares, a div with no `lang=`, a language without a stress rule. A div with no `scan=` is not counted. Readers see nothing of the
+count; the div carries `data-scan` with the metre's name.
 
-To number and caption a poem, put a leading numbered caption before the verse fence:
+To number and caption a poem, put a leading numbered caption before the verse div:
 
-````markdown
+```markdown
 :@ A song sung by the harbor watch. {#watch-song}
 
-```verse {form=ballad}
-The watch has gone to sea,
+::: {.verse form=ballad}
+The watch has gone to sea,/
 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
+#### Versions and stanza labels
 
-`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.
+`work=<key>` names a work within the page. Every div with that key is a version
+of the same work. Each stanza opens with its automatically counted label: `1`,
+`2`, and so on for a work with no canto break, or `1:1`, `1:2`, `2:1`, and so on
+when the div contains cantos. Stanza numbering starts at one in each canto.
+The website, Foundry journals and book show the same labels. A paired original
+has one label shared by both presentations. A div without `work=` has no label.
 
-````markdown
-```verse {numstep=5 lang=en}
-The lantern burns beside the gate,
-…
+Versions must have the same number of cantos and the same number of stanzas in
+each canto. Their line counts can differ. A work with only one version is a
+finding. Shape disagreements are findings at the opening lines of the versions,
+naming the canto and the counts. A canto break at the edge of a div, or beside another
+canto break with no intervening stanza, is a finding at the break itself.
+Authored `***` inside verse is a finding.
+
+This poem's English version and Sinale original share stanza `1`. The original
+is authored once and displays as script beside Roman:
+
+```markdown
+::: {.verse form=lay work=asking lang=en}
+A child comes up the hill at night/
+.and leaves a loaf beneath the birch./
+.She does not wait. She does not search/
+the dark for us. We stand in sight.
+:::
+
+::: {.verse form=lay work=asking lang=sina enc=sinaveldikkoenc}
+irtal nysse auldiho nalduho/
+.penvai onsa tarnevinu halpi polpeho/
+.ahi sennevi onsa ahi syltete onsa/
+ehii nalduho setty ehii nelkis yinserseho
+:::
 ```
-````
 
-#### Verse in columns
+Prose uses the same div and omits line-ending marks. Source lines join into
+paragraphs. Both versions below have stanzas `1` and `2`; the original's paragraphs
+also appear beside their Roman text:
 
-`cols=N` sets a positive whole number of columns and defaults to `1`. A
-single-column poem keeps its physical lines without column prefixes. For
-`cols` above one, every content line starts with its column number and one
-or more spaces. The prefix selects its cell and is not displayed.
+```markdown
+::: {.verse work=walking lang=en}
+He walks the oath road.
 
-A blank line ends a **logical verse row**. Within that row, numbers must be
-in `1..cols` and nondecreasing: finish one column before starting a higher
-one. Any column may be omitted; its empty cell remains in the grid. A column
-may hold any number of readings. Its first line uses the foreground color,
-and every subsequent line in that same column is grey. Each column starts
-its own foreground line, and the choice resets in the next row.
+I walk the oath road.
+:::
 
-This sparse three-column poem leaves the middle cell empty in its first row:
+::: {.verse work=walking lang=vyl enc=vylsemaronenc}
+Lokazor lonak zaron.
 
-````markdown
-```verse {form=epic lang=en numstep=5 cols=3}
-1 [Thiruthriman sorimamen,]{lang=vyl}
-3 [The hallowed boundary I sing,]{lang=en}
-3 [Thiruthriman sorimamen,]{lang=vyl}
+Lokamen lonak zaron.
+:::
+```
+
+See [work shape diagnostics](../diagnostics.md#a-worked-case-versions-of-a-work)
+for how findings locate a disagreement.
+
+#### Inline quotations
+
+Quoted verse inside a prose paragraph uses a `.verse` span:
 
-1 [ul alathas kedis alatha valmazor, ul talothoi]{lang=vyl}
-2 [Nothing to say]{lang=en}
-3 [and the one who walked it, and the stones]{lang=en}
-3 [ul alathas kedis alatha valmazor, ul talothoi]{lang=vyl}
+```markdown
+The reply is [to be or not to be/..that is the question!//]{.verse} in the telling.
 ```
-````
 
-The left cell uses Vylari's configured native script. The third cell contains
-an English reading in foreground and a separately authored Roman Vylari
-reading in grey. Language labels identify words; column numbers alone place
-them. `lang=`, `font=` and `enc=` are written on the actual
-runs, so a Roman repeat makes its own presentation choice. Inline links and
-mixed-language spans stay in their authored order with their spaces intact.
+A quotation uses `/` for line endings and `//` for stanza endings, with the same
+indentation and source-line joining as a div. It takes ordinary span attributes,
+including `lang=` and `enc=`. An unencoded quotation draws Roman text with its
+line and stanza layout. A concrete encoding draws only its script, continuously
+inside the surrounding prose, like any encoded span. Its `/` and `//` reach the
+encoder as verse controls, so a script with verse signs draws them. Only divs
+have paired script and Roman columns.
+Inline verse has no `work=`, `form=`, `scan=`, stanza labels or canto breaks.
+Directions, speaker labels, links, names and shared note footnotes work inside it.
+
+#### Footnotes in works and encoded spans
+
+Footnote references are valid after a line or word inside verse. Their definitions
+sit below the work, as ordinary note footnotes:
+
+```markdown
+::: {.verse work=walking lang=en}
+He walks the oath road.[^image]
+:::
+
+::: {.verse work=walking lang=vyl enc=vylsemaronenc}
+Lokazor lonak[^oath] zaron.
+:::
+
+[^image]: The road names the obligation as well as the route.
+
+[^oath]: This word carries the oath image in the original.
+```
 
-`numstep=N` counts logical rows, not their individual readings. A standalone
-`***` separates stanzas, and column order resets after it as after a blank
-line. Leading periods after the number and its separating spaces set a
-reading's indent. Periods at the start of its first span also count; periods
-inside later spans remain text. For example:
+The English reference renders normally. In the encoded original, the reference
+appears only in the Roman column, beside the word it follows. The script column
+has no marker. Displaying a line twice adds no duplicate number, definition or
+backlink. References never add lines, stanzas or labels and never affect work
+shape.
+
+This rule also applies to every encoded span, whether or not it carries
+`.verse`. A footnote marker is removed before encoding and restored after the
+span's text, outside its script font, as an ordinary reference:
 
 ```markdown
-1 [.Thiruthriman [the boundary]{lang=en} sorimamen]{lang=vyl}
-3 [The hallowed boundary I sing,]{lang=en}
+The inscription reads [Lokazor lonak[^word] zaron.]{lang=vyl enc=vylsemaronenc}.
+The reply is [Lokazor lonak[^reply] zaron./Lokamen lonak zaron.//]{.verse lang=vyl enc=vylsemaronenc}.
+
+[^word]: A note about the inscription's wording.
+
+[^reply]: A note about the reply's wording.
 ```
 
-Every target aligns a logical row's cells at the top, including empty ones.
-On a narrow screen or journal, cells stack in their numbered order. A reading
-in a right-to-left face stays in its chosen cell and runs right to left
-within it. The book uses the same row and cell order.
+Markers never reach an encoder, draw a script glyph or cause an encoding finding.
+The website, Foundry journals and book share the note's footnote numbering and
+definitions.
+
+#### Canto headings
+
+A canto break stands alone after a blank line, with a stanza on both sides.
+Its optional `title` appears as a heading and its optional `#id` is an anchor
+within the work, without starting a separate Foundry journal page:
+
+```markdown
+::: {.verse lang=en}
+The watch crosses the shore.
+
+--- {.canto #choosing title="The Choosing"}
+The captain raises the lamp.
+:::
+```
+
+The heading appears once across an encoded div's presentations. Its title is
+heading text, separate from the letters passed to the encoder. A valid break
+supplies the encoder's standard Roman `***` canto control. `package-build format`
+leaves each complete verse div and quotation byte for byte, including its
+delimiters and attributes, while formatting surrounding prose.
+
+#### Directions and speakers
+
+A `.direction` span identifies an instruction or stage direction; `.speaker`
+identifies the person speaking. Either can fill a logical line or sit within it.
+Each version writes its own directions and speaker names in its own language.
+Write ordinary case; these classes do not rewrite the text. The classes are
+valid outside verse as well.
+
+```markdown
+::: {.verse form=rite work=weighing lang=en}
+Let the household enter. Let the creditor enter./
+[The reader names the year of the reign, the season, the day, and the dead.]{.direction}/
+One person of this household goes down to the West.
+:::
+
+::: {.verse form=rite work=weighing lang=khel enc=khelqalezuenc}
+galun garqen. galun zeqatar./
+[zethul nemar …]{.direction}/
+yarul genar lazen elu garqen nizar ez ithnar.
+:::
+
+::: {.verse form=roll work=thresholds lang=en}
+[The Captain]{.speaker}/
+Is the stone here?
+:::
+
+::: {.verse form=roll work=thresholds lang=tarv enc=tarvsemaronenc}
+[thrumar]{.speaker}/
+eza goitsa ared ir denon sedon.
+:::
+```
 
-Findings point to the authored `cols` value, column prefix or inline run;
-see [a verse in columns](../diagnostics.md#a-worked-case-a-verse-in-columns).
+Their text is encoded normally. The classes themselves are presentation hooks;
+they add no emphasis, encoding controls or stanza boundaries. A direction alone
+between blank lines is a stanza like any other. HTML preserves `direction` and
+`speaker` classes. Typst preserves those classes through `book-span` and provides
+plain `book-direction` and `book-speaker` hooks. The default appearance is plain.
 
 ### Scrolls
 
@@ -640,7 +728,7 @@ A scroll fence is a real code fence, so Markdown never reformats its body.
 - **`rows=`** is the number of characters in a column, and **`cols=`** the
   number of columns in a panel. Each is a whole number above zero, and either
   may be left out.
-- **`lang=`, `font=` and `enc=`** work as they do on a verse fence. See
+- **`lang=`, `font=` and `enc=`** work as they do on a verse div. See
   [marking language, font and encoding](#marking-language-font-and-encoding).
   The text is encoded before layout. Own and composed lexical spellings precede
   rows; a written separator follows the selected definition. An explicit `enc=`
@@ -727,10 +815,10 @@ Use the guillemet pairs instead of English double quotation marks or `<<` and
 
 Whitespace is every Unicode space-separator (`Zs`) and U+0009 through U+000D.
 A contiguous run of that whitespace is one word separator, written as the
-chosen encoding specifies. A newline in prose is whitespace. In verse, line
-endings and blank lines supply line and stanza boundaries; a line of only
-`--- {.canto}` supplies a canto boundary. Visual verse indentation stays
-layout, outside the encoded letters. Do not type `/` inside a verse fence.
+chosen encoding specifies. A source newline joins as whitespace. In verse,
+`/` ends a logical line, blank lines or `//` end stanzas, and `--- {.canto}` after a blank line
+ends a canto. Visual indentation at a logical line boundary stays layout,
+outside the encoded letters. Write `\/` for a literal slash.
 
 Native characters in a language run are written through literal codage:
 `⟦U+F0230⟧`, or a name the encoding defines between `⟦` and `⟧`. Directly
@@ -769,7 +857,7 @@ face. An explicitly authored font remains a font choice.
 
 A name's braces use the shared name controls. Resolved references encode only
 their visible labels, retaining URLs and presentation cues. These keys apply
-to spans, divs, verse fences and scroll fences. A scroll's selected font must
+to spans, divs and scroll fences. A scroll's selected font must
 belong to a script whose note declares `direction: vertical-rl`.
 
 ### A language's script
@@ -1157,7 +1245,7 @@ that `lint` reports and that fails nothing:
 | ``a span in non-English language `vyl` holds no bold or italic markup``                                                                                   | Remove the markup, or escape its delimiter characters.                                                                    |
 | `` `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 enc=vylsemaronenc` 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 verse 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 div, 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
@@ -1314,7 +1402,7 @@ 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.
+A fence named `sql` or `pagelist` is a query. Verse uses a `.verse` div or quotation.
 
 ## SQL generated tables
 
@@ -1336,7 +1424,7 @@ 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 verse fence marked with `lang=`, `font=` or `enc=`, with its containing NOTE Address, its `kind`, `lang` as written, the `tag` it resolves to, the `font` and `enc` it is set with (its own, inherited, or its language's [script](#a-languages-script)), and source line/column. See [marking language, font and encoding](#marking-language-font-and-encoding).                                                                                                                                                                                                                                                   |
+| `runs`             | Each span, div and verse div marked with `lang=`, `font=` or `enc=`, with its containing NOTE Address, its `kind`, `lang` as written, the `tag` it resolves to, the `font` and `enc` it is set with (its own, inherited, or its language's [script](#a-languages-script)), and source line/column. See [marking language, font and encoding](#marking-language-font-and-encoding).                                                                                                                                                                                                                                                     |
 | `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 `enc`, `font` and `"text"`. See [what `enc=` takes](#what-enc-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`, `attachesTo`, `lengthens`, `front`, `examples`, `barredAfter` and `tones`, then `written`, the form as a table prints it, `∅` for a zero affix.                                                                                                                                                                                                                                     |

package/docs/commands.md

@@ -1097,7 +1097,7 @@ and `**Rendering**`, and `### Patch Changes` holding `**Miscellaneous**` and
 
 **Verse**
 
-- A verse fence keeps its line breaks.
+- A verse div keeps its line breaks.
 - A stanza break renders as a blank line.
 
 **Rendering**
@@ -2626,7 +2626,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 includes each own note's spans, divs and verse fences marked with
+Metadata includes each own note's spans, divs and verse divs marked with
 `lang=`, `font=` or `enc=` under `runs`, with the language as written, its
 resolved tag, font, encoding document Address and original source line/column.
 Roman runs use the default encoding and receive no inferred script face.

package/docs/content-format.md

@@ -29,11 +29,36 @@ A nonempty note body creates one system-agnostic Foundry JournalEntry. Content b
 
 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 `verse` keeps verse lines, stanza breaks and relative indentation. Leading periods set indent levels and are removed from the text; leading spaces do not count. Blank lines separate verse units and `***` separates stanzas. 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. `cols=N` sets a positive whole number of columns and defaults to one. With `cols` above one, each content line starts with an integer and one or more spaces; numbers lie in `1..cols` and are nondecreasing within each blank-separated logical row. Any column may be omitted and keeps an empty cell. A column may repeat without limit: its first reading is foreground and its later readings are grey, independently for every column and row. Number prefixes are not displayed; `numstep` counts logical rows. `***` separates stanzas. Inline language and native presentation are explicit on each authored run. See [verse in columns](authoring/links-and-markup.md#verse-in-columns).
-
-A code fence with language `scroll` sets text in a script whose script note states `direction: vertical-rl` as columns, top to bottom, read from the right. The lines of a paragraph are joined, and each paragraph starts a fresh column. `rows=N` is the characters in a column and `cols=M` the columns in a panel, each a whole number above zero; `lang=`, `font=` and `enc=` mark the text as on a verse fence, an explicit `enc=` selects an encoding document and its language and font. The site, the preview and Foundry set it with `writing-mode: vertical-rl` in a panel that scrolls sideways from the right; the book draws its panels as images from the face's outlines, each with its roman text as alt text. A scroll fence in a script written in lines is an error. See [scrolls](authoring/links-and-markup.md#scrolls).
-
-A span, generic div, verse or scroll fence uses `enc=default` unless it selects
+A `.verse` div (`::: {.verse ...}` or `:::verse {...}`) sets poetry or prose. `/` ends a logical line; source newlines
+otherwise join. Blank lines or `//` end stanzas, and a standalone `--- {.canto}` after a blank line ends a canto.
+Leading periods indent a logical line, including after `/` within a source line;
+a period on a joined continuation line is text. `\/` writes a literal slash.
+A concrete `enc=` on a div sets the original once in two presentations, script on the left
+and Roman on the right, aligned by logical line at full weight. No `enc=`, or
+`enc=default`, produces one Roman column. Inline names, codage, language gaps and
+footnotes retain their meaning. `work=<key>` groups versions within the page,
+labels each stanza with its number (or canto:stanza), and requires matching canto
+and per-canto stanza counts; line counts may differ. Singleton work keys and
+shape disagreements are findings. A canto separator with no stanza on either
+side is a finding at that separator. `.direction` and `.speaker` spans identify
+instructions and speakers inside or outside verse, retain plain presentation
+hooks in HTML and Typst, and change neither encoding nor shape. See
+[verse and worked examples](authoring/links-and-markup.md#verse). Its numbered
+caption uses the **Poem** label. Inline quotations use `[text/..line//]{.verse}` with span presentation
+attributes and no work, form, scan, canto or labels. An encoded quotation is
+script-only and flows inside prose, with `/` and `//` drawn through its encoding;
+an unencoded quotation retains Roman verse layout. Footnotes are excluded from
+encoding: an encoded div shows each reference only beside its Roman word, and
+every encoded span restores its references after the span, outside the script
+font. A reference adds no line or stanza and creates no display duplicate. `--- {.canto #id title="Heading"}`
+adds a visible canto heading and anchor inside its work. Authored `***` is a
+finding. The formatter preserves complete verse divs and spans byte for byte. Generic `:::` divs and `[inline spans]{.class}`
+accept attributes; see [fenced divs](authoring/links-and-markup.md#fenced-divs)
+and [inline spans](authoring/links-and-markup.md#inline-spans).
+
+A code fence with language `scroll` sets text in a script whose script note states `direction: vertical-rl` as columns, top to bottom, read from the right. The lines of a paragraph are joined, and each paragraph starts a fresh column. `rows=N` is the characters in a column and `cols=M` the columns in a panel, each a whole number above zero; `lang=`, `font=` and `enc=` mark the text as on a verse div, an explicit `enc=` selects an encoding document and its language and font. The site, the preview and Foundry set it with `writing-mode: vertical-rl` in a panel that scrolls sideways from the right; the book draws its panels as images from the face's outlines, each with its roman text as alt text. A scroll fence in a script written in lines is an error. See [scrolls](authoring/links-and-markup.md#scrolls).
+
+A span, generic div, verse div or scroll fence uses `enc=default` unless it selects
 an encoding document. `enc=` is an Address whose default type is `doc`; the
 document names its language and font, and explicit `lang=` or `font=` values
 must agree. Each encoding tries authored native writings, complete parts and
@@ -41,7 +66,7 @@ then its mappings. Unknown characters, undefined glyph codes and conflicting
 selections are located errors. `⟦…⟧` reads the selected font's glyph codes or
 strict Unicode scalars. See [encodings](reference/format-details.md#encodings).
 Language word-book validation applies to both Roman and native runs. Parallel
-verse retains independent authored readings and their column numbers.
+verse keeps one authored original with its language and selected encoding.
 
 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

@@ -297,36 +297,35 @@ Like a culture conflict, each fails the index and every command that reads it
 without collecting problems. The rules are under
 [a note's language](reference/format-details.md#a-notes-language).
 
-## A worked case: a verse in columns
+## A worked case: versions of a work
 
-A [verse in columns](authoring/links-and-markup.md#verse-in-columns) has a
-positive whole-number `cols` value. Invalid counts are located at their
-value. With multiple columns, every content line needs a numeric prefix and
-one or more spaces. Missing prefixes point to the line's first content
-character; out-of-range or decreasing numbers point to the authored number.
+[Versions of a work](authoring/links-and-markup.md#versions-and-stanza-labels)
+share a page-local `work=` key and the same stanza shape. For example:
 
-This row has a decreasing column number on its third content line:
+```markdown
+::: {.verse work=watch lang=en}
+The watch arrives.
 
-````markdown
-```verse {cols=3 lang=en}
-1 The first reading.
-3 A later column.
-2 Out of order within this row.
+The harbor wakes.
+:::
+
+::: {.verse work=watch lang=en}
+Another telling has only one stanza.
+:::
 ```
-````
 
-The finding points to `2`. A blank line before it would start another row,
-where the column order begins again. A number above three or below one is
-out of bounds. Skipping a column is valid and leaves an empty cell; repeating
-a number is valid and adds another reading to that column. The first reading
-in every column is foreground and its later readings are grey.
+The opening lines receive findings naming canto 1 and its differing stanza
+counts, two and one. The first version is included in the disagreement. A key
+used by only one version is also a finding at that div's opening line.
 
-Language and native-font findings retain their authored locations inside a
-reading, including the column prefix and indentation before it. An unknown
-mapping or face points to that run's attribute; an unknown word or a character
-the face cannot draw points to the original word or character. A language-only
-Roman repeat is checked in its own language, independently of a native run.
-The build reports invalid input rather than publishing an inferred layout.
+A concrete `enc=` creates its own script and Roman presentations from one
+original; the display does not add a second authored version. Source newlines
+join unless `/` ends the line. Blank lines and `//` end stanzas. A canto uses
+`--- {.canto}` on its own line after a blank line. A leading, trailing or
+consecutive canto separator without a stanza between is located at the break
+itself. Authored `***` is a finding. Language and encoding findings retain their positions in the single
+authored original, including text inside names, directions and speaker labels.
+The content index records that original once in `runs`.
 
 ## Emphasis in non-English spans
 
@@ -603,9 +602,10 @@ finding naming its `⟦U+XXXX⟧` spelling. Use that notation, or the chosen
 encoding's codage name, inside the literal markers. The encoder checks the
 codes; the Roman validator leaves their contents immutable.
 
-A verse fence uses its authored line endings for boundaries. A literal `/`
-inside it is an error at that slash. Visual indentation does not add periods
-to the encoded text. Source positions survive Markdown escapes and nested
+A verse div uses `/` for logical line endings, `//` or blank lines for
+stanzas, and `--- {.canto}` after a blank line for cantos. A literal slash is written `\/`.
+Visual indentation at a logical line boundary does not add periods to the
+encoded text; a period on a joined continuation line remains text. Source positions survive Markdown escapes and nested
 `.emph` or `.name` spans.
 
 Language-run diagnostic columns count Unicode code points, so a supplementary