@heroiclands/package-build 25.1.3 → 25.2.0

package/docs/diagnostics.md

@@ -254,6 +254,49 @@ problems, listing every conflict at once. Stating `data.culture` on the note
 resolves it. The rules are under
 [Culture in the index](reference/format-details.md#culture-in-the-index).
 
+## A worked case: names and a note's language
+
+A note's `name` lists its other names under language codes. A key that is
+neither `full`, `sort`, a character's `given` or `clan`, nor a code
+`languages:` declares or `en` is an error at the key, `aliases` among them:
+
+```text
+assets/content/Beings/Ada.md:3:21: error: `name.aliases` is not valid for this note: a name lists its forms under a language code `languages:` declares, or `en`
+```
+
+A list that is not a list of nonempty strings is an error at its key, and a form
+under `en` that repeats `full`, ignoring case, is an error at the form:
+
+```text
+assets/content/Beings/Ada.md:3:30: error: `name.en` repeats `name.full` (ada vale); `full` is already an English form, so leave it out
+```
+
+The other three come from deriving each note's language into the content index,
+and each is located at the value that causes it. A `data.lang` naming no
+declared code:
+
+```text
+assets/content/Lore/Tale.md:4:14: error: data.lang vyal names no language: state a code `languages:` declares, or en (en, kiic, tenl, vyl)
+```
+
+A `data.culture` whose culture states no `data.lang` and inherits none from its
+parent cultures:
+
+```text
+assets/content/Beings/Ada.md:5:17: error: data.culture lore-folk resolves to no language: state data.lang on the culture or on a parent culture
+```
+
+Every `data.parents` entry on a cycle, one finding for each note of the cycle,
+at the entry naming the next; a note naming itself is a cycle of one:
+
+```text
+assets/content/Places/West.md:4:19: error: data.parents.0 names place-east, which closes a parents cycle; a note is never its own ancestor
+```
+
+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 [verse in columns](authoring/links-and-markup.md#verse-in-columns) has a
@@ -313,6 +356,38 @@ a span in non-English language `vyl` holds no `.strong` emphasis
 a span takes `.emph` or `.strong`, not both
 ```
 
+## A name's ref
+
+A `ref` on a `.name` span names the note the span stands for. Each finding is an
+`error` located at the attribute part it concerns:
+
+```text
+ref "being-tomr" names no note in this package or its declared dependencies
+data-type is for a name with no note; the ref states the type
+ref= belongs on a .name span; a wikilink never takes ref
+```
+
+The first points at the `ref` value, the second at `data-type`, the third at
+`ref`. A value beginning `#` is a page-local key and resolves to no note; it is
+a finding only when it is malformed, and then at its value:
+
+```text
+ref "#" must be a note address or a page-local key such as #jane
+```
+
+A wikilink written with `{ref=…}` is an error at the wikilink, stating that its
+address is its ref.
+
+## A name's first use
+
+A name-marking finding is a `warning`: it reports and never fails lint. A
+`.name` span with no `ref` whose label is an indexed note's full name or listed
+form is reported at the span, naming the note to link or tie it to:
+
+```text
+assets/content/Lore/Ferry.md:12:1: warning: first-use/unlinked-name: “Arden” names “Arden Vale”; use a link to “test-note-place-arden”, or tie it with ref=
+```
+
 ## Native presentation is explicit
 
 `enc=` resolves an encoding document and infers its language and font.

package/docs/guides/book.md

@@ -410,7 +410,7 @@ notes the book prints.
 | ------------------------ | ----------------------------- | ---------------------------------------------------------------------------------- |
 | A note's name            | `name.sort`, else `name.full` | the page of the note's entry in **bold**, then the pages of every authored mention |
 | A name without its head  | `name.full`                   | the same pages as the note's entry, filed as `Targud, Kingdom of`                  |
-| An alias                 | `name.aliases`                | _see_ the note's name                                                              |
+| A listed name form       | `name.<code>`                 | _see_ the note's name                                                              |
 | An event's in-world name | `data.events[].names`         | _see_ the name of the note that holds the event                                    |
 
 A name that opens with a generic word a reader would not look under, such as
@@ -538,8 +538,8 @@ keeping the source available for inspection.
 A reference to a GM-only note or secret heading prints normally. GM-only notes
 remain omitted, and references to them print as text without a link. `.show`
 does not add an omitted destination to the book. Inline `[text]{.secret}` spans
-print as ordinary text, preserving emphasis, links, anchors and `.name` bold
-styling; the book ignores their `.secret` class.
+print as ordinary text, preserving emphasis, links, anchors and a name's
+first-use bold; the book ignores their `.secret` class.
 
 Secret sections and `:::secret` fences keep their visible contents in pale
 lavender boxes (`#f2eefb`) with a purple left border and title (`#5c4b8a`). The

package/docs/guides/module-project.md

@@ -800,7 +800,7 @@ each other. One JSON object per note, carrying the note's canonical address, its
 name, its description and the Foundry UUID it compiles to:
 
 ```text
-{"address":{"canonical":"bestiary-none-lore-marshdrake","slug":"lore-marshdrake"},"aliasesAscii":[],"anchors":[],"description":"A wingless drake of the reed flats, hunted for its hide and feared for its patience.","documentation":null,"file":{"folder":"Bestiary","name":"Marsh_Drake","path":"Bestiary/Marsh_Drake.md"},"foundry":{"none":{"uuid":"Compendium.acme-bestiary.journals.JournalEntry.72d497c6a8e57f57"}},"id":"72d497c6a8e57f57","name":{"full":"Marsh Drake"},"nameAscii":"Marsh Drake","package":"bestiary","shortcode":"marshdrake","subType":"bestiary","type":"lore"}
+{"address":{"canonical":"bestiary-none-lore-marshdrake","slug":"lore-marshdrake"},"anchors":[],"description":"A wingless drake of the reed flats, hunted for its hide and feared for its patience.","documentation":null,"file":{"folder":"Bestiary","name":"Marsh_Drake","path":"Bestiary/Marsh_Drake.md"},"formsAscii":{},"foundry":{"none":{"uuid":"Compendium.acme-bestiary.journals.JournalEntry.72d497c6a8e57f57"}},"id":"72d497c6a8e57f57","lang":"en","name":{"full":"Marsh Drake"},"nameAscii":"Marsh Drake","package":"bestiary","shortcode":"marshdrake","subType":"bestiary","type":"lore"}
 ```
 
 A downstream package that declares a dependency on this one fetches this file

package/docs/guides/reference-pages.md

@@ -128,9 +128,13 @@ jq -r 'select(.type == "affiliation") | .name.full' \
 ```
 
 Each note record carries its authored frontmatter together with derived
-`package`, `file`, `address`, `anchors`, and document destinations. It also has
-ASCII-folded `nameAscii` and `aliasesAscii` for searching names typed without
-diacritics. Asset files under `assets/icons`, `assets/images`, and
+`package`, `file`, `address`, `anchors`, and document destinations. Its `name`
+is the map the note authors, the full name with every other form listed under
+its language's code. It also has ASCII-folded `nameAscii` and `formsAscii`, the
+listed forms by language, for searching names typed without diacritics, and
+`lang`, the language the note is in, derived as
+[a note's language](../reference/format-details.md#a-notes-language) describes.
+A language note that `languages:` names carries its code as `languageCode`. Asset files under `assets/icons`, `assets/images`, and
 `assets/audio` have records in the same index, identified by an `asset` block.
 The index is disposable build output; regenerate it from the authored tree
 when the content changes.

package/docs/project-setup.md

@@ -473,6 +473,9 @@ need setting, and each is a decision rather than a preference.
 - **`changelog: "@changesets/changelog-git"`** attributes each entry to its
   commit. The GitHub changelog generator wants a token and produces entries
   naming pull requests, which is history the changelog does not need.
+- **`changelog: ["@heroiclands/package-build/changelog", {labels: [...]}]`** is the form
+  that also declares the labels changesets group under; see
+  [`changelog check`](commands.md#package-build-changelog-check).
 - **`privatePackages: {version: true, tag: false}`** is what makes changesets
   work at all here. Every package in the constellation is `private`, because it
   ships as a Foundry release rather than to npm; without `version: true`