@heroiclands/package-build 23.2.1 → 23.2.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @heroiclands/package-build
 
+## 23.2.2
+
+### Patch Changes
+
+A book author can list leading words such as "Kingdom of" or "Ritual:" under `pdf.indexHeads`, and the index also files those notes under the rest of the name, so "Kingdom of Targud" is found under Targud.
+
+A book whose Typst is killed, most often by the memory limit, now fails naming the signal instead of an empty reason, and a Typst that exits silently reports its exit code.
+
 ## 23.2.1
 
 ### Patch Changes

package/content-config.mjs

@@ -776,6 +776,7 @@ const PDF_KEYS = [
     "unprinted",
     "coverage",
     "indexSeeAlso",
+    "indexHeads",
     "copyright",
     "license",
 ];
@@ -1920,6 +1921,17 @@ function normalizePdf(value, rootDir, contentPackage) {
         fail("pdf.copyright", "must be one line — the licence statement is the one that runs on");
     }
 
+    /** @type {string[]} */
+    const indexHeads = [];
+    if (input.indexHeads !== undefined) {
+        if (!Array.isArray(input.indexHeads)) fail("pdf.indexHeads", "must be a list of strings");
+        input.indexHeads.forEach((head, i) => {
+            const field = `pdf.indexHeads[${i}]`;
+            if (typeof head !== "string" || !head.trim()) fail(field, "must be a non-empty string");
+            indexHeads.push(head);
+        });
+    }
+
     return Object.freeze({
         books,
         out: input.out === undefined ? "" : requireNonEmptyString(input.out, "pdf.out"),
@@ -1939,6 +1951,9 @@ function normalizePdf(value, rootDir, contentPackage) {
         // Whether an index names a note another book prints, as
         // `Name: Book title, p. N`.
         indexSeeAlso: optionalBoolean(input.indexSeeAlso, "pdf.indexSeeAlso", false),
+        // Leading words an index inverts: `Kingdom of ` files `Kingdom of
+        // Targud` again as `Targud, Kingdom of`.
+        indexHeads: Object.freeze(indexHeads),
         copyright: copyright.trim(),
         license:
             input.license === undefined ?

package/docs/configuration.md

@@ -1161,6 +1161,7 @@ The keys of `pdf` itself are shared by every book:
 | `pdf.unprinted`    | string (`WHERE` clause)       | no       | `""`                   |
 | `pdf.coverage`     | `warning` \| `error` \| `off` | no       | `warning`              |
 | `pdf.indexSeeAlso` | boolean                       | no       | `false`                |
+| `pdf.indexHeads`   | string[]                      | no       | `[]` — none inverted   |
 | `pdf.copyright`    | string (one line)             | no       | `""`                   |
 | `pdf.license`      | string (one or more lines)    | no       | `""`                   |
 
@@ -1185,6 +1186,15 @@ The keys of `pdf` itself are shared by every book:
   `Name: _Book title_, p. N` 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
+  `Kingdom of ` or `Ritual:`. Each is matched literally against the start of
+  a note's `name.full`, so a head that ends in a space includes it. A note
+  whose name opens with one is also filed in the index under the rest of its
+  name, followed by the head without its trailing space or colon: `Kingdom of
+Targud` is also listed as `Targud, Kingdom of`, with the same pages as the
+  note's own entry. Where several heads match, the longest applies. A blank
+  entry, or a value that is not a list of strings, is an error at the offending
+  key. See [The index](guides/book.md#the-index).
 - A note several books select prints in each of them. Its **home book** is the
   first book in `pdf.books` that selects it; a note a book selects twice is
   still one book's, and prints at each position. After the books are built the

package/docs/guides/book.md

@@ -409,9 +409,19 @@ notes the book prints.
 | Term                     | Source                | Shown as                                                                           |
 | ------------------------ | --------------------- | ---------------------------------------------------------------------------------- |
 | A note's name            | `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                                                              |
 | 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
+`Kingdom of Targud` or `Ritual: Blessing`, is also filed under the rest of the
+name when [`pdf.indexHeads`](../configuration.md) lists that opening: with
+`indexHeads: ["Kingdom of ", "Ritual:"]` the index lists `Targud, Kingdom of`
+and `Blessing, Ritual`, each with the pages of the note's entry. No alias is
+needed to find the note under its distinctive word. An inverted entry that would
+print the same as another note's term is told apart by the note's subtype, then
+its parent place, as any two equal terms are.
+
 To get a term into the index, give the note a `name.full`, add an alias or an
 event name, or link to the note from prose with a wikilink. A wikilink to a note
 the book prints adds the page it appears on. A term mentioned several times on

package/engine/pdf-build.mjs

@@ -86,7 +86,14 @@ import { publishesContentPages } from "../content-config.mjs";
 import { indexRecordsFor } from "./content-index.mjs";
 import { noteFile } from "./index-records.mjs";
 import { coverage, isPrintable, recordKey } from "./pdf-coverage.mjs";
-import { elsewhereFor, homeEntries, movedPages, pageTable, readEntryPages } from "./pdf-pages.mjs";
+import {
+    elsewhereFor,
+    homeEntries,
+    movedPages,
+    pageTable,
+    readEntryPages,
+    typstFailure,
+} from "./pdf-pages.mjs";
 import { cachedDependencies, openNotesDatabase, prepareTreeSqlTables } from "./sql-tables.mjs";
 import { parseDocumentTree, runTreeFilters, planDocument } from "./pdf-toc.mjs";
 import {
@@ -1166,6 +1173,7 @@ async function buildBook(book, shared) {
     // another book is a reprint, and its term is in that book's index.
     const index = {
         owns: (entry) => (shared.homes?.get(recordKey(entry.record)) ?? book.id) === book.id,
+        heads: resolved.pdf.indexHeads,
         ...(elsewhere?.seeAlso ? { foreign: elsewhere.listed } : {}),
     };
 
@@ -2054,14 +2062,7 @@ export function compileTypst(typPath, pdfPath, pdf = {}) {
         };
     }
     if (result.status !== 0) {
-        const detail = String(result.stderr || result.stdout || "")
-            .trim()
-            .split("\n")[0];
-        return {
-            ok: false,
-            message: `\`${binary} compile\` failed: ${detail}`,
-            findings: [],
-        };
+        return { ok: false, message: typstFailure(result, binary, "compile"), findings: [] };
     }
     return { ok: true, message: "", findings: typstWarnings(result.stderr) };
 }

package/engine/pdf-index.mjs

@@ -25,6 +25,9 @@
  *
  * - A note's own entry lists its name, with the entry's page in bold.
  * - An authored mention of a note in the book adds the page it appears on.
+ * - A note whose name opens with one of the book's `pdf.indexHeads` is also
+ *   filed under the rest of its name, with the head after a comma
+ *   (`Targud, Kingdom of`), and that entry carries the note's pages.
  * - An alias (`name.aliases`) and an event's in-world name
  *   (`data.events[].names`) list a cross-reference to the note's name.
  *
@@ -96,6 +99,9 @@ function letterOf(key) {
  * @param {object} [opts] - Options.
  * @param {(entry: object) => boolean} [opts.owns] - Whether this book is the
  *   entry's home. Every entry when absent.
+ * @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] -
  *   Notes another book prints, listed as `Name: Book title, p. N` once this
  *   book mentions them.
@@ -103,7 +109,8 @@ function letterOf(key) {
  *   foreign?: {title: 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 = [] } = {}) {
+export function indexTerms(entries, { owns = () => true, foreign = [], heads = [] } = {}) {
+    const byLength = [...heads].sort((a, b) => b.length - a.length);
     const terms = [];
     const info = new Map();
     const nameByCanonical = new Map();
@@ -130,6 +137,12 @@ export function indexTerms(entries, { owns = () => true, foreign = [] } = {}) {
         });
         terms.push({ name, slug, main: true });
         const taken = new Set([sortKey(name)]);
+        const head = byLength.find((one) => name.startsWith(one) && name.slice(one.length).trim());
+        if (head) {
+            const inverted = `${name.slice(head.length).trim()}, ${head.replace(/[\s:]+$/, "")}`;
+            taken.add(sortKey(inverted));
+            terms.push({ name: inverted, slug, main: false, inverted: true });
+        }
         const names = [
             ...(Array.isArray(entry.record?.name?.aliases) ? entry.record.name.aliases : []),
             ...(Array.isArray(entry.record?.data?.events) ? entry.record.data.events : []).flatMap(
@@ -174,7 +187,7 @@ export function indexTerms(entries, { owns = () => true, foreign = [] } = {}) {
     const keyed = terms.map((term, i) => ({
         name: shown[i],
         slug: term.slug,
-        ...(term.main ? {} : { see: mainShown.get(term.slug) }),
+        ...(term.main || term.inverted ? {} : { see: mainShown.get(term.slug) }),
         key: sortKey(shown[i]),
     }));
     const listed = new Set(terms.map((term) => term.slug));

package/engine/pdf-pages.mjs

@@ -66,6 +66,34 @@ export function evalArgs(typPath, fontArgs) {
     return ["eval", "--in", typPath, ...fontArgs, PAGES_EXPRESSION];
 }
 
+/**
+ * Say why a finished Typst process failed.
+ *
+ * A process killed by a signal has no exit status and prints nothing, so the
+ * signal is named; `SIGKILL` is the kernel's out-of-memory kill. Otherwise the
+ * first line the compiler printed is the reason, and the exit code stands in
+ * when it printed none.
+ *
+ * @param {{status: number | null, signal: string | null, stderr?: string | null, stdout?: string | null}} result -
+ *   The finished process.
+ * @param {string} binary - The Typst binary.
+ * @param {string} subcommand - The Typst subcommand that ran.
+ * @returns {string} The reason, ready to follow the failing command's name.
+ */
+export function typstFailure(result, binary, subcommand) {
+    const command = `\`${binary} ${subcommand}\``;
+    if (result.signal) {
+        const hint = result.signal === "SIGKILL" ? " (most often the memory limit)" : "";
+        return `${command} was killed by ${result.signal}${hint}`;
+    }
+    const detail = String(result.stderr || result.stdout || "")
+        .trim()
+        .split("\n")[0];
+    return detail ?
+            `${command} failed: ${detail}`
+        :   `${command} exited with code ${result.status} and printed nothing`;
+}
+
 /**
  * Measure the page each labelled entry of a book starts on.
  *
@@ -87,12 +115,7 @@ export function readEntryPages(typPath, fontArgs, binary = "typst") {
         return fail(`could not run \`${binary}\`: ${err.message}`);
     }
     if (result.error) return fail(`could not run \`${binary}\`: ${result.error.message}`);
-    if (result.status !== 0) {
-        const detail = String(result.stderr || result.stdout || "")
-            .trim()
-            .split("\n")[0];
-        return fail(`\`${binary} eval\` failed: ${detail}`);
-    }
+    if (result.status !== 0) return fail(typstFailure(result, binary, "eval"));
     let rows;
     try {
         rows = JSON.parse(result.stdout);

package/hugo-theme/layouts/_default/baseof.html

@@ -15,7 +15,7 @@
        enough — the system deliberately uses no Pro-only icons — and the
        game-icons webfont is subset to just the glyphs the docs reference
        (~3 KB), generated by the SoHL repo. */}}
-  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.1/css/all.min.css" crossorigin="anonymous" referrerpolicy="no-referrer">
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.3.1/css/all.min.css" crossorigin="anonymous" referrerpolicy="no-referrer">
   <link rel="stylesheet" href="{{ "css/sohl-icons.css" | relURL }}">
 </head>
 <body>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.2.1",
+    "version": "23.2.2",
     "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/engine/pdf-index.d.mts

@@ -17,6 +17,9 @@ export function indexMarker(slug: string, main?: boolean): string;
  * @param {object} [opts] - Options.
  * @param {(entry: object) => boolean} [opts.owns] - Whether this book is the
  *   entry's home. Every entry when absent.
+ * @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] -
  *   Notes another book prints, listed as `Name: Book title, p. N` once this
  *   book mentions them.
@@ -24,8 +27,9 @@ export function indexMarker(slug: string, main?: boolean): string;
  *   foreign?: {title: 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 }?: {
+export function indexTerms(entries: object[], { owns, foreign, heads }?: {
     owns?: ((entry: object) => boolean) | undefined;
+    heads?: string[] | undefined;
     foreign?: {
         slug: string;
         name: string;

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

@@ -10,6 +10,26 @@
  * @returns {string[]} The arguments, in order.
  */
 export function evalArgs(typPath: string, fontArgs: string[]): string[];
+/**
+ * Say why a finished Typst process failed.
+ *
+ * A process killed by a signal has no exit status and prints nothing, so the
+ * signal is named; `SIGKILL` is the kernel's out-of-memory kill. Otherwise the
+ * first line the compiler printed is the reason, and the exit code stands in
+ * when it printed none.
+ *
+ * @param {{status: number | null, signal: string | null, stderr?: string | null, stdout?: string | null}} result -
+ *   The finished process.
+ * @param {string} binary - The Typst binary.
+ * @param {string} subcommand - The Typst subcommand that ran.
+ * @returns {string} The reason, ready to follow the failing command's name.
+ */
+export function typstFailure(result: {
+    status: number | null;
+    signal: string | null;
+    stderr?: string | null;
+    stdout?: string | null;
+}, binary: string, subcommand: string): string;
 /**
  * Measure the page each labelled entry of a book starts on.
  *