create-asciidoc-multi-book-workspace 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.7.0 - 2026-10-31
+
+### Removed
+
+- The generated workspace has no `check` command. `pnpm run build` is the only way to render, and `check` ran the same path only so the runtime's checks could be run on their own.
+- The runtime no longer judges a workspace: `XREF_UNRESOLVED`, `XREF_AMBIGUOUS`, `HTML_RESOURCE_MISSING`, `HTML_ANCHOR_MISSING`, `CATALOG_TARGET_MISSING`, `BOOK_MISSING_FROM_CATALOG`, and `MISSING_DOCTYPE` are gone. Whether a reference reaches one heading is read from the `asciidoc-abundant-tree` projection by the tool that reads it; the build fails only where it cannot produce the pages: a missing `catalog.adoc` or book, any Asciidoctor message, an include graph that cannot be parsed within `documentRoot` or an error-level parse diagnostic, or a configuration or include resolver it cannot use.
+
+### Changed
+
+- Generated workspaces depend on `asciidoc-abundant-tree` `^0.6.0`. Its label space is four predicates on the heading nodes of the graph, and an xref whose address several headings own gets an edge to each of them. The runtime rewrites an HTML link only when its xref reaches exactly one section, inside a book and across books; any other xref is left as Asciidoctor wrote it. The document title owns labels but is not a section, so an xref to a title only the document title owns is left as written.
+- The samples no longer say a check reports broken references. After renaming a heading, an author searches the book for the old name, which finds every reference written by it (qualified addresses included), its link text, and the prose. The structured writing conventions sample states where an unbound or ambiguous link lands on the page (an unbound one is broken; one that several headings share lands on the first of them), shows the projection as `asciidoc-abundant-tree` 0.6 writes it (heading nodes named by the projector, addresses as `aat:headline` and `aat:addressPath` values), and lists a title that starts with inline markup among those a reference cannot name by their text.
+
+### Upgrading an existing workspace
+
+Create a temporary workspace with `pnpm create asciidoc-multi-book-workspace@0.7.0 tmp-books` and copy its `tools/adoc-books.mjs` over yours. In your `package.json`, remove the `check` script, set `"asciidoc-abundant-tree": "^0.6.0"`, and run `pnpm install`. Books need no change. To find references that reach no heading or several, read the projection: an xref edge (`aat:XrefEdge`) carries one `aat:targetHeading` for each heading its address reaches.
+
+## 0.6.0 - 2026-10-31
+
+### Added
+
+- `pnpm run check` binds a qualified address: when several headings share a title, a book refers to one of them by writing the titles above it, joined with `::`, as in `xref:红烧肉::火候[]` or, across books, `xref:{dish-book}#红烧肉::火候[]`. The HTML link reaches that heading.
+
+### Changed
+
+- Generated workspaces depend on `asciidoc-abundant-tree` `^0.3.0`. Which xrefs exist and what their targets say are now read by Asciidoctor inside it, and the runtime no longer works around its gaps: xrefs inside passthroughs (`pass:[…]`, `+++…+++`, `$$…$$`, `` `+…+` ``) or escaped with `\` are not checked; `xref:` targets with spaces are bound and checked; `xref:#id[]` names `id`; an attribute reference in a target takes its value at the xref's position, where it used to take the value the book held after conversion; `xref:other#x[]` without `.adoc` names the document `other`, as Asciidoctor links it. The projection itself changed in 0.3.0 (fields are `field:<name>`, heading nodes are named by their address); tools that read it follow that release's changelog.
+- The structured writing conventions sample teaches qualified addresses for shared titles, written with link text that joins the titles with an interpunct (《红烧肉·火候》). Two headings that share a title under one parent are renamed so each title says what its section is (糖醋排骨's two 炸 become 初炸 and 复炸); a custom ID is the second address only for a title that cannot serve, with rules for naming it. After a rename, an author also searches the book for the old name in link text and prose, which the check does not report. The projection example shows heading nodes named by their address and the field predicate `field:难度`, and the fields chapter states that a field name in an attrlist uses only letters, digits, `_`, and `-`. `00-book-anatomy` and the `04-reference-manual` glossary say the same about custom IDs.
+
+### Upgrading an existing workspace
+
+A generated workspace owns its `tools/adoc-books.mjs`, and this release changes it. Create a temporary workspace with `pnpm create asciidoc-multi-book-workspace@0.6.0 tmp-books`, copy its `tools/adoc-books.mjs` over yours, set `"asciidoc-abundant-tree": "^0.3.0"` in your `package.json`, and run `pnpm install`. Books need no change; a heading that declares an ID only to tell it apart from others with the same title can drop the ID once its references use the qualified address.
+
 ## 0.5.1 - 2026-10-23
 
 ### Changed

package/README.md

@@ -97,7 +97,6 @@ The generated scripts are:
 
 ```bash
 pnpm run build
-pnpm run check
 pnpm run clean
 ```
 

package/dist/runtime/adoc-books.mjs

@@ -5,13 +5,15 @@ import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promi
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import asciidoctorFactory from "@asciidoctor/core";
-import { parseAbundantTree } from "asciidoc-abundant-tree";
+import { parseAbundantTree, rdf12 } from "asciidoc-abundant-tree";
 const require = createRequire(import.meta.url);
 const DIAGRAM_BLOCK_PATTERN = /^\[(?:actdiag|blockdiag|bpmn|bytefield|c4plantuml|d2|dbml|ditaa|erd|excalidraw|graphviz|mermaid|nomnoml|nwdiag|packetdiag|pikchr|plantuml|rackdiag|seqdiag|svgbob|symbolator|umlet|vega|vegalite|wavedrom|structurizr|diagramsnet|wireviz)(?:,|\])/m;
-const CATALOG_BOOK_XREF_PATTERN = /xref:books\/([^/\]]+)\/book\.adoc(?:#[^\[]+)?\[/g;
-const LOCAL_TARGET_PATTERN = /\b(href|src)="([^"]+)"/g;
 const HTML_ANCHOR_PATTERN = /\b(?:id|name)="([^"]+)"/g;
