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

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.8.0 - 2026-10-31
+
+### Changed
+
+- A link with no link text shows the name of its address. When the xref's address is the heading's title or one of its qualified addresses, the link shows it as written, its titles joined with an interpunct: `xref:红烧肉::火候[]` shows 红烧肉·火候 and `xref:家常菜::红烧肉::火候[]` shows all three titles, inside a book and across books. It used to show the last title alone (火候), so a book that referred to one of several 火候 wrote its address twice, once as the target and once as link text. An xref whose address is an ID still shows the heading's title, as Asciidoctor does for a section it resolves by ID. Link text the author writes is shown as written.
+- The structured writing conventions sample writes a qualified address once (《xref:红烧肉::火候[]》) and writes link text only where it says something other than the address's name. Its addressing chapter, print conventions, decision trees, and quick reference say so.
+
+### Upgrading an existing workspace
+
+Create a temporary workspace with `pnpm create asciidoc-multi-book-workspace@0.8.0 tmp-books` and copy its `tools/adoc-books.mjs` over yours. The `asciidoc-abundant-tree` range stays `^0.6.0`. Books need no change: link text written as the address's name, such as `xref:红烧肉::火候[红烧肉·火候]`, still shows the same, and can be removed.
+
 ## 0.7.0 - 2026-10-31
 
 ### Removed

package/dist/runtime/adoc-books.mjs

@@ -570,12 +570,16 @@ function bindReferences(config, document) {
     const sections = new Map(projection.nodeIndex.entries()
         .filter((entry) => entry.kind === "section")
         .map((entry) => [entry.iri.value, entry]));
-    const located = (iris) => [...iris].flatMap((iri) => {
+    // 地址的名字：选择器是这一节的标题或某个限定地址时，照写下的样子显示，各级标题之间用间隔号；是 ID（作者声明的或生成的）
+    // 时显示标题——ID 是给引用用的第二个地址，不是给读者看的名字。按图上是哪个标签判，不按字符串里有没有 :: 猜。
+    const located = (iris, selector) => [...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 }];
+        const node = { termType: "iri", value: iri };
+        const named = values(node, "headline").includes(selector) || values(node, "addressPath").includes(selector);
+        return [{ id, shown: named ? selector.split("::").join("·") : entry.node.title ?? id }];
     });
     // 别的书指过来的引用在这本书的 label space 里找：图上四个标签谓词的值，按整串相等找拥有者。
     const ownersByLabel = new Map();
@@ -588,7 +592,7 @@ function bindReferences(config, document) {
             ownersByLabel.set(triple.object.value, iris);
         }
     }
-    const owners = (selector) => located(ownersByLabel.get(selector) ?? []);
+    const owners = (selector) => located(ownersByLabel.get(selector) ?? [], selector);
     const headingsByFragment = new Map();
     const crossBook = [];
     // 指向整本书的 xref（没有片段）没有 targetSelector：没有可改写的片段。
@@ -600,7 +604,7 @@ function bindReferences(config, document) {
             crossBook.push({ document, fragment });
             continue;
         }
-        const found = located(values(edge, "targetHeading"));
+        const found = located(values(edge, "targetHeading"), fragment);
         if (found.length !== 1)
             continue;
         headingsByFragment.set(fragment, found[0]);
@@ -635,14 +639,14 @@ async function bindCrossBookReferences(book, references, bindingsByInput, anchor
         if (anchors.has(fragment))
             continue;
         const htmlPath = `${documentName}.html`;
-        const link = { href: `${htmlPath}#${heading.id}`, title: heading.title };
+        const link = { href: `${htmlPath}#${heading.id}`, shown: heading.shown };
         linksByHref.set(`${htmlPath}#${fragment}`, link);
         linksByHref.set(escapeHtmlAttribute(`${htmlPath}#${fragment}`), link);
     }
     return linksByHref;
 }
-// 在目标书里恰好对上一节、而目标书的 HTML 里没有这个片段的跨书链接，改成指向那一节的标题。Asciidoctor 对没写显示文字的跨书 xref
-// 显示文档路径；改写时换成标题。
+// 在目标书里恰好对上一节、而目标书的 HTML 里没有这个片段的跨书链接，改成指向那一节的标题。Asciidoctor 对没有显示文字的跨书 xref
+// 显示文档路径；改写时换成地址的名字。
 function rewriteCrossBookXrefs(html, linksByHref) {
     if (linksByHref.size === 0)
         return html;
@@ -650,12 +654,12 @@ function rewriteCrossBookXrefs(html, linksByHref) {
         const link = linksByHref.get(`${htmlPath}#${fragment}`) ?? linksByHref.get(`${htmlPath}#${decodeUrlFragment(fragment)}`);
         if (link === undefined)
             return whole;
-        const shown = text === htmlPath ? escapeHtmlAttribute(link.title) : text;
+        const shown = text === htmlPath ? escapeHtmlAttribute(link.shown) : text;
         return `<a href="${escapeHtmlAttribute(link.href)}"${rest}>${shown}</a>`;
     });
 }
 // Asciidoctor 把它解析不了的书内 xref 写成 <a href="#选择器">[选择器]</a>；aat 的投影里恰好对上一节的，改成指向那一节的标题，
