@heroiclands/package-build 23.12.3 → 23.12.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @heroiclands/package-build
 
+## 23.12.4
+
+### Patch Changes
+
+A PDF book may declare a short `abbreviation`, so references into it read `(Aelw. p307)` instead of naming the full title, and the other books' indexes list its notes the same way.
+
+In PDF books, a definition list sets its term in bold at the start of the line with the description running on after it, indented on later lines, and no space appears between a linked name and the punctuation that follows it.
+
+`project init` scaffolds the build workflow at `.gitea/workflows/build.yml`, and `project check` and `package-build ci` read it from there.
+
 ## 23.12.3
 
 ### Patch Changes

package/ci/ci-steps.mjs

@@ -18,7 +18,7 @@
  * of the command list is a second statement of one thing, and the copy is the
  * one that goes stale — silently, because a pre-push check that runs four of
  * five steps still exits 0. So the steps are parsed out of
- * `.github/workflows/build.yml` at run time and there is nothing to keep in
+ * `.gitea/workflows/build.yml` at run time and there is nothing to keep in
  * step.
  *
  * **It refuses rather than assumes.** If the workflow's shape changes so that
@@ -28,7 +28,7 @@
  *
  * **What it cannot run**, and says so: a `uses:` step is a published action, not
  * a command — the forbidden-marker check, the coverage upload. Those stay
- * GitHub's to run, and the summary names them so the gap is visible rather than
+ * CI's to run, and the summary names them so the gap is visible rather than
  * assumed away.
  *
  * **It parses the workflow itself rather than importing a YAML library**, for a
@@ -64,7 +64,7 @@ const ROOT = process.cwd();
  * failed*. Mirrors the same constant in `ci-docker.mjs`.
  */
 export const UNAVAILABLE = 2;
-const WORKFLOW_DIR = path.join(ROOT, ".github/workflows");
+const WORKFLOW_DIR = path.join(ROOT, ".gitea/workflows");
 
 /**
  * The workflow's steps, split into what can be run here and what cannot.
@@ -77,7 +77,7 @@ export function ciSteps() {
     const files = prTriggeredWorkflows();
     if (!files.length) {
         throw new NoWorkflow(
-            `no workflow under .github/workflows is triggered by \`pull_request\`, ` +
+            `no workflow under .gitea/workflows is triggered by \`pull_request\`, ` +
                 `so there is nothing here that a pull request would run.`,
         );
     }
@@ -236,7 +236,7 @@ function main() {
         });
         if (result.status !== 0) {
             console.error(
-                `\nci-steps: FAILED at "${step.name}" — this is what GitHub would report.\n` +
+                `\nci-steps: FAILED at "${step.name}" — this is what CI would report.\n` +
                     `  Fix it, or push with --no-verify if you mean to.`,
             );
             return result.status ?? 1;

package/content-config.mjs

@@ -787,6 +787,7 @@ const PDF_KEYS = [
 const PDF_BOOK_KEYS = [
     "id",
     "title",
+    "abbreviation",
     "subtitle",
     "coverImage",
     "front",
@@ -1813,6 +1814,8 @@ function normalizeSite(value) {
  * @typedef {object} ResolvedPdfBook
  * @property {string} id          Its name on the command line, `--book <id>`.
  * @property {string} title
+ * @property {string} abbreviation  Names the book in another book's
+ *                                references; `""` when none is declared.
  * @property {string} subtitle    `""` when none is declared.
  * @property {string} coverImage  Absolute; `""` when none is declared.
  *                                Whether the file exists is checked when the
@@ -1984,6 +1987,8 @@ function normalizePdfBooks(value, rootDir, contentPackage) {
     const ids = new Set();
     /** @type {Map<string, number>} Stem → the book that took it. */
     const stems = new Map();
