create-asciidoc-multi-book-workspace 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.13 - 2026-06-21
+
+### Changed
+
+- Expand the structured writing conventions sample with a decision-tree appendix for heading topology, stable IDs, roles, xrefs, surface fields, source numbering, index terms, and syntax pass-through choices.
+- Update the structured writing quick reference and default semantics guidance to point authors toward the new decision-tree workflow.
+
+## 0.1.12 - 2026-06-19
+
+### Changed
+
+- Expand the structured writing conventions sample to document title fields written as description lists, including multi-line field values.
+- Update the maintainer and generated workspace `asciidoc-abundant-tree` dependency range to `^0.1.18` so new workspaces use the matching projection toolchain.
+
 ## 0.1.11 - 2026-06-17
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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.1.16",
+    "asciidoc-abundant-tree": "^0.1.18",
     "asciidoctor-kroki": "^0.18.1",
     "playwright": "^1.59.1",
     "typescript": "^5.9.3"

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

@@ -1,3 +1,4 @@
+[#structured-writing-quick-reference]
 = 附录 A：结构化写法速查
 
 [cols="1,2", options="header"]
@@ -44,6 +45,9 @@
 |`[#example.example, owner=writing-team]`
 |role 声明标题身份；named attributes 保留附加字段。
 
+|`summary::` + 下一行说明文本
+|标题下描述列表字段。用于较多字段或多行字段值。
+
 |`xref:stable-id[显示文本]`
 |显示为链接，投影为 references。
 
@@ -59,7 +63,7 @@
 
 全书标题需要保持 `标题层级连续`。
 
-role 描述标题身份。rel 描述 xref 边上的关系谓词。named attributes 是附加字段。
+role 描述标题身份。rel 描述 xref 边上的关系谓词。附加字段可以写在标题 attrlist、标题下描述列表或 xref named attributes 中。
 
 `[appendix]`、`[glossary]`、`[bibliography]` 和 `[index]` 是 section style。它们改变紧随其后 section 的语义；标题层级仍由 `=` 数量决定。
 
@@ -69,8 +73,8 @@ role 描述标题身份。rel 描述 xref 边上的关系谓词。named attribut
 
 如果你的建模中存在需要对一段区域精准指向、提及的情况，可以考虑使用 **更小一级/更小一节** 的标题把这段区域划分出来，之后就可以继续使用 `xref` 进行交叉引用。
 
-在 Asciidoc 中使用 pass:[] 宏可以表达透传，不会被解析，使用反引号包裹可以获得字体样式。
+如果文章中出现 Asciidoc 自己的语法，通过反引号包裹依然会被解析，必须使用 pass:[] 宏才可以表达透传，不会被解析，使用反引号包裹可以获得字体样式。
 
 如果遇到“代码/日志”与其“文字解释”需要分离的场景，可以考虑使用 Asciidoc 的 Callouts。
 
-TIP: 在你写作的过程中，你可以思考有哪些 Asciidoc 语法/表达 适合你当前的所撰写的对象，然后选择合适的并应用。
+结构化写法的选择由当前对象、引用需求、投影需求和维护成本共同决定。具体判定流程见 xref:structured-writing-decision-trees[附录 B：结构化写法决策树]。

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

@@ -0,0 +1,166 @@
+[#structured-writing-decision-trees]
+= 附录 B：结构化写法决策树
+
+== 标题生成与层级拓扑控制
+
+触发场景:: 作者准备在源文档中创建新的标题节点。
+
+[source,text]
+----
+1. 当前标题是否为文档大标题？
+   ├─ 是：使用 `= 书名`，并放置于文档首行。流程结束。
+   └─ 否：评估逻辑层级。
+
+2. 当前标题与紧邻上级标题的层级关系是否连续？
+   ├─ 否：补充中间层级标题，保持标题层级连续；回到节点 2 重新评估。
+   └─ 是：评估区域划分。
+
+3. 当前标题下的文本区域后续是否需要被精准指向或提及？
+   ├─ 是：使用更小一级标题将该区域独立划分，后续用 xref 指向该标题。流程结束。
+   └─ 否：评估 section style。
+
+4. 当前标题是否承载附录、术语表、参考文献或索引等后置结构？
+   ├─ 是：在等号标题上方声明对应 section style：
+   │      `[appendix]`、`[glossary]`、`[bibliography]` 或 `[index]`。
+   │      section style 改变紧随其后 section 的语义；标题层级仍由 `=` 数量决定。
+   │      流程结束。
+   └─ 否：写入标准等号标题。流程结束。
+----
+
+== stable ID 的生命周期与寻址机制
+
+触发场景:: 作者评估是否需要为当前标题显式声明寻址 ID。
+
+[source,text]
+----
+1. 当前标题文本是否已是领域内唯一且稳定的标识符？
+   ├─ 是：不声明 `[#stable-id]`；直接使用标题文本作为引用地址。流程结束。
+   └─ 否：评估交叉引用状态。
+
+2. 该标题在全书范围内是否被至少一个 `xref` 交叉引用？
+   ├─ 否：不声明 `[#stable-id]`。流程结束。
+   └─ 是：在等号标题上方的 attrlist 中显式声明 `[#stable-id]`。流程结束。
+----
+
+触发场景:: 项目全局构建或审查阶段检查 stable ID 消费状态。
+
+[source,text]
+----
+1. 扫描源文件中所有手工显式声明的 `[#stable-id]`。
+   ├─ 每个 ID 对应的 xref 引用次数 >= 1：保留声明，审查通过。
+   └─ 某个 ID 对应的 xref 引用次数 == 0：移除该 `[#stable-id]` 声明。
+----
+
+== role 的作用域与语境管理
+
+触发场景:: 作者为标题标记认知功能与身份语义。
+前提:: 当前书稿已经约定 role 受控词表，例如 `.concept`、`.rule`、`.example`。
+
+[source,text]
+----
+1. 当前标题是否为其父标题的下级标题？
+   ├─ 否：从受控词表中选取匹配当前语境的 role，写入标题 attrlist。流程结束。
+   └─ 是：评估语境连续性。
+
+2. 当前子标题承载的认知角色是否与父标题声明的 role 相同？
+   ├─ 是：不重复声明 role；下级标题默认属于同一角色范围。流程结束。
+   └─ 否：从受控词表中选取匹配新语境的 role，显式写入当前标题 attrlist。
+          该声明完成语境切换。流程结束。
+----
+
+== xref 与 rel 关系谓词建立
+
+触发场景:: 作者在正文中写入指向其他标题节点的交叉引用。
+
+[source,text]
+----
+1. 当前引用是否跨越 `= 书名`、`= 卷/部`、`== 章` 等大跨度指代？
+   ├─ 是：手动写入 `xref`，平衡隐式上下文的阅读压力；进入关系评估。
+   └─ 否：评估文件位置。
+
+2. 目标标题是否位于不同的物理源文件中？
+   ├─ 是：在文档头部定义文档属性存储基础路径；
+   │      后续通过该属性调用基础路径进行跨文件引用；进入关系评估。
+   └─ 否：进入关系评估。
+
+3. 引用目的是什么？
+   ├─ 表达阅读顺序、先读建议或普通参见：
+   │      写入普通 xref，例如 `xref:target-id[显示文本]`。
+   │      投影为默认谓词 `aat:references`。流程结束。
+   └─ 声明明确的逻辑关系边：选取 `rel` 谓词。
+
+4. 根据全书约定的关系谓词选择 `rel`。
+   ├─ 当前标题的判断、规则或操作以目标标题为依据：使用 `rel=depends-on`。
+   ├─ 当前标题提供目标标题的示例：使用 `rel=illustrates`。
+   ├─ 当前标题给出目标标题所代表对象的定义：使用 `rel=defines`。
+   └─ 当前标题对目标标题的合法写法或范围施加约束：使用 `rel=constrains`。
+----
+
+== surface field 落位策略
+
+触发场景:: 作者为 heading 节点或 xref 边挂载键值信息。
+
+[source,text]
+----
+1. 字段描述的主体是什么？
+   ├─ xref 引用边：将字段写入 xref 的 named attributes 中。流程结束。
+   └─ heading 标题节点：评估字段体积。
+
+2. heading 字段数量和长度是否适合写入标题 attrlist？
+   ├─ 字段较少，且字段值较短：写入标题前方 attrlist。
+   │      例如 `[owner=writing-team, status=active]`。流程结束。
+   └─ 字段较多，或包含多行字段值：
+          写入紧随标题下方的第一个连续描述列表。
+          例如 `key:: value`。流程结束。
+----
+
+== 源文件物理编排与编号运算
+
+触发场景:: 作者为 Part 目录或 Chapter 源文件生成文件编排号。
+前提:: Part 目录和 Chapter 文件统一使用三位数 `0X0` 格式；初始序列步长为 10，例如 `010`、`020`、`030`。
+
+[source,text]
+----
+1. 新文件在逻辑序列中的位置是什么？
+   ├─ 位于当前既有序列的最后方：执行末尾追加。
+   └─ 位于当前既有文件 A 与文件 B 之间：执行中间插入。
+
+2. 末尾追加：
+   提取当前同级列表中的最大编号，将其十位数字加 1，个位保持 0。
+   流程结束。
+
+3. 中间插入：
+   提取上文文件 A 和下文文件 B 的编号，计算两者的算术中间值。
+   例如在 `010` 与 `020` 之间插入，使用 `015`。
+   流程结束。
+----
+
+== index term 落位
+
+触发场景:: 作者为读者检索和书后索引添加索引入口。
+
+[source,text]
+----
+1. 索引目标词是否已经自然出现在当前正文句子中？
+   ├─ 是：使用正文可见索引词宏 `indexterm2:[<primary>]` 包裹该词。
+   │      正文保持可见，同时提取为一级索引项。流程结束。
+   └─ 否：使用正文隐藏索引词宏 `indexterm:[<primary>]`。
+          按需使用多级形式，例如 `indexterm:[<primary>, <secondary>]`。
+          隐藏索引词贴近相关段落内容，放在相关句子末尾。流程结束。
+----
+
+== 语法透传与 callouts
+
+触发场景:: 作者书写代码、日志或工具语法文本。
+
+[source,text]
+----
+1. 正文中是否出现 AsciiDoc 原生语法字符，且需要阻止其被解析引擎渲染？
+   ├─ 是：使用 `pass:[]` 宏包裹该内容。
+   │      若需要代码字体样式，在外层叠加反引号包裹。流程结束。
+   └─ 否：评估解释关联。
+
+2. 当前是否为代码或日志结构，且配有单独的文字解释？
+   ├─ 是：使用 AsciiDoc callouts 标注代码或日志与解释之间的关联。流程结束。
+   └─ 否：正常书写。流程结束。
+----

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/bibliography.adoc

@@ -1,7 +1,8 @@
 = 参考坐标
 
-以下资料提供 AsciiDoc 标题、交叉引用和元素属性的参考坐标。
+以下资料提供 AsciiDoc 标题、交叉引用、元素属性和描述列表的参考坐标。
 
 * [[[asciidoctor-xref]]] Asciidoctor Docs, Cross References, https://docs.asciidoctor.org/asciidoc/latest/macros/xref/
 * [[[asciidoctor-attributes]]] Asciidoctor Docs, Element Attributes, https://docs.asciidoctor.org/asciidoc/latest/attributes/element-attributes/
+* [[[asciidoctor-description-lists]]] Asciidoctor Docs, Description Lists, https://docs.asciidoctor.org/asciidoc/latest/lists/description/
 * [[[asciidoctor-sections]]] Asciidoctor Docs, Sections, https://docs.asciidoctor.org/asciidoc/latest/sections/

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/glossary.adoc

@@ -14,5 +14,5 @@ ordinary reference:: 普通 xref。投影时使用默认谓词 `aat:references`
 relation predicate:: xref `rel` 字段选择的边谓词。
 source heading:: xref 所在的标题。
 target heading:: xref selector 指向的标题。
-surface field:: named attributes 携带的源文档表面字段。
+surface field:: 源文档表面的附加字段。标题字段可来自标题 attrlist 或标题下描述列表；xref 边字段来自 xref named attributes。
 index term:: 服务书后索引和读者检索的索引入口。

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/index.adoc

@@ -35,4 +35,5 @@ indexterm2:[role]
 indexterm:[relation predicate]
 indexterm:[源文件编排号]
 indexterm:[中间值插入]
+indexterm:[描述列表]
 ----

package/templates/default-workspace/books/07-structured-writing-conventions/book.adoc

@@ -61,6 +61,9 @@ include::parts/030-fields-and-lookup/020-index-and-glossary.adoc[]
 [appendix]
 include::backmatter/appendix-a.adoc[]
 
+[appendix]
+include::backmatter/appendix-b-decision-trees.adoc[]
+
 [glossary]
 include::backmatter/glossary.adoc[]
 

package/templates/default-workspace/books/07-structured-writing-conventions/frontmatter/abstract.adoc

@@ -1,3 +1,3 @@
 == 摘要
 
-本书展示标题、稳定 ID、role、xref、rel 和 named attributes 形成可读、可维护、可投影的源文档的方式。作者可按写作目的选择其中写法。
+本书展示标题、稳定 ID、role、xref、rel 和附加字段形成可读、可维护、可投影的源文档的方式。作者可按写作目的选择其中写法。

package/templates/default-workspace/books/07-structured-writing-conventions/frontmatter/preface.adoc

@@ -6,9 +6,9 @@
 长期引用且标题文本可能变更的标题使用稳定 ID；
 若标题本身已是唯一且稳定的实体名称，标题文本直接作为引用地址。
 带有明确身份的标题使用 role；表达关系的引用使用 rel；
-随源稿保留的字段使用 named attributes。
+随源稿保留的短字段使用 named attributes；字段较多或需要多行值的标题字段使用标题下描述列表。
 
 业务含义由书稿自己的约定承载。本书展示同一份 AsciiDoc 源文本如何同时服务阅读、维护和工具链投影。
 
-通过展示标题、稳定 ID、role、xref、rel 和 named attributes 如何形成可读、可维护、可投影的源文档，让你能够理解，你可以拥有一种这样的表达方式，可以按照某种约定，就能够提升你书籍的质量，能够让下游的工具链继续消费你的书。 你可以参考本书里你所需要的结构。
+通过展示标题、稳定 ID、role、xref、rel 和附加字段如何形成可读、可维护、可投影的源文档，让你能够理解，你可以拥有一种这样的表达方式，可以按照某种约定，就能够提升你书籍的质量，能够让下游的工具链继续消费你的书。 你可以参考本书里你所需要的结构。
 合适的结构能够提升书籍的可阅读、可维护性。你可以按写作目的选择其中写法。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/010-source-surface/020-default-semantics.adoc

@@ -27,7 +27,7 @@
 
 [TIP]
 ====
-1. 需要保证全书里所有出现的稳定地址都最少有1个 `xref` 消费，也就是说可以在需要进行交叉引用时，判断引用目标当前在全书中是否已经有稳定的标识，再确认是否需要手动添加上稳定地址。详细判断规则见 xref:附录 A：结构化写法速查[]。
+1. 全书中手工声明的稳定地址至少需要一个 `xref` 消费。写法速查见 xref:structured-writing-quick-reference[附录 A：结构化写法速查]；完整判断流程见 xref:structured-writing-decision-trees[附录 B：结构化写法决策树]。
 2. 按照书籍结构，跨越 `= 书名`、`= 卷/部`、`== 章` 这些大跨度的指代均需要使用 `xref` 手动标注，平衡隐式上下文的阅读压力。
 ====
 
@@ -45,4 +45,3 @@
 [.example]
 === 一个完整示例
 ----
-

package/templates/default-workspace/books/07-structured-writing-conventions/parts/020-identity-and-relation/_partintro.adoc

@@ -1 +1 @@
-本部展示标题身份和引用关系。role 标明标题身份；rel 标明引用关系。 在书籍中，你需要主动根据你当前所建模的概念结构对各类词表进行建模与约定，需要专门的词表约定章节清晰的写出你需要使用的受控词表，方便后续的使用。
+本部展示标题身份和引用关系。role 标明标题身份；rel 标明引用关系。 在书籍中，你需要主动根据你当前所建模的概念结构对各类词表（`role`、`rel` 或者其他更多）进行建模与约定，需要专门的词表约定章节清晰的写出你需要使用的受控词表，方便后续的使用。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-lookup/010-surface-fields.adoc

@@ -1,7 +1,7 @@
 [#surface-fields]
 == 附加字段
 
-named attributes 是写在源文档表面的字段。
+附加字段是写在源文档表面的键值信息。标题字段可以写在标题 attrlist 或标题下描述列表中；xref 边证据字段写在 xref named attributes 中。
 
 [source,asciidoc]
 ----
@@ -15,4 +15,21 @@ named attributes 是写在源文档表面的字段。
 
 `owner=writing-team` 写在标题 attrlist 中，投影时成为标题字段。`weight=strong` 写在 xref 中，投影时成为边证据字段。
 
+标题字段较少且值较短时，写在标题 attrlist 中。标题字段较多，或字段值需要换行时，写在标题下的第一个连续描述列表中。indexterm:[描述列表]
+
+[source,asciidoc]
+----
+[#rule.example, status=active]
+== 示例规则
+
+priority:: normal
+summary::
+示例规则说明标题字段的描述列表写法。
+多行说明保留为同一个标题字段。
+
+示例规则正文从这里开始。
+----
+
+`priority:: normal` 和 `summary::` 属于 `示例规则` 标题的附加字段。投影时它们成为标题字段，例如 `aat:priority` 和 `aat:summary`。
+
 字段名和字段值来自本书自己的约定。同一本书使用附加字段时，应保持字段写法和字段含义稳定。

package/templates/default-workspace/package.json.template

@@ -13,7 +13,7 @@
   },
   "devDependencies": {
     "@asciidoctor/core": "^3.0.4",
-    "asciidoc-abundant-tree": "^0.1.16",
+    "asciidoc-abundant-tree": "^0.1.18",
     "asciidoctor-kroki": "^0.18.1"
   }
 }