-const SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+const AAT_NAMESPACE = "https://micheng.dev/ns/asciidoc-abundant-tree#";
+// 标题投影的 label space：aat 图上标题节点的这四个谓词（aat 06 号书第 2 章「地址与 Label 空间」）。
+const LABEL_PREDICATES = ["headline", "addressPath", "addressLabel", "generatedAddressLabel"];
+const HTML_FRAGMENT_LINK_PATTERN = /<a href="#([^"]*)"([^>]*)>([\s\S]*?)<\/a>/g;
+const HTML_DOCUMENT_LINK_PATTERN = /<a href="([^"#]+\.html)#([^"]*)"([^>]*)>([\s\S]*?)<\/a>/g;
 const HOME_MARKER = "data-multi-book-home";
 const CONTROLS_MARKER = "data-multi-book-controls";
 const FETCH_DIAGRAMS_ENV = "ADOC_BOOKS_FETCH_DIAGRAMS";
@@ -322,8 +324,9 @@ function convertFile(asciidoctor, extensionRegistry, input, outputFile, baseDir,
     const defaultLogger = loggerManager.getLogger();
     const memoryLogger = asciidoctor.MemoryLogger.create();
     loggerManager.setLogger(memoryLogger);
+    let document;
     try {
-        asciidoctor.convertFile(input, {
+        document = asciidoctor.convertFile(input, {
             safe: "unsafe",
             base_dir: baseDir,
             to_file: outputFile,
@@ -339,6 +342,7 @@ function convertFile(asciidoctor, extensionRegistry, input, outputFile, baseDir,
     if (messages.length > 0) {
         throw new Error(`AsciiDoc strict check failed for ${input}\n${messages.map(formatAsciidoctorMessage).join("\n")}`);
     }
+    return document;
 }
 async function buildHtml(rootDir, books, asciidoctor, extensionRegistry, useKroki, fetchDiagrams) {
     await mkdir(path.join(rootDir, "build", "html"), { recursive: true });
@@ -462,16 +466,18 @@ function sourceBundleFromDocument(document) {
     }).join("\n");
 }
 // 解析失败就让构建失败，不退回只有封面的阅读页：退回时 include 越过 documentRoot 只剩一条 warning，
-// 构建照常成功，没有人发现阅读页坏了（DESIGN.adoc 的 Workspace Contract Checks）。
+// 构建照常成功，没有人发现阅读页坏了（DESIGN.adoc 的 Rendering Failures）。
 async function buildReaderBookData(config, book) {
+    let parsed;
     let document;
     try {
-        document = await parseAbundantTree({
+        parsed = await parseAbundantTree({
             sourcePath: book.input,
             mode: "book-entry",
             documentRoot: config.documentRoot,
             includeResolvers: config.includeResolvers
         });
+        document = parsed;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -490,7 +496,9 @@ async function buildReaderBookData(config, book) {
     const sections = (Array.isArray(document.children) ? document.children : []).filter((child) => {
         return typeof child === "object" && child !== null && child.kind === "section";
     });
-    const frontmatterStyles = new Set(["abstract", "colophon", "dedication", "preface", "acknowledgments"]);
+    // abstract 不在其中：它是 article 的样式，book 里的 [abstract] 被 Asciidoctor 当作编号的一章，阅读器照它渲染的样子
+    // 当章节显示（docs/design/book-dual-reader-view.adoc 的 Page Map）。
+    const frontmatterStyles = new Set(["colophon", "dedication", "preface", "acknowledgments"]);
     const backmatterStyles = new Set(["appendix", "glossary", "bibliography", "index"]);
     const frontmatter = sections.filter((section) => section.level === 1 && frontmatterStyles.has(sectionStyle(section) ?? ""));
     if (frontmatter.length > 0) {
@@ -543,8 +551,125 @@ async function buildReaderBookData(config, book) {
     };
     return {
         pageMap,
-        sourceBundle: sourceBundleFromDocument(document)
+        sourceBundle: sourceBundleFromDocument(document),
+        references: bindReferences(config, parsed)
+    };
+}
+// 书内 xref 落在哪一节，读 aat 的投影（DESIGN.adoc 的 Reference Binding）：哪些是 xref、目标写的是什么（透传与转义
+// 不算，属性已展开，指向别的文档的另记 targetDocument）由 aat 里的 Asciidoctor 读出，一处引用对上几节就有几条
+// targetHeading。链接只能跳到一处，所以恰好一节才改写；零节或几节保持 Asciidoctor 写下的样子，不替人挑，也不报：
+// 引用对不对是投影的读者（bookgraph）的解释，不是渲染的事（DESIGN.adoc 的 Division of Labour）。
+function bindReferences(config, document) {
+    const projection = rdf12(document, { documentRoot: config.documentRoot });
+    const graph = projection.graph;
+    const values = (subject, name) => {
+        return graph.match({ subject, predicate: { termType: "iri", value: `${AAT_NAMESPACE}${name}` } })
+            .map((triple) => triple.object.termType === "triple" ? "" : triple.object.value);
     };
+    // 只数节：书名也是图上的一个标题节点、也拥有标签，可它不是书里的一节，网页上没有落点（nodeIndex 里它不是 section）。
+    const sections = new Map(projection.nodeIndex.entries()
+        .filter((entry) => entry.kind === "section")
+        .map((entry) => [entry.iri.value, entry]));
+    const located = (iris) => [...iris].flatMap((iri) => {
+        const entry = sections.get(iri);
+        const id = entry?.node.ids?.[0];
+        if (entry === undefined || id === undefined)
+            return [];
+        return [{ id, title: entry.node.title ?? id }];
+    });
+    // 别的书指过来的引用在这本书的 label space 里找：图上四个标签谓词的值，按整串相等找拥有者。
+    const ownersByLabel = new Map();
+    for (const name of LABEL_PREDICATES) {
+        for (const triple of graph.match({ predicate: { termType: "iri", value: `${AAT_NAMESPACE}${name}` } })) {
+            if (triple.object.termType !== "literal")
+                continue;
+            const iris = ownersByLabel.get(triple.object.value) ?? new Set();
+            iris.add(triple.subject.value);
+            ownersByLabel.set(triple.object.value, iris);
+        }
+    }
+    const owners = (selector) => located(ownersByLabel.get(selector) ?? []);
+    const headingsByFragment = new Map();
+    const crossBook = [];
+    // 指向整本书的 xref（没有片段）没有 targetSelector：没有可改写的片段。
+    for (const triple of graph.match({ predicate: { termType: "iri", value: `${AAT_NAMESPACE}targetSelector` } })) {
+        const edge = triple.subject;
+        const fragment = triple.object.termType === "triple" ? "" : triple.object.value;
+        const document = values(edge, "targetDocument")[0];
+        if (document !== undefined) {
+            crossBook.push({ document, fragment });
+            continue;
+        }
+        const found = located(values(edge, "targetHeading"));
+        if (found.length !== 1)
+            continue;
+        headingsByFragment.set(fragment, found[0]);
+        headingsByFragment.set(escapeHtmlAttribute(fragment), found[0]);
+    }
+    return { headingsByFragment, crossBook, owners };
+}
+// 跨书 xref 同样跟着投影走，只是 label space 在目标书里（DESIGN.adoc 的 Reference Binding）。aat 不打开别的文档，
+// 工作区解析了每一本书，所以在这里找。路径按书目录解析：Asciidoctor 把它照写进 HTML，而 HTML 的输出目录与 books/ 下的
+// 书目录一一对应。指向的不是工作区里的书、只指向整本书（没有片段）、或在目标书里对上零节或几节的，保持原样。
+async function bindCrossBookReferences(book, references, bindingsByInput, anchorCache) {
+    const linksByHref = new Map();
+    for (const xref of references.crossBook) {
+        const { fragment } = xref;
+        // Asciidoctor 把 xref:other#x[] 与 xref:other.adoc#x[] 都读成文档 other：去掉 .adoc、没有扩展名的照写，
+        // 再加 .html 写进 href。书的入口按 .adoc 登记，链接按 .html 改写，两边都从这个文档名出发。
+        const documentName = path.extname(xref.document) === ".adoc" ? xref.document.slice(0, -".adoc".length) : xref.document;
+        const target = bindingsByInput.get(path.resolve(book.bookDir, `${documentName}.adoc`));
+        if (fragment === "" || target === undefined)
+            continue;
+        const found = target.references.owners(fragment);
+        if (found.length !== 1)
+            continue;
+        const heading = found[0];
+        // 指向本书自己的 book.adoc：Asciidoctor 把它当书内引用，写成 #片段。
+        if (target.book.bookId === book.bookId) {
+            references.headingsByFragment.set(fragment, heading);
+            references.headingsByFragment.set(escapeHtmlAttribute(fragment), heading);
+            continue;
+        }
+        const anchors = await anchorsForHtmlFile(path.join(target.book.htmlOutputDir, "book.html"), anchorCache);
+        if (anchors.has(fragment))
+            continue;
+        const htmlPath = `${documentName}.html`;
+        const link = { href: `${htmlPath}#${heading.id}`, title: heading.title };
+        linksByHref.set(`${htmlPath}#${fragment}`, link);
+        linksByHref.set(escapeHtmlAttribute(`${htmlPath}#${fragment}`), link);
+    }
+    return linksByHref;
+}
+// 在目标书里恰好对上一节、而目标书的 HTML 里没有这个片段的跨书链接，改成指向那一节的标题。Asciidoctor 对没写显示文字的跨书 xref
+// 显示文档路径；改写时换成标题。
+function rewriteCrossBookXrefs(html, linksByHref) {
+    if (linksByHref.size === 0)
+        return html;
+    return html.replace(HTML_DOCUMENT_LINK_PATTERN, (whole, htmlPath, fragment, rest, text) => {
+        const link = linksByHref.get(`${htmlPath}#${fragment}`) ?? linksByHref.get(`${htmlPath}#${decodeUrlFragment(fragment)}`);
+        if (link === undefined)
+            return whole;
+        const shown = text === htmlPath ? escapeHtmlAttribute(link.title) : text;
+        return `<a href="${escapeHtmlAttribute(link.href)}"${rest}>${shown}</a>`;
+    });
+}
+// Asciidoctor 把它解析不了的书内 xref 写成 <a href="#选择器">[选择器]</a>；aat 的投影里恰好对上一节的，改成指向那一节的标题，
+// 显示标题。片段已经是 HTML 里某个元素的 id 时，保持 Asciidoctor 写下的样子。
+function rewriteBoundXrefs(html, headingsByFragment) {
+    if (headingsByFragment.size === 0)
+        return html;
+    const anchors = htmlAnchors(html);
+    return html.replace(HTML_FRAGMENT_LINK_PATTERN, (whole, fragment, rest, text) => {
+        const decoded = decodeUrlFragment(fragment);
+        if (anchors.has(fragment) || anchors.has(decoded))
+            return whole;
+        const heading = headingsByFragment.get(fragment) ?? headingsByFragment.get(decoded);
+        if (heading === undefined)
+            return whole;
+        const shown = text === `[${fragment}]` ? escapeHtmlAttribute(heading.title) : text;
+        return `<a href="#${escapeHtmlAttribute(heading.id)}"${rest}>${shown}</a>`;
+    });
 }
 function readerStyles() {
     return `
@@ -1061,12 +1186,20 @@ ${readerStyles()}
 }
 async function addHomeLinks(rootDir, books, config) {
     const catalog = path.join(rootDir, "build", "html", "catalog.html");
+    // 跨书 xref 在目标书的 label space 里找，所以先把每一本书都解析完。
+    const readerData = new Map();
+    for (const book of books) {
+        readerData.set(book.bookId, await buildReaderBookData(config, book));
+    }
+    const bindingsByInput = new Map(books.map((book) => [book.input, { book, references: readerData.get(book.bookId).references }]));
+    const anchorCache = new Map();
     for (const book of books) {
         const htmlFile = path.join(book.htmlOutputDir, "book.html");
-        const html = await readFile(htmlFile, "utf8");
         const href = path.relative(path.dirname(htmlFile), catalog);
-        const readerData = await buildReaderBookData(config, book);
-        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, config.homeLink, readerData.sourceBundle, readerData.pageMap, book.bookId), "utf8");
+        const data = readerData.get(book.bookId);
+        const crossBookLinks = await bindCrossBookReferences(book, data.references, bindingsByInput, anchorCache);
+        const html = rewriteCrossBookXrefs(rewriteBoundXrefs(await readFile(htmlFile, "utf8"), data.references.headingsByFragment), crossBookLinks);
+        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, config.homeLink, data.sourceBundle, data.pageMap, book.bookId), "utf8");
     }
 }
 async function writeRootIndex(rootDir, rootIndex) {
@@ -1086,56 +1219,6 @@ async function writeRootIndex(rootDir, rootIndex) {
 </html>
 `, "utf8");
 }
-function extractCatalogBookIds(catalogSource) {
-    const ids = new Set();
-    for (const match of catalogSource.matchAll(CATALOG_BOOK_XREF_PATTERN))
-        ids.add(match[1]);
-    return [...ids].sort((a, b) => a.localeCompare(b));
-}
-function issue(code, detail) {
-    return { code, detail };
-}
-// xref 的目标与锚点不在这里查：Asciidoctor 把它们写成 HTML 里的链接与 ID，missingLocalResources 在生成的 HTML 上
-// 核对（DESIGN.adoc 的 Workspace Contract Checks）。ID 有 [#id]、[.role#id]、[[id]]、[id=id] 与标题生成等写法，
-// 只有 Asciidoctor 认得全。
-async function workspaceContractIssues(rootDir, books) {
-    const issues = [];
-    const catalogSource = await readIfExists(path.join(rootDir, "catalog.adoc"));
-    const catalogBookIds = extractCatalogBookIds(catalogSource);
-    const bookSet = new Set(books.map((book) => book.bookId));
-    const catalogBookSet = new Set(catalogBookIds);
-    for (const bookId of catalogBookIds) {
-        if (!bookSet.has(bookId))
-            issues.push(issue("CATALOG_TARGET_MISSING", bookId));
-    }
-    for (const book of books) {
-        if (!catalogBookSet.has(book.bookId))
-            issues.push(issue("BOOK_MISSING_FROM_CATALOG", book.bookId));
-    }
-    for (const book of books) {
-        const bookSource = await readFile(book.input, "utf8");
-        if (!/^:doctype:\s+book$/m.test(bookSource))
-            issues.push(issue("MISSING_DOCTYPE", book.bookId));
-    }
-    return issues;
-}
-async function collectHtmlFiles(dir) {
-    return collectFiles(dir, (filePath) => filePath.endsWith(".html"));
-}
-function extractLocalTargets(html) {
-    const targets = [];
-    for (const match of html.matchAll(LOCAL_TARGET_PATTERN)) {
-        const [, attribute, rawTarget] = match;
-        if (rawTarget === "" || rawTarget === "#" || rawTarget.startsWith("//") || SCHEME_PATTERN.test(rawTarget)) {
-            continue;
-        }
-        const targetWithoutFragment = rawTarget.split("#", 1)[0].split("?", 1)[0];
-        const fragment = rawTarget.includes("#") ? rawTarget.split("#", 2)[1].split("?", 1)[0] : "";
-        if (targetWithoutFragment !== "" || fragment !== "")
-            targets.push({ attribute, rawTarget });
-    }
-    return targets;
-}
 function decodeUrlFragment(fragment) {
     try {
         return decodeURIComponent(fragment);
@@ -1158,39 +1241,6 @@ async function anchorsForHtmlFile(filePath, cache) {
     cache.set(filePath, anchors);
     return anchors;
 }
-async function missingLocalResources(rootDir) {
-    const htmlDir = path.join(rootDir, "build", "html");
-    const htmlFiles = await collectHtmlFiles(htmlDir);
-    const issues = [];
-    const anchorCache = new Map();
-    for (const htmlFile of htmlFiles) {
-        const html = await readFile(htmlFile, "utf8");
-        for (const target of extractLocalTargets(html)) {
-            const targetPath = target.rawTarget.split("#", 1)[0].split("?", 1)[0];
-            const fragment = target.rawTarget.includes("#") ? target.rawTarget.split("#", 2)[1].split("?", 1)[0] : "";
-            const resolved = targetPath === "" ? htmlFile : path.resolve(path.dirname(htmlFile), targetPath);
-            if (targetPath !== "" && !await existsFile(resolved)) {
-                issues.push(issue("HTML_RESOURCE_MISSING", `${path.relative(htmlDir, htmlFile)} -> ${target.rawTarget}`));
-                continue;
-            }
-            if (target.attribute === "href" && fragment !== "" && (targetPath === "" || resolved.endsWith(".html"))) {
-                const anchors = await anchorsForHtmlFile(resolved, anchorCache);
-                const decodedFragment = decodeUrlFragment(fragment);
-                if (!anchors.has(fragment) && !anchors.has(decodedFragment)) {
-                    issues.push(issue("HTML_ANCHOR_MISSING", `${path.relative(htmlDir, htmlFile)} -> ${target.rawTarget}`));
-                }
-            }
-        }
-    }
-    return issues;
-}
-async function assertNoIssues(label, issues) {
-    if (issues.length === 0)
-        return;
-    for (const entry of issues)
-        console.error(`${entry.code}: ${entry.detail}`);
-    throw new Error(`${label} failed with ${issues.length} issue(s)`);
-}
 export async function buildWorkspace(rootDir = process.cwd()) {
     const catalog = path.join(rootDir, "catalog.adoc");
     if (!await existsFile(catalog))
@@ -1206,11 +1256,6 @@ export async function buildWorkspace(rootDir = process.cwd()) {
     await copyAssets(rootDir, books);
     await addHomeLinks(rootDir, books, config);
     await writeRootIndex(rootDir, config.rootIndex);
-    await assertNoIssues("HTML local resource check", await missingLocalResources(rootDir));
-    await assertNoIssues("workspace contract check", await workspaceContractIssues(rootDir, books));
-}
-export async function checkWorkspace(rootDir = process.cwd()) {
-    await buildWorkspace(rootDir);
 }
 export async function cleanWorkspace(rootDir = process.cwd()) {
     await rm(path.join(rootDir, "build"), { force: true, recursive: true });
@@ -1221,15 +1266,11 @@ async function main() {
         await buildWorkspace();
         return;
     }
-    if (command === "check") {
-        await checkWorkspace();
-        return;
-    }
     if (command === "clean") {
         await cleanWorkspace();
         return;
     }
-    console.error("Usage: node tools/adoc-books.mjs <build|check|clean>");
+    console.error("Usage: node tools/adoc-books.mjs <build|clean>");
     process.exitCode = 1;
 }
 const executedPath = process.argv[1] ? path.resolve(process.argv[1]) : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Create a complete AsciiDoc multi-book workspace.",
   "license": "Apache-2.0",
   "author": {
@@ -54,7 +54,7 @@
   "devDependencies": {
     "@asciidoctor/core": "^3.0.4",
     "@types/node": "^24.10.1",
-    "asciidoc-abundant-tree": "^0.2.6",
+    "asciidoc-abundant-tree": "link:../asciidoc-abundant-tree",
     "asciidoctor-kroki": "^0.18.1",
     "playwright": "^1.59.1",
     "typescript": "^5.9.3"

package/templates/default-workspace/README.md

@@ -29,13 +29,11 @@ To fetch diagram images into the local HTML output, run:
 ADOC_BOOKS_FETCH_DIAGRAMS=1 pnpm run build
 ```
 
-## Check
+## When The Build Fails
 
-```bash
-pnpm run check
-```
+The build fails only when it cannot produce the pages: Asciidoctor reports a message while rendering, a book's includes leave `documentRoot` (see Configure), or an include resolver returns something the build cannot use.
 
-This checks the current catalog, existing books, book doctypes, cross-book xrefs, anchors, and local HTML resources, and that every book's includes stay within `documentRoot` (see Configure).
+It does not judge your books. Whether an xref reaches the heading you meant, whether a local link resolves, and whether `catalog.adoc` lists every book are left to tools that read the RDF projection `asciidoc-abundant-tree` makes of each book. An xref whose address one heading owns links to that heading; one that no heading owns, or several do, keeps the link Asciidoctor wrote, and the build still succeeds.
 
 ## Configure
 
@@ -52,7 +50,7 @@ export default {
 };
 ```
 
-`documentRoot` matters when this workspace lives inside a project repository. Set it to the project root (`".."` when the workspace is a direct subdirectory) and books can include the project's own code instead of a copy of it. Source paths in the reader and the `// file:` markers of copied source then start at that root. It must contain this workspace. An include that leaves `documentRoot` fails `pnpm run check` and names the book.
+`documentRoot` matters when this workspace lives inside a project repository. Set it to the project root (`".."` when the workspace is a direct subdirectory) and books can include the project's own code instead of a copy of it. Source paths in the reader and the `// file:` markers of copied source then start at that root. It must contain this workspace. An include that leaves `documentRoot` fails the build and names the book.
 
 `includeResolvers` lets books include lines chosen by your own code, for example one function out of a source file:
 
@@ -95,7 +93,7 @@ Delete `books/<book-id>/`, then remove the matching `xref:books/<book-id>/book.a
 Run:
 
 ```bash
-pnpm run check
+pnpm run build
 ```
 
 ## Add A Book

package/templates/default-workspace/books/00-book-anatomy/backmatter/{appendix-a.adoc → appendix-structure-reference.adoc}

@@ -1,4 +1,4 @@
-= 附录 A：结构速查
+= 结构速查
 
 [cols="1,2", options="header"]
 |===

package/templates/default-workspace/books/00-book-anatomy/book.adoc

@@ -5,16 +5,16 @@ v0.1, 2026-05
 :toc: left
 :toclevels: 3
 :sectnums:
+:partnums:
+:part-signifier: Part
 :icons: font
 :experimental:
+:appendix-caption: 附录
 :idprefix:
 :idseparator: -
 
 include::../../shared/attributes.adoc[]
 
-[abstract]
-include::frontmatter/abstract.adoc[]
-
 [colophon]
 include::frontmatter/colophon.adoc[]
 
@@ -27,24 +27,24 @@ include::frontmatter/preface.adoc[]
 [acknowledgments]
 include::frontmatter/acknowledgments.adoc[]
 
-= 第一部：前置结构
+= 前置结构
 
 [partintro]
-include::parts/01-front-structure/_partintro.adoc[]
+include::parts/010-front-structure/_partintro.adoc[]
 
-include::parts/01-front-structure/01-frontmatter-map.adoc[]
+include::parts/010-front-structure/010-frontmatter-map.adoc[]
 
-= 第二部：正文结构
+= 正文结构
 
 [partintro]
-include::parts/02-body-structure/_partintro.adoc[]
+include::parts/020-body-structure/_partintro.adoc[]
 
-include::parts/02-body-structure/01-body-map.adoc[]
+include::parts/020-body-structure/010-body-map.adoc[]
 
-include::parts/02-body-structure/02-inline-structure.adoc[]
+include::parts/020-body-structure/020-inline-structure.adoc[]
 
 [appendix]
-include::backmatter/appendix-a.adoc[]
+include::backmatter/appendix-structure-reference.adoc[]
 
 [glossary]
 include::backmatter/glossary.adoc[]

package/templates/default-workspace/books/00-book-anatomy/parts/{01-front-structure/01-frontmatter-map.adoc → 010-front-structure/010-frontmatter-map.adoc}

@@ -1,4 +1,3 @@
-[#frontmatter-map]
 == 前置内容地图
 
 前置内容用于建立读者进入正文之前需要知道的说明、来源和阅读位置。
@@ -9,9 +8,6 @@
 |===
 |结构 |职责
 
-|`[abstract]`
-|说明整本书覆盖什么。
-
 |`[colophon]`
 |记录版本、出版或来源信息。
 
@@ -24,3 +20,5 @@
 |`[acknowledgments]`
 |放置致谢。
 |===
+
+书没有摘要。`[abstract]` 是 article 的 section style：摘要概述一篇文章，书的前置内容里没有这一项。在 book 里写 `[abstract]`，Asciidoctor 会把那一节当作普通的一章编号，它后面每一章的编号都跟着多一。一本书覆盖什么、怎样读，写在前言里。

package/templates/default-workspace/books/00-book-anatomy/parts/010-front-structure/_partintro.adoc

@@ -0,0 +1 @@
+本部展示一本书进入正文之前的结构位置。版本说明、献辞、前言和致谢都属于书籍前置内容。

package/templates/default-workspace/books/00-book-anatomy/parts/{02-body-structure/01-body-map.adoc → 020-body-structure/010-body-map.adoc}

@@ -1,4 +1,3 @@
-[#body-map]
 == 正文结构地图
 
 part 是 book doctype 中 document title 之后的 level 0 section。level 1 section 通常形成 chapter；multipart book 中 chapter 位于 part 下，普通 book 中 chapter 可以直接位于 book 下。

package/templates/default-workspace/books/00-book-anatomy/parts/020-body-structure/020-inline-structure.adoc

@@ -0,0 +1,31 @@
+== 内联结构标记
+
+内联结构标记给正文中的术语、路径和索引入口标出它们的身份，并写出正文对别的章节的引用。它不改变 book 的章节层级，但会提高正文片段的可维护性和可检索性。
+
+[cols="1,2", options="header"]
+|===
+|写法 |结构作用
+
+|`xref:正文结构地图[]`
+|按标题引用同一本书里的一节：标题就是这一节的地址。
+
+|`[#id]`
+|custom ID：给标题再加一个地址。同名的标题先写上级标题、以 `::` 隔开来引用（`pass:[xref:上级标题::本节标题[]]`）；同一个上级下也同名，或标题里有 `#`、`::` 时才写。
+
+|`indexterm2:[term]`
+|把正文中已经出现的词作为可见索引词。
+
+|`indexterm:[term, detail]`
+|正文没有出现该词时，补充隐藏索引入口。
+
+|`[.term]#inline role#`
+|给术语片段提供语义身份。
+
+|`[.path]` + monospace path
+|给路径文本提供语义身份。
+
+|`{series-name}`
+|引用共享属性，减少多处重复文本。
+|===
+
+语义 inline role 提供结构身份；具体视觉效果取决于输出样式。本书使用 [.term]#inline role# 标记术语片段，使用 [.path]`parts/020-body-structure/` 标记路径片段。

package/templates/default-workspace/books/01-starter-book/backmatter/{appendix-a.adoc → appendix-minimal-files.adoc}

@@ -1,4 +1,4 @@
-== 附录 A：最小文件清单
+== 最小文件清单
 
 普通新书通常需要：
 

package/templates/default-workspace/books/01-starter-book/book.adoc

@@ -7,6 +7,7 @@ v0.1, 2026-05
 :sectnums:
 :icons: font
 :experimental:
+:appendix-caption: 附录
 :idprefix:
 :idseparator: -
 
@@ -15,12 +16,12 @@ include::../../shared/attributes.adoc[]
 [preface]
 include::frontmatter/preface.adoc[]
 
-include::chapters/01-opening.adoc[]
+include::chapters/010-opening.adoc[]
 
-include::chapters/02-main-flow.adoc[]
+include::chapters/020-main-flow.adoc[]
 
 [appendix]
-include::backmatter/appendix-a.adoc[]
+include::backmatter/appendix-minimal-files.adoc[]
 
 [bibliography]
 include::backmatter/bibliography.adoc[]

package/templates/default-workspace/books/01-starter-book/chapters/{01-opening.adoc → 010-opening.adoc}

@@ -1,4 +1,3 @@
-[#starter-book-boundary]
 == 单书边界
 
 一本普通书由自己的 `book.adoc` 定义边界。入口文件负责书名、属性、章节顺序、前置内容和后置内容。

package/templates/default-workspace/books/02-multipart-monograph/backmatter/appendix-part-reference.adoc

@@ -0,0 +1,5 @@
+= part 速查
+
+* `= 问题世界`：同一本 book 内部的 part。标题只写语义名；`Part I`、`Part II` 这样的序号由书头的 `:partnums:` 生成，不写进标题。
+* `[partintro]`：part 开头的说明块。
+* `== 章标题`：part 下的 chapter。