+    /** @type {Map<string, string>} Abbreviation → the id of the book that took it. */
+    const abbreviations = new Map();
     return Object.freeze(
         value.map((entry, i) => {
             const where = `pdf.books[${i}]`;
@@ -2003,6 +2008,19 @@ function normalizePdfBooks(value, rootDir, contentPackage) {
             if (ids.has(id)) fail(`${where}.id`, `is \`${id}\`, which names a book more than once`);
             ids.add(id);
             const title = requireNonEmptyString(book.title, `${where}.title`);
+            let abbreviation = "";
+            if (book.abbreviation !== undefined) {
+                abbreviation = requireNonEmptyString(book.abbreviation, `${where}.abbreviation`);
+                const holder = abbreviations.get(abbreviation);
+                if (holder !== undefined) {
+                    fail(
+                        `${where}.abbreviation`,
+                        `is \`${abbreviation}\`, which books \`${holder}\` and \`${id}\` both ` +
+                            "declare — a reader could not tell which book to open",
+                    );
+                }
+                abbreviations.set(abbreviation, id);
+            }
 
             // One tree, from exactly one place: two would leave the reader to
             // guess which is printed, and none prints nothing.
@@ -2059,6 +2077,7 @@ function normalizePdfBooks(value, rootDir, contentPackage) {
             return Object.freeze({
                 id,
                 title,
+                abbreviation,
                 subtitle:
                     book.subtitle === undefined ?
                         ""

package/docs/commands.md

@@ -128,16 +128,16 @@ package-build ci [--native]
 
 The default command runs in Docker on Linux against a clean export of the
 current commit. It reads the repository's pull-request workflows under
-`.github/workflows/` and runs their `run:` steps in workflow order. A failed
+`.gitea/workflows/` and runs their `run:` steps in workflow order. A failed
 step stops the replay. Uncommitted changes are absent from the clean export.
 
 `--native` runs the same steps on the host in the current working tree. It
 needs no Docker and includes uncommitted changes, but its operating system and
-existing files can differ from a clean GitHub runner. The steps themselves
+existing files can differ from a clean CI runner. The steps themselves
 still come from the workflow files.
 
 The command lists `uses:` steps that it cannot run locally. A successful replay
-covers the listed `run:` steps; GitHub runs the published actions separately.
+covers the listed `run:` steps; the forge runs the published actions separately.
 Workflow steps may install dependencies, generate files, or perform other
 declared build actions.
 
@@ -2632,7 +2632,8 @@ Typst compiler; `--no-compile` emits the Typst source and stops there,
 which is what lets the source be inspected or compiled by hand.
 
 A reference to a note that another book is home to prints that book and page,
-`Name (_Book title_, p. 12)`. A compile renders and lays out every book, writes
+`Name (_Book title_, p. 12)`, or `Name (Aelw. p12)` when that book declares an
+`abbreviation`. A compile renders and lays out every book, writes
 `pages.json` (each note's home book and the page its entry starts on) into the
 output directory, and renders again with those pages; `--no-compile` runs
 neither pass and prints `p. ?`. See the

package/docs/configuration.md

@@ -1156,6 +1156,7 @@ pdf:
   books:
     - id: core
       title: The World of Thalorna
+      abbreviation: Thal.
       subtitle: A Song of Heroic Lands Sourcebook
       coverImage: assets/images/covers/core.webp
       document: book.yaml
@@ -1209,7 +1210,8 @@ The keys of `pdf` itself are shared by every book:
 
 - `pdf.indexSeeAlso` adds a line to a book's index for each note that another
   book prints and this book mentions in authored prose, written
-  `Name: _Book title_, p. N` with the page the note's entry starts on in its
+  `Name: _Book title_, p. N` (or `Name: Aelw. p307` when that book declares an
+  `abbreviation`) with the page the note's entry starts on in its
   home book. It is `false` by default, and the index then lists only the notes
   the book is home to. See [The index](guides/book.md#the-index).
 - `pdf.indexHeads` lists leading words that open many names, such as
@@ -1236,20 +1238,29 @@ Targud` is also listed as `Targud, Kingdom of`, with the same pages as the
 
 Each entry of `pdf.books` is one PDF:
 
-| Key                      | Type                      | Required       | Default                 |
-| ------------------------ | ------------------------- | -------------- | ----------------------- |
-| `pdf.books[].id`         | string                    | yes            | —                       |
-| `pdf.books[].title`      | string                    | yes            | —                       |
-| `pdf.books[].subtitle`   | string                    | no             | `""`                    |
-| `pdf.books[].coverImage` | string (path)             | no             | `""` — no cover         |
-| `pdf.books[].front`      | string[] (markdown files) | no             | `[]`                    |
-| `pdf.books[].out`        | string (file stem)        | no             | `<contentPackage>-<id>` |
-| `pdf.books[].contents`   | list (the tree, inline)   | one of the two | —                       |
-| `pdf.books[].document`   | string (path to the tree) | one of the two | —                       |
+| Key                        | Type                      | Required       | Default                   |
+| -------------------------- | ------------------------- | -------------- | ------------------------- |
+| `pdf.books[].id`           | string                    | yes            | —                         |
+| `pdf.books[].title`        | string                    | yes            | —                         |
+| `pdf.books[].abbreviation` | string                    | no             | `""` — the title names it |
+| `pdf.books[].subtitle`     | string                    | no             | `""`                      |
+| `pdf.books[].coverImage`   | string (path)             | no             | `""` — no cover           |
+| `pdf.books[].front`        | string[] (markdown files) | no             | `[]`                      |
+| `pdf.books[].out`          | string (file stem)        | no             | `<contentPackage>-<id>`   |
+| `pdf.books[].contents`     | list (the tree, inline)   | one of the two | —                         |
+| `pdf.books[].document`     | string (path to the tree) | one of the two | —                         |
 
 - `id` is lowercase letters, digits and hyphens, starting with a letter or
   digit. It is what `--book <id>` names and the tail of the default file stem.
   Each `id` is used once.
+- `abbreviation` is a short name for the book, such as `Aelw.`. It is used only
+  where another book refers to this one: a reference to a note this book
+  prints reads `Name (Aelw. p307)`, with a non-breaking space between the
+  abbreviation and the page, and the other book's index, when
+  `pdf.indexSeeAlso` is on, lists the note as `Name: Aelw. p307`. A book
+  with no abbreviation is named by its full title in italics, `Name (_Book
+title_, p. 307)`. Each abbreviation is used once, since a reader could not
+  tell which book to open from one shared by two.
 - `contents` is the tree written inline — the same `sectionName` /
   `contents` / `filter` / `file` shape a tree file holds under its own
   `contents:` key — and `document` names the file holding it. A book declares
@@ -1296,6 +1307,10 @@ file, line and column the key is written at:
 
 > ``package-build config: `pdf.books[0].title` must be a non-empty string.``
 
+> ``package-build config: `pdf.books[0].abbreviation` must be a non-empty string.``
+
+> ``package-build config: `pdf.books[1].abbreviation` is `Thal.`, which books `core` and `vedyara` both declare — a reader could not tell which book to open.``
+
 > ``package-build config: `pdf.books[0]` must declare exactly one of `contents` and `document` — the tree written inline, or the file holding it.``
 
 > ``package-build config: `pdf.books[0].out` is `dist/core`, which is not a file stem — letters, digits, `.`, `_` and `-`, with no directory; the directory is `pdf.out`.``
@@ -1304,7 +1319,7 @@ file, line and column the key is written at:
 
 > ``package-build config: `pdf.books[0].front` must be a list of markdown files.``
 
-> ``package-build config: `pdf.books[0].<key>` is not a recognized option (expected one of: id, title, subtitle, coverImage, front, out, contents, document).``
+> ``package-build config: `pdf.books[0].<key>` is not a recognized option (expected one of: id, title, abbreviation, subtitle, coverImage, front, out, contents, document).``
 
 > ``package-build config: `pdf.coverage` must be one of: warning, error, off.``
 

package/docs/guides/book.md

@@ -174,11 +174,11 @@ the Lyrebird Inn (The Tenebrae Volume, p. 214)
 
 Which form a wikilink takes depends on where its target is printed:
 
-| The target is                                                 | The link prints                           |
-| ------------------------------------------------------------- | ----------------------------------------- |
-| An entry of the same book, including a note the book reprints | An internal destination                   |
-| An entry of another book, and not of this one                 | `Name (_Book title_, p. N)`, with no link |
-| A note in no book                                             | The web address of the note's page        |
+| The target is                                                 | The link prints                                                                      |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| An entry of the same book, including a note the book reprints | An internal destination                                                              |
+| An entry of another book, and not of this one                 | `Name (_Book title_, p. N)`, or `Name (Aelw. pN)` with an abbreviation, with no link |
+| A note in no book                                             | The web address of the note's page                                                   |
 
 The page is the page the PDF itself numbers, which is the number printed in the
 footer and used by the contents and the index, so the printed `p. N` is the
@@ -438,7 +438,7 @@ first book in `pdf.books` that selects it. In a package of several books:
   as the cross-book references (`pages.json`), so the page a reference prints
   for a note is the page its home book's index lists for the note's own entry.
 - A mention of a note another book prints is not a term of the mentioning
-  book. The mention reads `Name (_Book title_, p. N)` in the text, and the note's
+  book. The mention reads `Name (_Book title_, p. N)` in the text (`Name (Aelw. pN)` when the home book declares an `abbreviation`), and the note's
   entry and its page are in the other book's index.
 
 Set [`pdf.indexSeeAlso`](../configuration.md) to `true` to list those mentions
@@ -447,6 +447,8 @@ then has a line, filed under its name:
 
 > Sword: _Book A_, p. 12
 
+A home book with an `abbreviation` files the line as `Sword: BkA. p12`.
+
 Two kinds of link add nothing:
 
 - **Links in generated sections** such as "Within" or "Governed by". They name

package/docs/guides/release-and-deploy.md

@@ -182,17 +182,14 @@ release runs in two halves, one on each:
    pushes the tag `v<version>` at the merged version commit. Releasing from
    Gitea is switched on by the repository variable `HL_RELEASE_ENABLED`.
 2. **Publish, on GitHub.** The push mirror carries the tag to GitHub, where it
-   starts the **Publish to npm** workflow, `.github/workflows/release.yml`. It
-   refuses a tag that names a commit outside `main` or that is not
-   `v<version>` of the tagged `package.json`. When npm does not have the
-   version yet, it runs the tests and publishes through npm Trusted Publishing
-   with provenance. It then creates the GitHub Release from the version's
-   changelog section, unless one exists.
+   starts the **Publish to npm** workflow, `.github/workflows/release.yml`, the
+   only workflow GitHub runs. Every check has already run on Gitea before the
+   tag exists, so the workflow installs, publishes through npm Trusted
+   Publishing with provenance, and creates the GitHub Release from the
+   version's changelog section.
 
 Nothing on Gitea publishes to npm, and nothing on GitHub runs for a branch
-push. Every step of the GitHub half is safe to repeat: re-running it, or
-dispatching it with the tag as its ref, finishes a release whose publish or
-Release step failed and changes nothing for one that completed. The
+push. The
 [npm package page](https://www.npmjs.com/package/@heroiclands/package-build)
 shows the published version and README.
 

package/docs/project-setup.md

@@ -513,7 +513,7 @@ tool:
 organisation-level and defined in `HeroicLands/.github`, so the repository
 carries no label registry of its own.
 
-`.github/workflows/` then carries the repository's own CI. The org-wide
+`.gitea/workflows/` carries the repository's own CI. The org-wide
 `HeroicLands/.github` repository supplies the shared composite actions those
 workflows `uses:` — `labels`, `no-attribution` and `todos` — plus the reusable
 site-deploy workflow, so a fix to any of them reaches every repository at once.
@@ -522,16 +522,16 @@ site-deploy workflow, so a fix to any of them reaches every repository at once.
 
 A summary, because "where does this come from" is the question that recurs.
 
-| Read                          | By                                                                                                        |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `package.json`                | The Foundry package id, the version, the release addresses; the site's `baseURL`, description and author. |
-| `package-build.config.yaml`   | Everything else about the build.                                                                          |
-| `assets/content/**/*.md`      | Every content command.                                                                                    |
-| `.gitignore`                  | `package-build format`, `package-build markdown`.                                                         |
-| `.prettierignore`             | `package-build format`.                                                                                   |
-| `lang/*.json`                 | `package-build lang`.                                                                                     |
-| `.env.local`                  | `package-build deploy`.                                                                                   |
-| `.github/workflows/build.yml` | The `pre-push` hook, for its step list.                                                                   |
+| Read                         | By                                                                                                        |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `package.json`               | The Foundry package id, the version, the release addresses; the site's `baseURL`, description and author. |
+| `package-build.config.yaml`  | Everything else about the build.                                                                          |
+| `assets/content/**/*.md`     | Every content command.                                                                                    |
+| `.gitignore`                 | `package-build format`, `package-build markdown`.                                                         |
+| `.prettierignore`            | `package-build format`.                                                                                   |
+| `lang/*.json`                | `package-build lang`.                                                                                     |
+| `.env.local`                 | `package-build deploy`.                                                                                   |
+| `.gitea/workflows/build.yml` | The `pre-push` hook, for its step list.                                                                   |
 
 Everything written goes under `build/`. Nothing the toolchain generates is
 committed.

package/engine/pdf-build.mjs

@@ -780,6 +780,7 @@ export async function buildPdf({
             books: buildable.map((b) => ({
                 id: b.entry.id,
                 title: b.entry.title,
+                abbreviation: b.entry.abbreviation,
                 plan: b.selection.plan,
             })),
             homes,

package/engine/pdf-index.mjs

@@ -102,11 +102,13 @@ function letterOf(key) {
  * @param {string[]} [opts.heads] - Leading words (`pdf.indexHeads`) matched
  *   literally against the start of a name; a name that opens with one is also
  *   listed as `<rest>, <head>`, the head without its trailing space or colon. None when absent.
- * @param {Array<{slug: string, name: string, title: string, page: string|number}>} [opts.foreign] -
+ * @param {Array<{slug: string, name: string, title: string, abbreviation?: string,
+ *   page: string|number}>} [opts.foreign] -
  *   Notes another book prints, listed as `Name: Book title, p. N` once this
- *   book mentions them.
+ *   book mentions them, or `Name: Aelw. p12` when the home book has an
+ *   abbreviation.
  * @returns {Array<{letter: string, name: string, slug: string, see?: string,
- *   foreign?: {title: string, page: string}}>} Terms with `see` set for a
+ *   foreign?: {title: string, abbreviation?: string, page: string}}>} Terms with `see` set for a
  *   cross-reference to the main name it points at.
  */
 export function indexTerms(entries, { owns = () => true, foreign = [], heads = [] } = {}) {
@@ -198,7 +200,11 @@ export function indexTerms(entries, { owns = () => true, foreign = [], heads = [
         keyed.push({
             name,
             slug: other.slug,
-            foreign: { title: String(other.title), page: String(other.page) },
+            foreign: {
+                title: String(other.title),
+                ...(other.abbreviation ? { abbreviation: String(other.abbreviation) } : {}),
+                page: String(other.page),
+            },
             key: sortKey(name),
         });
     }
@@ -234,7 +240,7 @@ export function indexTerms(entries, { owns = () => true, foreign = [], heads = [
 export function indexPreamble({ seeAlso = false } = {}) {
     return [
         // Zero-size and invisible; the label is what the chapter queries.
-        "#let book-ix(key, main: false) = [#metadata((key: key, main: main)) <book-index>]",
+        "#let book-ix(key, main: false) = [#metadata((key: key, main: main))<book-index>]",
         "#let book-index(terms) = context {",
         "  set par(justify: false, first-line-indent: 0em, hanging-indent: 1em, spacing: 0.45em)",
         "  set text(size: 8.8pt)",
@@ -271,7 +277,12 @@ export function indexPreamble({ seeAlso = false } = {}) {
         ...(seeAlso ?
             [
                 "    if away != none {",
-                "      par[#term.name: #emph[#away.title], p. #away.page]",
+                '      let short = away.at("abbreviation", default: none)',
+                "      if short != none {",
+                "        par[#term.name: #short~p#away.page]",
+                "      } else {",
+                "        par[#term.name: #emph[#away.title], p. #away.page]",
+                "      }",
                 "      continue",
                 "    }",
             ]
@@ -309,8 +320,11 @@ export function indexChapter(entries, title, opts = {}) {
             }${
                 term.foreign === undefined ?
                     ""
-                :   `, foreign: (title: "${escapeString(term.foreign.title)}", ` +
-                    `page: "${escapeString(term.foreign.page)}")`
+                :   `, foreign: (title: "${escapeString(term.foreign.title)}", ${
+                        term.foreign.abbreviation === undefined ?
+                            ""
+                        :   `abbreviation: "${escapeString(term.foreign.abbreviation)}", `
+                    }` + `page: "${escapeString(term.foreign.page)}")`
             })`,
     );
     return [

package/engine/pdf-pages.mjs

@@ -142,7 +142,7 @@ export function readEntryPages(typPath, fontArgs, binary = "typst") {
  *   The books that render, in configuration order.
  * @param {Map<string, string>} input.homes - Each note's key → its home book's
  *   id, from {@link module:engine/pdf-coverage.coverage}.
- * @returns {Array<{key: string, book: string, title: string, anchor: string,
+ * @returns {Array<{key: string, book: string, title: string, abbreviation?: string, anchor: string,
  *   record: object, slug: string, aliases: string[]}>} One per homed note, in book order and
  *   then entry order.
  */
@@ -160,6 +160,7 @@ export function homeEntries({ books, homes }) {
                 key,
                 book: book.id,
                 title: book.title,
+                abbreviation: book.abbreviation,
                 anchor: entry.anchor,
                 record,
                 slug: String(record?.address?.slug ?? record?.shortcode ?? ""),
@@ -246,13 +247,21 @@ export function elsewhereFor({ entries, book, printed, table, seeAlso = false })
         const keys = [entry.slug, ...entry.aliases].filter((key) => key && !printed.has(key));
         const page = table?.[entry.key]?.page ?? UNMEASURED_PAGE;
         for (const key of keys) {
-            if (!map.has(key)) map.set(key, { slug: entry.slug, title: entry.title, page });
+            if (!map.has(key)) {
+                map.set(key, {
+                    slug: entry.slug,
+                    title: entry.title,
+                    abbreviation: entry.abbreviation,
+                    page,
+                });
+            }
         }
         if (seeAlso && entry.slug && !printed.has(entry.slug)) {
             listed.push({
                 slug: entry.slug,
                 name: String(entry.record?.name?.full ?? "").trim(),
                 title: entry.title,
+                abbreviation: entry.abbreviation,
                 page,
             });
         }

package/engine/pdf-render.mjs

@@ -841,12 +841,10 @@ function renderBlock(tokens, i, out, ctx) {
 }
 
 /**
- * Self-contained dictionary rows with the website's 150 CSS-pixel hanging indent.
- *
- * Each row remains a breakable block; only the bold term is an inline box. The
- * negative first-line space lets its label start at the original margin while
- * subsequent paragraphs, lists and blocks retain the definition's inset. A long
- * term enlarges its slot without changing the continuation margin.
+ * Definition rows set as a book sets them: the term in bold, run in at the
+ * margin, and the definition following on the same line, with its continuation
+ * lines and any further paragraphs, lists and blocks indented 1em. A long term
+ * takes no more room than a short one. Rows are spaced as paragraphs are.
  *
  * Scope the helper to this list so exported Markdown fragments also work without
  * a book preamble, including nested definition lists.
@@ -854,18 +852,12 @@ function renderBlock(tokens, i, out, ctx) {
  * @returns {string} Typst markup.
  */
 function renderDefinitionList(entries) {
-    return `#context {
-  let book-definition(term, body) = {
-    let indent = 112.5pt
-    let gap = (0.75em).to-absolute()
-    let label = text(weight: "bold", term)
-    let slot = calc.max(indent - gap, measure(label).width)
-    block(width: 100%, breakable: true, inset: (left: indent), above: 0pt, below: 0.5em)[
-      #set par(first-line-indent: 0pt, hanging-indent: 0pt)
-      #set text(weight: "regular")
-      #h(-indent)#box(width: slot, label)#h(gap)#body
-    ]
-  }
+    return `#{
+  let book-definition(term, body) = block(width: 100%, breakable: true, inset: (left: 1em))[
+    #set par(first-line-indent: 0pt, hanging-indent: 0pt)
+    #set text(weight: "regular")
+    #h(-1em)#text(weight: "bold", term)#h(0.5em)#body
+  ]
   ${entries.join("\n  ")}
 }`;
 }
@@ -1457,17 +1449,22 @@ function renderLink(href, inner, ctx) {
 
 /**
  * A reference to a note another book prints, as Typst: the words the link
- * carried, then the book and the page, `Name (_Book title_, p. 12)`.
+ * carried, then the book and the page. A book with an abbreviation reads
+ * `Name (Aelw. p12)`; one without reads `Name (_Book title_, p. 12)`.
  *
- * The space before the page number does not break, so a number never starts a
- * line of its own.
+ * The space before the page number, or between the abbreviation and the page,
+ * does not break, so a number never starts a line of its own.
  *
  * @param {string} inner - The already-rendered link text.
- * @param {{title: string, page: string|number}} away - The home book's title
- *   and the page the entry starts on.
+ * @param {{title: string, abbreviation?: string, page: string|number}} away -
+ *   The home book's title, its abbreviation when it declares one, and the page
+ *   the entry starts on.
  * @returns {string} Typst markup.
  */
 export function crossBookReference(inner, away) {
+    if (away.abbreviation) {
+        return `${inner} (${escapeTypst(away.abbreviation)}~p${away.page})`;
+    }
     return `${inner} (#emph[${escapeTypst(away.title)}], p.~${away.page})`;
 }
 

package/engine/project-init.mjs

@@ -308,7 +308,7 @@ function projectText(answers) {
             "Labels are organization-level, defined in `HeroicLands/.github`.",
             "",
         ].join("\n"),
-        ".github/workflows/build.yml": [
+        ".gitea/workflows/build.yml": [
             "# SPDX-License-Identifier: GPL-3.0-or-later",
             "name: Build and Test",
             "on:",
@@ -424,7 +424,7 @@ export function checkProject(rootDir) {
         "LICENSE.md",
         ".changeset/config.json",
         ".github/ISSUE_REPORTING.md",
-        ".github/workflows/build.yml",
+        ".gitea/workflows/build.yml",
     ];
     for (const file of required) {
         if (!fs.existsSync(path.join(root, file))) add(file, "required project file is missing");

package/githooks/pre-push

@@ -1,16 +1,16 @@
 #!/usr/bin/env sh
 #
 # Before pushing, run exactly what the Build & Test workflow runs — in a
-# container, over a clean export of HEAD — so a red GitHub check is something
+# container, over a clean export of HEAD — so a red CI check is something
 # you chose rather than something you discover.
 #
 # The steps are not listed here. `ci/ci-steps.mjs` reads them out of
-# `.github/workflows/build.yml`, because a hook holding its own copy of the
+# `.gitea/workflows/build.yml`, because a hook holding its own copy of the
 # command list is a second statement of one thing, and the copy is the one that
 # goes stale — silently, since running four of five steps still exits 0.
 #
 # **On push rather than at `gh pr create`**, because a push is where this
-# repository's work reaches GitHub: normally one, just before the pull request.
+# repository's work reaches the forge: normally one, just before the pull request.
 # Nothing to remember, no wrapper command, and no entry in package.json — the
 # hook is the whole mechanism.
 #
@@ -92,7 +92,7 @@ status=$?
 # 2 means the check could not run — no Docker — which is not the same as a
 # failure and must not stop the push. Whoever is pushing may not be the
 # maintainer, may be on a machine without Docker, and is entitled to open a
-# pull request; GitHub is what enforces the workflow. Said loudly, though: a
+# pull request; CI is what enforces the workflow. Said loudly, though: a
 # skipped check that reads like a passed one is how a guard loses its meaning.
 # 127 is "could not execute it at all" — no node on PATH, package not
 # installed. Infrastructure, not a verdict, so it is handled the same way.
@@ -104,6 +104,6 @@ fi
 
 if [ "$status" -ne 0 ]; then
     echo ""
-    echo "pre-push: refusing to push — GitHub would report the same failure."
+    echo "pre-push: refusing to push — CI would report the same failure."
     exit 1
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.12.3",
+    "version": "23.12.4",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/content-config.d.mts

@@ -159,6 +159,11 @@ export type ResolvedPdfBook = {
      */
     id: string;
     title: string;
+    /**
+     * Names the book in another book's
+     * references; `""` when none is declared.
+     */
+    abbreviation: string;
     /**
      * `""` when none is declared.
      */

package/types/engine/pdf-index.d.mts

@@ -20,11 +20,13 @@ export function indexMarker(slug: string, main?: boolean): string;
  * @param {string[]} [opts.heads] - Leading words (`pdf.indexHeads`) matched
  *   literally against the start of a name; a name that opens with one is also
  *   listed as `<rest>, <head>`, the head without its trailing space or colon. None when absent.
- * @param {Array<{slug: string, name: string, title: string, page: string|number}>} [opts.foreign] -
+ * @param {Array<{slug: string, name: string, title: string, abbreviation?: string,
+ *   page: string|number}>} [opts.foreign] -
  *   Notes another book prints, listed as `Name: Book title, p. N` once this
- *   book mentions them.
+ *   book mentions them, or `Name: Aelw. p12` when the home book has an
+ *   abbreviation.
  * @returns {Array<{letter: string, name: string, slug: string, see?: string,
- *   foreign?: {title: string, page: string}}>} Terms with `see` set for a
+ *   foreign?: {title: string, abbreviation?: string, page: string}}>} Terms with `see` set for a
  *   cross-reference to the main name it points at.
  */
 export function indexTerms(entries: object[], { owns, foreign, heads }?: {
@@ -34,6 +36,7 @@ export function indexTerms(entries: object[], { owns, foreign, heads }?: {
         slug: string;
         name: string;
         title: string;
+        abbreviation?: string;
         page: string | number;
     }[] | undefined;
 }): Array<{
@@ -43,6 +46,7 @@ export function indexTerms(entries: object[], { owns, foreign, heads }?: {
     see?: string;
     foreign?: {
         title: string;
+        abbreviation?: string;
         page: string;
     };
 }>;

package/types/engine/pdf-pages.d.mts

@@ -57,7 +57,7 @@ export function readEntryPages(typPath: string, fontArgs: string[], binary?: str
  *   The books that render, in configuration order.
  * @param {Map<string, string>} input.homes - Each note's key → its home book's
  *   id, from {@link module:engine/pdf-coverage.coverage}.
- * @returns {Array<{key: string, book: string, title: string, anchor: string,
+ * @returns {Array<{key: string, book: string, title: string, abbreviation?: string, anchor: string,
  *   record: object, slug: string, aliases: string[]}>} One per homed note, in book order and
  *   then entry order.
  */
@@ -74,6 +74,7 @@ export function homeEntries({ books, homes }: {
     key: string;
     book: string;
     title: string;
+    abbreviation?: string;
     anchor: string;
     record: object;
     slug: string;

package/types/engine/pdf-render.d.mts

@@ -166,18 +166,21 @@ export function markdownToTypst(markdown: string, opts?: {
 export function absolutePageUrl(url: string, site?: string): string;
 /**
  * A reference to a note another book prints, as Typst: the words the link
- * carried, then the book and the page, `Name (_Book title_, p. 12)`.
+ * carried, then the book and the page. A book with an abbreviation reads
+ * `Name (Aelw. p12)`; one without reads `Name (_Book title_, p. 12)`.
  *
- * The space before the page number does not break, so a number never starts a
- * line of its own.
+ * The space before the page number, or between the abbreviation and the page,
+ * does not break, so a number never starts a line of its own.
  *
  * @param {string} inner - The already-rendered link text.
- * @param {{title: string, page: string|number}} away - The home book's title
- *   and the page the entry starts on.
+ * @param {{title: string, abbreviation?: string, page: string|number}} away -
+ *   The home book's title, its abbreviation when it declares one, and the page
+ *   the entry starts on.
  * @returns {string} Typst markup.
  */
 export function crossBookReference(inner: string, away: {
     title: string;
+    abbreviation?: string;
     page: string | number;
 }): string;
 /**

package/ci/confirm-npm-version.mjs

@@ -1,135 +0,0 @@
-/*
- * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
- * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
- *
- * This work is licensed under the GNU General Public License v3.0 (GPLv3).
- * You may copy, modify, and distribute it under the terms of that license.
- *
- * For full terms, see the LICENSE.md file in the project root or visit:
- * https://www.gnu.org/licenses/gpl-3.0.html
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- */
-
-/**
- * Asserts that npm serves an exact package version.
- *
- * `npm publish` returns before the registry serves the new version, and a
- * version that is accepted but never served is indistinguishable from success
- * by the publish alone. This polls `npm view <name>@<version> version` until
- * it prints the version, then exits 0. When the time budget runs out it exits 1
- * with an `::error::` annotation naming the package, the version and the last
- * registry answer.
- *
- * Usage: `node ci/confirm-npm-version.mjs <name> <version> [--interval <s>]
- * [--timeout <s>]`. The defaults are 15 seconds between queries and 600 seconds
- * overall.
- */
-
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-
-/** Seconds between registry queries. */
-export const DEFAULT_INTERVAL_SECONDS = 15;
-/** Seconds the registry has to serve the version. */
-export const DEFAULT_TIMEOUT_SECONDS = 600;
-
-/**
- * Ask the registry which version `name@version` resolves to.
- *
- * @param {string} spec - `<name>@<version>`.
- * @returns {string} The version npm printed, or its error text when the query
- *   fails (an unpublished version answers E404).
- */
-export function queryNpm(spec) {
-    const result = spawnSync("npm", ["view", spec, "version"], { encoding: "utf8" });
-    if (result.error) return result.error.message;
-    const out = (result.stdout ?? "").trim();
-    if (result.status === 0) return out;
-    const err = (result.stderr ?? "").trim().replace(/\s*\n\s*/g, " | ");
-    return err || out || `npm exited ${result.status}`;
-}
-
-/**
- * Poll until the registry serves `version` of `name`.
- *
- * @param {object} options
- * @param {string} options.name - Package name.
- * @param {string} options.version - Exact version expected.
- * @param {(spec: string) => string} [options.query] - Registry query; returns
- *   the registry's answer for `<name>@<version>`.
- * @param {(ms: number) => Promise<void>} [options.sleep] - Waits between queries.
- * @param {number} [options.intervalSeconds] - Seconds between queries.
- * @param {number} [options.timeoutSeconds] - Seconds before giving up.
- * @param {(line: string) => void} [options.log] - Progress output.
- * @returns {Promise<{ok: true, attempts: number} | {ok: false, attempts: number, last: string}>}
- */
-export async function confirmNpmVersion({
-    name,
-    version,
-    query = queryNpm,
-    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-    intervalSeconds = DEFAULT_INTERVAL_SECONDS,
-    timeoutSeconds = DEFAULT_TIMEOUT_SECONDS,
-    log = () => {},
-}) {
-    const spec = `${name}@${version}`;
-    const attemptLimit = Math.floor(timeoutSeconds / intervalSeconds) + 1;
-    let last = "";
-    for (let attempts = 1; attempts <= attemptLimit; attempts++) {
-        last = query(spec);
-        if (last === version) {
-            log(`${spec} is served by npm.`);
-            return { ok: true, attempts };
-        }
-        log(`${spec} is not served yet (${last || "empty answer"}).`);
-        if (attempts < attemptLimit) await sleep(intervalSeconds * 1000);
-    }
-    return { ok: false, attempts: attemptLimit, last };
-}
-
-function parseArguments(argv) {
-    const positional = [];
-    const options = {};
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === "--interval" || arg === "--timeout") {
-            const value = Number(argv[++i]);
-            if (!Number.isFinite(value) || value <= 0) {
-                throw new Error(`${arg} takes a positive number of seconds.`);
-            }
-            options[arg === "--interval" ? "intervalSeconds" : "timeoutSeconds"] = value;
-        } else if (arg.startsWith("--")) {
-            throw new Error(`Unknown option ${arg}.`);
-        } else {
-            positional.push(arg);
-        }
-    }
-    if (positional.length !== 2) {
-        throw new Error(
-            "Usage: confirm-npm-version.mjs <name> <version> [--interval <s>] [--timeout <s>]",
-        );
-    }
-    return { name: positional[0], version: positional[1], ...options };
-}
-
-async function main(argv) {
-    let options;
-    try {
-        options = parseArguments(argv);
-    } catch (error) {
-        console.error(`::error::${error.message}`);
-        return 2;
-    }
-    const outcome = await confirmNpmVersion({ ...options, log: (line) => console.log(line) });
-    if (outcome.ok) return 0;
-    const timeout = options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
-    console.error(
-        `::error::npm does not serve ${options.name}@${options.version} after ${timeout}s and ${outcome.attempts} queries. Last registry answer: ${outcome.last || "(empty)"}`,
-    );
-    return 1;
-}
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-    process.exitCode = await main(process.argv.slice(2));
-}