-// 显示标题。片段已经是 HTML 里某个元素的 id 时，保持 Asciidoctor 写下的样子。
+// 显示地址的名字。片段已经是 HTML 里某个元素的 id 时，保持 Asciidoctor 写下的样子。
 function rewriteBoundXrefs(html, headingsByFragment) {
     if (headingsByFragment.size === 0)
         return html;
@@ -667,7 +671,7 @@ function rewriteBoundXrefs(html, headingsByFragment) {
         const heading = headingsByFragment.get(fragment) ?? headingsByFragment.get(decoded);
         if (heading === undefined)
             return whole;
-        const shown = text === `[${fragment}]` ? escapeHtmlAttribute(heading.title) : text;
+        const shown = text === `[${fragment}]` ? escapeHtmlAttribute(heading.shown) : text;
         return `<a href="#${escapeHtmlAttribute(heading.id)}"${rest}>${shown}</a>`;
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Create a complete AsciiDoc multi-book workspace.",
   "license": "Apache-2.0",
   "author": {

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/appendix-decision-trees.adoc

@@ -91,8 +91,8 @@
    └─ 否：同一本书里经 include 拼起来的各个文件之间，xref 直接写标题。看第 2 步。
 
 2. 目标标题在它所在的书里与别的标题同名吗？
-   ├─ 是：把上级标题由近及远用 `::` 接在前面，补到候选只剩一个，如 `红烧肉::火候`，
-   │      并写上显示文本，各级之间用间隔号，如 `[红烧肉·火候]`。
+   ├─ 是：把上级标题由近及远用 `::` 接在前面，补到候选只剩一个，如 `红烧肉::火候`。
+   │      不必写显示文本：网页显示地址的名字，各级之间用间隔号，如《红烧肉·火候》。
    │      补到书名之下最高的一级仍分不开（同一个上级下同名）时，先把标题改得说得清这一节讲什么；
    │      改不了时，在那一节标题上方加 custom ID，xref 写这个 ID，
    │      并写上能分清是哪一节的显示文本。看第 3 步。

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/appendix-quick-reference.adoc

@@ -34,8 +34,8 @@
 |`[.dish]`
 |role：这一节在书里是什么。
 
-|`pass:[xref:红烧肉::火候[红烧肉·火候]]`
-|限定地址：几个标题同名时，把上级标题用 `::` 接在前面，指明其中一个；显示文本用间隔号。
+|`pass:[xref:红烧肉::火候[]]`
+|限定地址：几个标题同名时，把上级标题用 `::` 接在前面，指明其中一个；网页显示《红烧肉·火候》，各级之间用间隔号。
 
 |`[#…]`
 |custom ID：标题当不了地址时（同一个上级下同名，或标题里有 `#`、`::`）给它的第二个地址。
@@ -74,7 +74,7 @@
 写引用时，应符合下列规定：
 
 * 同一本书里经 include 拼起来的各个文件之间，引用直接写标题；
-* 几个标题同名时，引用写限定地址，例如 `pass:[xref:红烧肉::火候[红烧肉·火候]]`；
+* 几个标题同名时，引用写限定地址，例如 `pass:[xref:红烧肉::火候[]]`，不必再写显示文本；
 * 引用另一本书时，在书头定义一个文档属性，存那本书的入口路径（如 `:snack-book: ../02-home-snacks/book.adoc`），引用写成 `pass:[xref:{snack-book}#糖油饼[]]`，`#` 后面写那本书里的标题。
 
 反引号只改字体，反引号里的行内宏（如 xref）和属性引用照样会被替换。要原样展示它们，应把它们包在 `pass:[pass:[…]]` 里，外面再加反引号得到等宽字体。`= 书名`、`[.dish]` 这类块写法出现在行内时不会被当作结构，用反引号即可。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/010-source-surface/020-heading-address-and-xref.adoc

@@ -55,17 +55,14 @@ Asciidoctor 还会从标题生成一个 ID，生成时去掉标点，同名的
 
 [source,asciidoc]
 ----
-糖色下锅以后怎样转火，见《xref:红烧肉::火候[红烧肉·火候]》。
+糖色下锅以后怎样转火，见《xref:红烧肉::火候[]》。
 ----
 
-`红烧肉::火候` 是这一节的限定地址。写限定地址时，应符合下列规定：
+`红烧肉::火候` 是这一节的限定地址。上级标题由近及远逐级补上，补到候选只剩一个为止。
 
-* 上级标题由近及远逐级补上，补到候选只剩一个为止；
-* 写上显示文本，各级标题之间用间隔号，例如 `红烧肉·火候`（见《xref:篇名用书名号[]》）。
+限定地址只写一遍，不必再写显示文本。链接没有显示文本时，网页上显示地址的名字，各级标题之间用间隔号（见《xref:篇名用书名号[]》），上面这句读者看到的是“见《红烧肉·火候》”。作者补上的上级标题，读者也要靠它分清是哪道菜的火候，所以显示时一级不少。想在链接上说别的话时，才写显示文本，例如 `pass:[xref:红烧肉::火候[那一锅的火候]]`，网页显示写下的这句。
 
-不写显示文本时，链接上只显示最后一级标题“火候”，读者看不出是哪道菜的。
-
-补一级不够时，再往上补一级。例如菜谱分了《家常菜》《宴客菜》两部，两部里都有《红烧肉》，引用家常菜里那一道的火候时，写 `pass:[xref:家常菜::红烧肉::火候[家常菜·红烧肉·火候]]`。补到书名之下最高的一级（分部的书是部，不分部的书是章），就是这一节完整的路径；书名全书只有一个，不必写。
+补一级不够时，再往上补一级。例如菜谱分了《家常菜》《宴客菜》两部，两部里都有《红烧肉》，引用家常菜里那一道的火候时，写 `pass:[xref:家常菜::红烧肉::火候[]]`，网页显示《家常菜·红烧肉·火候》。补到书名之下最高的一级（分部的书是部，不分部的书是章），就是这一节完整的路径；书名全书只有一个，不必写。
 
 同一个上级下有两个同名的标题时，完整的路径也分不开它们，例如糖醋排骨要炸两遍，《糖醋排骨》下写了两节《炸》。两节同名，多半是标题没有说清这一节讲什么。这时宜先改标题，例如改成《初炸》与《复炸》，改好以后，两节的标题各是各的地址。
 
@@ -74,7 +71,7 @@ Asciidoctor 还会从标题生成一个 ID，生成时去掉标点，同名的
 * 名字说清这一节讲什么，不写序号和位置词，例如不写 `炸-2`、`第二个炸`，因为序号和位置会随编排变化；
 * 名字不与书里的任何标题相同。例如给《卤味》下讲糖色的一节加了 `[#炒糖色]`，书里又有一节《炒糖色》，这个地址就对上两节；Asciidoctor 先按 ID 去找，网页上 `pass:[xref:炒糖色[]]` 落到加了 ID 的那一节，原来指《炒糖色》的引用便不声不响地指到了别处；
 * 同一个上级下同名的几节，要引用哪一节，就给哪一节加；只给其中一节加时，另一节的标题和限定地址仍然有两个候选；
-* 引用写上显示文本，写出能让读者分清是哪一节的说法。
+* 引用写上显示文本，写出能让读者分清是哪一节的说法：引用 custom ID 的链接显示的是标题，同名的几节显示得一样。
 
 custom ID 是同一个标题的第二个地址，不替代标题。作者是在要引用某一节时才发现标题当不了地址的，custom ID 也宜在那时再加，不必预先写下。
 

package/templates/default-workspace/books/07-structured-writing-conventions/parts/040-book-prose/040-print-conventions.adoc

@@ -18,7 +18,7 @@ ____
 做法见《红烧肉》。
 ____
 
-书名号标书名、卷名和篇名（4.15.3.1）；题目是一部特定的作品时用书名号，只是谈论的话题时才用引号（B.1.8）。书里的一节是这本书里的一篇，提到它时应加书名号。几篇并列时，书名号应紧挨着写，中间不加顿号（A.13）。提到的一节带链接时，xref 应写在书名号里面，例如 `《pass:[xref:红烧肉[]]》`，读者看到的是《红烧肉》，链接落在书名号里的标题上。书名和其中的篇名连着写时，中间用间隔号，例如《随园食单·须知单》；限定地址的显示文本也这样写，例如《红烧肉·火候》。
+书名号标书名、卷名和篇名（4.15.3.1）；题目是一部特定的作品时用书名号，只是谈论的话题时才用引号（B.1.8）。书里的一节是这本书里的一篇，提到它时应加书名号。几篇并列时，书名号应紧挨着写，中间不加顿号（A.13）。提到的一节带链接时，xref 应写在书名号里面，例如 `《pass:[xref:红烧肉[]]》`，读者看到的是《红烧肉》，链接落在书名号里的标题上。书名和其中的篇名连着写时，中间用间隔号，例如《随园食单·须知单》；链接没有显示文本时，网页把限定地址也这样显示，`《pass:[xref:红烧肉::火候[]]》` 读者看到的是《红烧肉·火候》。
 
 [.touchstone]
 === 中西文混排照规范