@heroiclands/package-build 23.12.6 → 23.12.8

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @heroiclands/package-build
 
+## 23.12.8
+
+### Patch Changes
+
+A `packageBuild.assets` row that copies files into `icons/` or `images/` now ships them beside the staged pictures instead of having them erased. A shipped picture whose path matches a file a row already staged is an error, and the row's file is left as it was.
+
+## 23.12.7
+
+### Patch Changes
+
+**Writing in the setting's languages and scripts**
+
+- Text can be marked with its language and set in one of the HeroicLands fonts, or in plain serif, sans or monospace, on the site, in Foundry and in books.
+- Roman spelling converts into a script through a mapping note, which takes a word from the language's dictionary when the dictionary spells it differently.
+- `package-build transliterate` and `package-build lexicon` show a passage or a word exactly as a build sets it.
+- Converted text is checked against its language, and an unknown word or unregistered name is reported where it is written.
+- A language's present endings can replace its infinitive ending, as Vylari's do.
+
 ## 23.12.6
 
 ### Patch Changes

package/assets/styles/content-base.css

@@ -164,6 +164,31 @@
     --poetry-indent: 10em;
 }
 
+/* Text set in one of the faces. The font family and features come from the
+ * face's own class; a right-to-left block or verse reads from the right. */
+.script-block {
+    margin: 1rem 0;
+    line-height: 1.7;
+}
+
+.script-block[dir="rtl"],
+.poetry[dir="rtl"] {
+    text-align: start;
+}
+
+/* Text set in the reader's generic families, `font=serif`, `sans` and `mono`. */
+.font-serif {
+    font-family: serif;
+}
+
+.font-sans {
+    font-family: sans-serif;
+}
+
+.font-mono {
+    font-family: monospace;
+}
+
 /*
  * Historical info/warn section classes remain available for styled prose.
  * New alerts use the separate alert classes below.

package/bin/content-commands.mjs

@@ -30,6 +30,8 @@
  *   npx package-build site [--out <dir>]
  *   npx package-build map [--tree] [--from <shortcode>] [--chart <shortcode>] [--travel] [--out <dir>]
  *   npx package-build reachability <dir> [file] [--index <shortcode>]
+ *   npx package-build transliterate <map> [--lang <language>] [--font <slug>] [--hex] [text..]
+ *   npx package-build lexicon <language> --map <map> [--font <slug>] [--json]
  *   npx package-build addresses diff --from <zip|dir> [--strict]
  *   npx package-build npc new (--spec <json> | --specfile <path>) [--seed <text>] [--out <path>]
  *
@@ -62,7 +64,19 @@ import {
     unaddressableForeignPackages,
     formatUnaddressableFinding,
 } from "../engine/metadata-index.mjs";
-import { fetchNavigation, generateHugoConfig, writeHugoConfig } from "../engine/site-config.mjs";
+import {
+    fetchNavigation,
+    generateHugoConfig,
+    HUGO_SOURCE,
+    writeHugoConfig,
+} from "../engine/site-config.mjs";
+import {
+    checkScriptFonts,
+    copyScriptFonts,
+    scriptFontFiles,
+    SITE_FONTS_DIR,
+    siteFontsDestination,
+} from "../engine/script-font-delivery.mjs";
 import { renderItemFieldReference, renderItemFieldsPage } from "../engine/field-reference.mjs";
 import { checkDocLinks, checkDocIndex } from "../engine/docs-checks.mjs";
 import { checkArtSlotSizes } from "../engine/art-fields.mjs";
@@ -102,6 +116,14 @@ import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { schemaSubtypeOf } from "../engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
 import { markupFindings } from "../engine/markup-validation.mjs";
+import { runContext } from "../engine/content-scripts.mjs";
+import {
+    checkLexiconNatives,
+    checkMapFonts,
+    languageNoteFindings,
+    lexiconEntries,
+    transliterate,
+} from "../engine/map-lexicon.mjs";
 import { checkFormatting, checkPrettierConventions, lintMarkdown } from "../engine/prose-lint.mjs";
 import { lintProse, scoreProseTree } from "../engine/readability-lint.mjs";
 import { loadPackageBuildConfig } from "../config.mjs";
@@ -300,6 +322,8 @@ export function registerContentCommands(cli) {
         )
         .command(withIndexPreflight(mapCommand()))
         .command(withIndexPreflight(reachabilityCommand()))
+        .command(transliterateCommand())
+        .command(lexiconCommand())
         .command(addressesCommand())
         .command(withIndexPreflight(npcCommand()));
 }
@@ -461,7 +485,7 @@ function withBodyPreflight(
                         :   undefined;
                     const records = session?.records ?? indexRecordsFor({ config, contentBase });
                     if (session?.problems.length) {
-                        emitDiagnostic(session.problems[0]);
+                        for (const problem of session.problems) emitDiagnostic(problem);
                         process.exitCode = 1;
                         return;
                     }
@@ -1257,10 +1281,19 @@ function lintCommand() {
                     assetsBase: config.paths.assets,
                 });
 
+                // Text marked with a language, a font or a map, checked against
+                // the languages this package declares, the faces it installed
+                // and the maps its notes declare.
+                const runs = runContext(config, records);
                 const findings = [
                     ...index.notes.flatMap((note) =>
-                        markupFindings(note.raw, note.file, session.syntax),
+                        markupFindings(note.raw, note.file, session.syntax, runs),
                     ),
+                    // Each mapping note's faces, each language's native forms
+                    // and each language's `note`, against the faces and maps.
+                    ...index.notes.flatMap((note) => checkMapFonts(note, runs)),
+                    ...index.notes.flatMap((note) => checkLexiconNatives(note, runs)),
+                    ...languageNoteFindings({ ...config, configFile: packConfigPath() }, records),
                     ...index.notes.flatMap(firstUseChecker),
                     ...(names ? [names] : []),
                     ...addresses.findings,
@@ -1891,6 +1924,38 @@ function pdfCommand() {
     };
 }
 
+/**
+ * Copy the installed script fonts into the Hugo static tree, under a path that
+ * names their version, and drop any other version's copy.
+ *
+ * A package that has not installed `@heroiclands/fonts`, or sets no text in
+ * one of its faces, gets no copy; a package missing a file its fonts depend on
+ * gets a located error and a non-zero exit.
+ *
+ * @param {object} config - The resolved content configuration.
+ * @returns {void}
+ */
+function stageSiteFonts(config) {
+    const root = path.join(config.rootDir, HUGO_SOURCE, "static", SITE_FONTS_DIR);
+    fs.rmSync(root, { recursive: true, force: true });
+    const found = scriptFontFiles(config, ["woff2"]);
+    if (!found) return;
+    const findings = checkScriptFonts(config);
+    for (const finding of findings) emitDiagnostic(finding);
+    if (findings.length) {
+        process.exitCode = 1;
+        return;
+    }
+    const dest = path.join(
+        config.rootDir,
+        HUGO_SOURCE,
+        "static",
+        siteFontsDestination(found.version),
+    );
+    const count = copyScriptFonts(config, dest, ["woff2"]);
+    log.info(`wrote ${count} script font file(s) to ${path.relative(process.cwd(), dest)}`);
+}
+
 /**
  * `package-build site` — publish the content tree as a website.
  *
@@ -2077,6 +2142,7 @@ function siteCommand() {
                 );
                 const { file } = writeHugoConfig(config, hugo);
                 log.info(`wrote ${path.relative(process.cwd(), file)}`);
+                stageSiteFonts(config);
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -2241,6 +2307,201 @@ function mapCommand() {
     };
 }
 
+/**
+ * The run context a mapping command reads: the content index's maps and
+ * lexicons, and the configured languages and installed faces, exactly as the
+ * build has them.
+ *
+ * @returns {{config: object, ctx: object}|undefined} The context, or
+ *   `undefined` when the content tree could not be read whole, which is
+ *   reported.
+ */
+function mappingContext() {
+    const config = loadPackConfig();
+    const problems = [];
+    const records = indexRecordsFor({
+        contentBase: config.paths.content,
+        config,
+        skipDirectories: config.skipDirectories,
+        problems,
+    });
+    for (const problem of problems) emitDiagnostic(problem);
+    if (problems.length) return undefined;
+    return { config, ctx: runContext(config, records) };
+}
+
+/**
+ * Report what a mapping command was given that names nothing: an unknown
+ * language at the configuration's `languages`, and an unknown map or face at
+ * the content tree, where mapping notes are. A word the rows cannot
+ * capitalise is in the passage given, so it has no file.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {{problem: string, about: string}} found - What is wrong.
+ * @param {string} [lang] - The language asked for.
+ */
+function reportMapping(config, found) {
+    if (found.about === "lang") {
+        const file = packConfigPath();
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        } catch {
+            text = undefined;
+        }
+        emitDiagnostic({
+            file,
+            ...(text ? positionOfYamlPath(text, ["languages"], { key: true }) : {}),
+            severity: "error",
+            message: found.problem,
+        });
+    } else if (found.about === "word")
+        // A word of the passage given, which sits in no file.
+        emitDiagnostic({ severity: "error", message: found.problem });
+    else emitDiagnostic({ file: config.paths.content, severity: "error", message: found.problem });
+    process.exitCode = 1;
+}
+
+/**
+ * `package-build transliterate <map> [text..]` — map a passage exactly as the
+ * build maps a run marked with the same `map=`, `lang=` and `font=`.
+ *
+ * @returns {object} The yargs command module.
+ */
+// eslint-disable-next-line
+function transliterateCommand() {
+    return {
+        command: "transliterate <map> [text..]",
+        describe: "Map a passage into a script exactly as the build maps a marked run",
+        builder: (yargs) =>
+            yargs
+                .positional("map", {
+                    type: "string",
+                    describe: "The `data.map.name` of a mapping note",
+                })
+                .positional("text", {
+                    type: "string",
+                    array: true,
+                    describe: "The passage; `-` or nothing reads it from stdin",
+                })
+                .option("lang", {
+                    type: "string",
+                    describe: "A declared language, whose lexicon is read first",
+                })
+                .option("font", {
+                    type: "string",
+                    describe: "The face; required when the map lists more than one",
+                })
+                .option("hex", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Print the code points, as `U+XXXX` separated by spaces",
+                }),
+        handler: (argv) => {
+            try {
+                const read = mappingContext();
+                if (!read) {
+                    process.exitCode = 1;
+                    return;
+                }
+                const words = (argv.text ?? []).map(String);
+                const text =
+                    !words.length || (words.length === 1 && words[0] === "-") ?
+                        fs.readFileSync(0, "utf8").replace(/\r?\n$/, "")
+                    :   words.join(" ");
+                const mapped = transliterate(
+                    read.ctx,
+                    { map: String(argv.map), lang: argv.lang, font: argv.font },
+                    text,
+                );
+                if ("problem" in mapped) {
+                    reportMapping(read.config, mapped);
+                    return;
+                }
+                console.log(
+                    argv.hex ?
+                        Array.from(
+                            mapped.text,
+                            (char) =>
+                                `U+${char.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}`,
+                        ).join(" ")
+                    :   mapped.text,
+                );
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
+/**
+ * `package-build lexicon <language> --map <map>` — every word of a language's
+ * lexicon with its native form under a map, as the build writes it.
+ *
+ * @returns {object} The yargs command module.
+ */
+// eslint-disable-next-line
+function lexiconCommand() {
+    return {
+        command: "lexicon <language>",
+        describe: "List a language's words with their native forms under a map",
+        builder: (yargs) =>
+            yargs
+                .positional("language", {
+                    type: "string",
+                    describe: "A declared language whose `note` names its language note",
+                })
+                .option("map", {
+                    type: "string",
+                    demandOption: true,
+                    describe: "The `data.map.name` of a mapping note",
+                })
+                .option("font", {
+                    type: "string",
+                    describe: "The face; required when the map lists more than one",
+                })
+                .option("json", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Print a JSON array rather than tab-separated lines",
+                }),
+        handler: (argv) => {
+            try {
+                const read = mappingContext();
+                if (!read) {
+                    process.exitCode = 1;
+                    return;
+                }
+                const listed = lexiconEntries(read.ctx, {
+                    lang: String(argv.language),
+                    map: String(argv.map),
+                    font: argv.font,
+                });
+                if ("problem" in listed) {
+                    reportMapping(read.config, listed);
+                    return;
+                }
+                if (argv.json) console.log(JSON.stringify(listed.entries, null, 2));
+                else
+                    for (const entry of listed.entries)
+                        console.log(
+                            [
+                                entry.form,
+                                entry.native,
+                                entry.exception ? "exception" : "rows",
+                                entry.class ?? "",
+                                entry.gloss ?? "",
+                            ].join("\t"),
+                        );
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
 /**
  * `package-build reachability <dir> [file]` — check that a corpus reads through.
  *

package/bin/package-build.mjs

@@ -96,6 +96,11 @@ import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pac
 import { cleanBuildArtifacts, resetStage, stageAssets } from "../stage.mjs";
 import { rowsStagingPictureRoots, stagePackageAssets } from "../engine/asset-shipping.mjs";
 import { baseStyleStageEntry } from "../engine/base-styles.mjs";
+import {
+    checkScriptFonts,
+    copyScriptFonts,
+    STAGED_FONTS_DIR,
+} from "../engine/script-font-delivery.mjs";
 import {
     CDN_ENV,
     cdnCredentials,
@@ -576,6 +581,26 @@ function assetsCommand() {
                 count += staged.entries;
                 files += staged.files;
             }
+
+            // The installed fonts, when the package has installed the fonts
+            // package and a note sets text in one of its faces: the
+            // stylesheet, the WOFF2 files and the licence, which the
+            // manifest's `styles` names.
+            const fontFindings = checkScriptFonts(packConfig);
+            if (fontFindings.length) {
+                const error = new Error(fontFindings.map(formatDiagnostic).join("\n"));
+                error.located = true;
+                die(error);
+            }
+            const fonts = copyScriptFonts(
+                packConfig,
+                path.resolve(config.rootDir, config.stageDir, STAGED_FONTS_DIR),
+                ["woff2"],
+            );
+            if (fonts) {
+                count += 1;
+                files += fonts;
+            }
             console.log(`✅ Static assets staged (${count} entries, ${files} files).`);
         }),
     };

package/content-config.mjs

@@ -70,6 +70,7 @@ import { normalizeCurrentDate } from "./engine/current-date.mjs";
 // Leaves with no local imports of their own, so naming them here cannot close
 // a cycle around a consumer's config file (see `engine/pack-config.mjs`).
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-charset.mjs";
+import { isLanguageTag } from "./engine/language-tag.mjs";
 import { ASSET_TYPE_NAMES, shippingLicensesProblem } from "./engine/asset-types.mjs";
 import { isReservedPackage } from "./engine/packages.mjs";
 import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.mjs";
@@ -614,6 +615,9 @@ export function publishesContentPages(config) {
  *                                          `{ system, builders }` registries
  *                                          instead, and the accepted type
  *                                          vocabulary is their union.
+ * @property {Record<string, LanguageSpec>} [languages]  The languages a
+ *                                          note may tag text with, by short
+ *                                          name. Default `{}`.
  * @property {PackSpec[]} packs             Packs to compile. More than one entry
  *                                          may share a `type`: a note then names
  *                                          the pack it belongs in with its
@@ -719,6 +723,8 @@ export function publishesContentPages(config) {
  *                                     fonts this package ships and the names it
  *                                     draws from them; empty when it declares
  *                                     none.
+ * @property {Readonly<Record<string, Readonly<LanguageSpec>>>} languages
+ *                                     Frozen; `{}` when absent.
  * @property {readonly Readonly<ResolvedPackSpec>[]} packs
  * @property {readonly string[]} packDirectories  Derived: every pack directory
  *                                     the build produces, in compile order —
@@ -747,6 +753,7 @@ const CONFIG_KEYS = [
     "skipDirectories",
     "forbidGeneratedArt",
     "icons",
+    "languages",
     "packs",
     "docs",
     "site",
@@ -937,6 +944,70 @@ function normalizeDefaultCalendar(value) {
     return /** @type {string} */ (value);
 }
 
+/**
+ * One entry of `languages`.
+ *
+ * @typedef {object} LanguageSpec
+ * @property {string} tag   Its BCP 47 tag. A constructed language takes
+ *                          `art-x-<name>`.
+ * @property {string} [note] The Address of its language note, whose
+ *                          `data.words` is the lexicon a mapped run in the
+ *                          language reads first.
+ */
+
+/**
+ * What a language name may be: lowercase letters, digits and single hyphens,
+ * starting with a letter. Lowercase keeps two names from differing only in
+ * case, which an index keyed by them cannot tell apart.
+ */
+const LANGUAGE_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+/**
+ * Check `languages` and freeze it.
+ *
+ * @param {unknown} value - The configured mapping.
+ * @returns {Readonly<Record<string, Readonly<LanguageSpec>>>} The frozen
+ *   mapping; `{}` when absent.
+ */
+function normalizeLanguages(value) {
+    if (value === undefined || value === null) return Object.freeze({});
+    if (!isPlainObject(value)) fail("languages", "must be a mapping of language name to `{tag}`");
+    const out = {};
+    for (const [name, entry] of Object.entries(/** @type {object} */ (value))) {
+        const where = `languages.${name}`;
+        if (!LANGUAGE_NAME.test(name))
+            fail(
+                where,
+                "is not a name: a name is lowercase letters, digits and single hyphens, " +
+                    "starting with a letter",
+            );
+        if (!isPlainObject(entry)) fail(where, "must be a mapping with `tag`");
+        rejectUnknownKeys(entry, ["tag", "note"], `${where}.`);
+        const { tag, note } = /** @type {Record<string, unknown>} */ (entry);
+        if (tag === undefined || tag === null || tag === "")
+            fail(
+                `${where}.tag`,
+                "must be a BCP 47 language tag, such as `art-x-vyl` for a constructed language",
+            );
+        if (!isLanguageTag(tag))
+            fail(
+                `${where}.tag`,
+                `${String(tag)} is not a valid BCP 47 language tag; a constructed ` +
+                    "language takes `art-x-<name>`",
+            );
+        if (note !== undefined && (typeof note !== "string" || note.trim() === ""))
+            fail(
+                `${where}.note`,
+                "must be the Address of a language note, such as `skill-vylarilng`",
+            );
+        out[name] = Object.freeze({
+            tag: /** @type {string} */ (tag),
+            ...(note === undefined ? {} : { note: /** @type {string} */ (note) }),
+        });
+    }
+    return Object.freeze(out);
+}
+
 /**
  * @param {object} object
  * @param {readonly string[]} allowed
@@ -3075,6 +3146,7 @@ export function defineConfig(config) {
         skipDirectories: Object.freeze(skipDirectories),
         forbidGeneratedArt,
         icons: normalizeIcons(input.icons, rootDir),
+        languages: normalizeLanguages(input.languages),
         packs: Object.freeze(packs),
         packDirectories: Object.freeze(packDirectories),
         docs: normalizeDocs(input.docs),

package/docs/api.md

@@ -2535,15 +2535,16 @@ The wildcard engine subpath exposes
 `@heroiclands/package-build/engine/dictionary-rows` for deriving the
 `dictionary` and `terms` SQL relations from content-index records:
 
-| Export                  | Signature                                       | Returns                                     | Use it when                                                             |
-| ----------------------- | ----------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
-| `DICTIONARY_COLUMNS`    | `const DICTIONARY_COLUMNS`                      | A readonly list of column names             | Declaring the schema of a language's dictionary.                        |
-| `TERM_COLUMNS`          | `const TERM_COLUMNS`                            | A readonly list of column names             | Declaring the schema of owner-specific glossary terms.                  |
-| `ETYMOLOGY_KEYS`        | `const ETYMOLOGY_KEYS`                          | A readonly list of keys                     | Reading the structure of a dictionary word's etymology.                 |
-| `dictionaryLetter`      | `dictionaryLetter(text)`                        | `string`                                    | Deriving a heading letter from a sort key.                              |
-| `dictionaryEntryAnchor` | `dictionaryEntryAnchor(language, name)`         | `string`                                    | Deriving the stable entry anchor for a word in a language's dictionary. |
-| `dictionaryAndTermRows` | `dictionaryAndTermRows(records, all = records)` | `{ dictionary: object[], terms: object[] }` | Deriving dictionary words and glossary terms for the selected records.  |
-| `serializeRows`         | `serializeRows(rows)`                           | `string`                                    | Writing deterministic JSON Lines with keys sorted at every depth.       |
+| Export                  | Signature                                       | Returns                                     | Use it when                                                                                        |
+| ----------------------- | ----------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `DICTIONARY_COLUMNS`    | `const DICTIONARY_COLUMNS`                      | A readonly list of column names             | Declaring the schema of a language's dictionary.                                                   |
+| `TERM_COLUMNS`          | `const TERM_COLUMNS`                            | A readonly list of column names             | Declaring the schema of owner-specific glossary terms.                                             |
+| `ETYMOLOGY_KEYS`        | `const ETYMOLOGY_KEYS`                          | A readonly list of keys                     | Reading the structure of a dictionary word's etymology.                                            |
+| `dictionaryLetter`      | `dictionaryLetter(text)`                        | `string`                                    | Deriving a heading letter from a sort key.                                                         |
+| `dictionaryEntryAnchor` | `dictionaryEntryAnchor(language, name)`         | `string`                                    | Deriving the stable entry anchor for a word in a language's dictionary.                            |
+| `dictionaryAndTermRows` | `dictionaryAndTermRows(records, all = records)` | `{ dictionary: object[], terms: object[] }` | Deriving dictionary words and glossary terms for the selected records.                             |
+| `serializeRows`         | `serializeRows(rows)`                           | `string`                                    | Writing deterministic JSON Lines with keys sorted at every depth.                                  |
+| `pluralOf`              | `pluralOf(word, grammar)`                       | `string \| null`                            | Deriving a noun's plural: its own `plural`, else the first `grammar.plural` row whose ending fits. |
 
 `dictionaryEntryAnchor` takes the language's canonical Address and the
 word's form. Its `word-` anchor is derived from the full SHA-256 digest of

package/docs/authoring/assets.md

@@ -47,7 +47,7 @@ role: portrait
 
 ## What the Foundry package ships
 
-The repository keeps every picture; the Foundry package carries a filtered copy, laid out flat. A picture ships when its record says `ai: false` and its licence is one of `LicenseRef-PublicDomain`, `CC0-1.0`, `CC0`, `CC-BY-3.0`, `CC-BY-4.0`, `CC-BY-SA-4.0` or `LicenseRef-NounProject-Pro`, together with any licence the package adds under `packageBuild.shippingLicenses`. A shipped picture sits at `icons/<basename>` or `images/<basename>` at the package root, whatever directories it is kept in here, and the package's asset set, `asset-sets/default.json`, lists what it ships.
+The repository keeps every picture; the Foundry package carries a filtered copy, laid out flat. A picture ships when its record says `ai: false` and its licence is one of `LicenseRef-PublicDomain`, `CC0-1.0`, `CC0`, `CC-BY-3.0`, `CC-BY-4.0`, `CC-BY-SA-4.0` or `LicenseRef-NounProject-Pro`, together with any licence the package adds under `packageBuild.shippingLicenses`. A shipped picture sits at `icons/<basename>` or `images/<basename>` at the package root, whatever directories it is kept in here, and the package's asset set, `asset-sets/default.json`, lists what it ships. A `packageBuild.assets` row may copy other files under `icons/` or `images/`; the shipped pictures are written beside them, and a row's file at the same path as a shipped picture is an error.
 
 A note may still name a picture the package does not ship. Its compiled document draws the package's stand-in instead — `icons/missing.<ext>` or `images/missing.<ext>`, which you provide as an ordinary human-made picture licensed to ship, addressed `<package>-none-icon-missing` and `<package>-none-image-missing` — and keeps the real picture's address, so a world that holds the real file can point back at it. A package that leaves out a picture a note names, and ships no stand-in of that type, fails the build at the note. See [what a package ships](../reference/format-details.md#what-a-package-ships).