create-asciidoc-multi-book-workspace 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.9 - 2026-06-17
+
+### Added
+
+- Add design notes for the `0X0` source-order numbering scheme used by structured writing sample books.
+- Add a reference note on book structure, front matter, body matter, and back matter for authors modeling AsciiDoc books.
+- Expand the structured writing conventions sample with heading containment, generated projection IRI, stable address label, and xref edge examples.
+
+### Changed
+
+- Use the same three-digit `0X0` numbering format for structured writing sample Part directories and Chapter files.
+- Clarify when authors should declare stable IDs versus relying on globally unique, stable title text as the xref target.
+- Tighten the sample guidance for role vocabularies, rel predicates, heading level continuity, pass macros, callouts, and large-scope xrefs.
+
 ## 0.1.8 - 2026-06-14
 
 ### Fixed

package/package.json

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

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

@@ -5,37 +5,41 @@
 |写法 |含义
 
 |`= 书名`
-|Document title（文档标题）。在 book 文档类型中作为整本书标题。
+|文档大标题（Document Title）。作为整本书的根节点，只能位于文档首行。
 
-|`= 部标题`
-|Document title 之后的 Level 0 Section。在 book 文档类型中可作为 Part（部）。
+|`= 卷/部`
+|0级章节（Level 0）。位于大标题之后的正文中，代表书籍的“卷/部”（Part）。
 
-|`== 章 / 标题`
-|Level 1 Section（一级章节）。创建书稿阅读结构，在 book 文档类型中通常作为 Chapter（章）。
+|`== 章`
+|1级章节（Level 1）。代表书籍的“章”（Chapter）。
 
 |`=== 节`
-|Level 2 Section（二级章节 / 节）。
+|2级章节（Level 2）。代表章内部的“节”（Section）。
 
 |`==== 小节`
-|Level 3 Section（三级章节 / 小节）。
+|3级章节（Level 3）。代表“小节”（Subsection）。
 
 |`===== 次小节`
-|Level 4 Section（四级章节）。
+|4级章节（Level 4）。代表“次小节”。
 
-|`====== 最底层级`
-|Level 5 Section（五级章节）。AsciiDoc 支持的最深层级。
+|`====== 最底层标题`
+|5级章节（Level 5）。AsciiDoc 引擎支持的最深物理层级。
 
-|`parts/100-topic/`
-|part 目录的源文件编排号。
+|`parts/010-topic/`
+|Part 目录的源文件编排号。使用统一的三位数 `0X0` 格式。`X` 为顺序号，首个 `0` 为前导零，末尾 `0` 为插入预留。
 
 |`010-opening.adoc`
-|chapter 文件的源文件编排号。
+|Chapter 文件的源文件编排号。规则与 Part 目录编排号一致。
 
 |`[#stable-id]`
-|为重要标题声明稳定 ID。
+|为标题声明一个稳定的引用地址。稳定 ID 仅当以下两个条件同时满足时才需显式声明：
+(1) 该标题被至少一个 `xref` 交叉引用；
+(2) 标题文本本身可能变更或在全书范围内可能重复。
+若标题本身已是领域内唯一且稳定的标识符（如专有名词、唯一实体名、标准化编号），即使被交叉引用，也无需额外声明稳定 ID——标题文本即地址。
 
 |`[#stable-id.concept]`
 |声明稳定 ID，并用 role 标明标题身份。
+需要能够回答： “这个标题在整本书的知识体系中扮演什么认知功能”
 
 |`[#example.example, owner=writing-team]`
 |role 声明标题身份；named attributes 保留附加字段。
@@ -53,6 +57,8 @@
 |正文隐藏索引词。
 |===
 
+全书标题需要保持 `标题层级连续`。
+
 role 描述标题身份。rel 描述 xref 边上的关系谓词。named attributes 是附加字段。
 
 `[appendix]`、`[glossary]`、`[bibliography]` 和 `[index]` 是 section style。它们改变紧随其后 section 的语义；标题层级仍由 `=` 数量决定。
@@ -61,4 +67,10 @@ role 描述标题身份。rel 描述 xref 边上的关系谓词。named attribut
 
 你可以在主文档的开头定义一个变量（比如 `:book-b-dir:`），后续引用时通过 `{book-b-dir}` 来调用它。
 
-如果你的建模中存在需要对一段区域精准指向、提及的情况，优先考虑使用 **更小一级/更小一节** 的标题把这段区域划分出来，之后就可以继续使用 `xref` 进行交叉引用。
+如果你的建模中存在需要对一段区域精准指向、提及的情况，可以考虑使用 **更小一级/更小一节** 的标题把这段区域划分出来，之后就可以继续使用 `xref` 进行交叉引用。
+
+在 Asciidoc 中使用 pass:[] 宏可以表达透传，不会被解析，使用反引号包裹可以获得字体样式。
+
+如果遇到“代码/日志”与其“文字解释”需要分离的场景，可以考虑使用 Asciidoc 的 Callouts。
+
+TIP: 在你写作的过程中，你可以思考有哪些 Asciidoc 语法/表达 适合你当前的所撰写的对象，然后选择合适的并应用。

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

@@ -2,8 +2,12 @@
 
 本术语表记录结构化书写约定中的核心术语。
 
+[glossary]
 heading:: 使用等号标题创建的书稿结构单位。
-stable ID:: 作者声明的稳定引用地址，例如 `#stable-heading`。
+stable ID:: 作者为标题显式声明的稳定引用地址，语法为 `[#id]`。
+仅当标题被交叉引用、且标题文本自身不能保证全局唯一和不变时才需使用。
+若标题文本已是领域内唯一的稳定标识符（如实体名称、标准化编号），
+标题文本本身即承担 stable ID 的寻址功能，无需额外声明。
 source-order notation:: 写在源文件路径表面的排序符号。
 role:: 标题身份标记，例如 `.concept` 或 `.rule`。
 ordinary reference:: 普通 xref。投影时使用默认谓词 `aat:references`。

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

@@ -34,4 +34,5 @@ Asciidoctor 的内置 HTML5 转换器不会自动生成索引目录。`[index]`
 indexterm2:[role]
 indexterm:[relation predicate]
 indexterm:[源文件编排号]
+indexterm:[中间值插入]
 ----

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

@@ -32,31 +32,31 @@ include::frontmatter/acknowledgments.adoc[]
 = 从源文档看结构
 
 [partintro]
-include::parts/100-source-surface/_partintro.adoc[]
+include::parts/010-source-surface/_partintro.adoc[]
 
-include::parts/100-source-surface/010-source-and-projection.adoc[]
+include::parts/010-source-surface/010-source-and-projection.adoc[]
 
-include::parts/100-source-surface/020-default-semantics.adoc[]
+include::parts/010-source-surface/020-default-semantics.adoc[]
 
-include::parts/100-source-surface/030-source-order-notation.adoc[]
+include::parts/010-source-surface/030-source-order-notation.adoc[]
 
 = 给标题和引用加意图
 
 [partintro]
-include::parts/200-identity-and-relation/_partintro.adoc[]
+include::parts/020-identity-and-relation/_partintro.adoc[]
 
-include::parts/200-identity-and-relation/010-role-identity.adoc[]
+include::parts/020-identity-and-relation/010-role-identity.adoc[]
 
-include::parts/200-identity-and-relation/020-relation-predicate.adoc[]
+include::parts/020-identity-and-relation/020-relation-predicate.adoc[]
 
 = 字段、索引与术语
 
 [partintro]
-include::parts/300-fields-and-lookup/_partintro.adoc[]
+include::parts/030-fields-and-lookup/_partintro.adoc[]
 
-include::parts/300-fields-and-lookup/010-surface-fields.adoc[]
+include::parts/030-fields-and-lookup/010-surface-fields.adoc[]
 
-include::parts/300-fields-and-lookup/020-index-and-glossary.adoc[]
+include::parts/030-fields-and-lookup/020-index-and-glossary.adoc[]
 
 [appendix]
 include::backmatter/appendix-a.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 和 named attributes 形成可读、可维护、可投影的源文档的方式。作者可按写作目的选择其中写法。

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

@@ -1,7 +1,14 @@
 == 前言
 
-这本标本书按源文档写法组织。阅读时先看源文档片段和投影片段，再对照后续章节理解每个标记承担的职责。
+这本书按源文档写法组织。阅读时先看源文档片段和投影片段，再对照后续章节理解每个标记承担的职责。
 
-实际书稿按写作目的选择这些写法。长期引用的标题使用稳定 ID；带有明确身份的标题使用 role；表达关系的引用使用 rel；随源稿保留的字段使用 named attributes。
+实际书稿按写作目的选择这些写法。
+长期引用且标题文本可能变更的标题使用稳定 ID；
+若标题本身已是唯一且稳定的实体名称，标题文本直接作为引用地址。
+带有明确身份的标题使用 role；表达关系的引用使用 rel；
+随源稿保留的字段使用 named attributes。
 
 业务含义由书稿自己的约定承载。本书展示同一份 AsciiDoc 源文本如何同时服务阅读、维护和工具链投影。
+
+通过展示标题、稳定 ID、role、xref、rel 和 named attributes 如何形成可读、可维护、可投影的源文档，让你能够理解，你可以拥有一种这样的表达方式，可以按照某种约定，就能够提升你书籍的质量，能够让下游的工具链继续消费你的书。 你可以参考本书里你所需要的结构。
+合适的结构能够提升书籍的可阅读、可维护性。你可以按写作目的选择其中写法。

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

@@ -0,0 +1,83 @@
+[#source-and-projection]
+== 源文本与投影
+
+本章用一段示例展示结构化书写约定。Turtle 片段列出关键投影事实；完整投影还会保留 raw、路径、行号和边证据。
+希望你能通过本章节的演示来理解你写下的文字能够给未来的你提供稳定的查询与导航结构。
+
+[source,asciidoc]
+----
+= 结构化写作样例
+
+[#regular-heading.concept]
+== 常规标题
+
+常规标题提供可引用的阅读单位。
+
+[#basic-syntax.example]
+=== 基本语法
+
+基本语法是常规标题下的直接子标题。
+
+[#xref-rule.rule]
+== 引用规则
+
+引用规则参见 xref:regular-heading[常规标题]。
+引用规则依赖 xref:regular-heading[常规标题, rel=depends-on, weight=strong]。
+----
+
+源文档把 `常规标题` 写成可引用的阅读单位，在其下写出 `基本语法` 子标题，把 `引用规则` 写成规则说明，并在正文里写出参见和依赖两种引用。
+
+Turtle 示例中的 `<urn:aat:doc:...#heading-*>` 和 `<urn:aat:doc:...#xref-edge-*>` 表示投影生成的 IRI；`aat:addressLabel` 保留源文档中的寻址 label。
+
+[source,turtle]
+----
+<urn:aat:doc:...#heading-l3-o0> a aat:Heading ;
+  aat:headline "常规标题" ;
+  aat:addressLabel "regular-heading" ;
+  aat:role "concept" ;
+  aat:containsDirectly <urn:aat:doc:...#heading-l8-o0> .
+
+<urn:aat:doc:...#heading-l8-o0> a aat:Heading ;
+  aat:headline "基本语法" ;
+  aat:addressLabel "basic-syntax" ;
+  aat:role "example" .
+
+<urn:aat:doc:...#heading-l13-o0> a aat:Heading ;
+  aat:headline "引用规则" ;
+  aat:addressLabel "xref-rule" ;
+  aat:role "rule" ;
+  aat:references <urn:aat:doc:...#heading-l3-o0> ;
+  rel:depends-on <urn:aat:doc:...#heading-l3-o0> .
+
+<urn:aat:doc:...#xref-edge-l17-c8-o0> a aat:XrefEdge ;
+  aat:rel "depends-on" ;
+  aat:weight "strong" .
+----
+
+读者看源文档，能直接看到 [.concept]#常规标题# 是被引用的阅读单位，`基本语法` 是它的下级标题， [.rule]#引用规则# 说明引用写法。投影读取同一份源文档，为标题生成 IRI，并在标题节点上保留 `aat:headline`、`aat:addressLabel` 和 `aat:role`；标题层级投影为 `aat:containsDirectly`，xref 投影为 `aat:references` 和 `rel:depends-on`。
+
+[source,asciidoc]
+----
+[.concept]
+== 林黛玉
+
+林黛玉是……她与 xref:贾宝玉[rel=love] 有木石前盟。
+----
+
+此处的 `pass:[xref:贾宝玉]` 直接使用标题文本作为寻址地址，
+因为“贾宝玉”在本书范围内唯一且不会变更为其他名称。
+交叉引用宏语法是 `pass:[xref:target-id[optional-display-text]]` ，所以这里省略了别名，渲染引擎默认会展示标题文字。
+
+'''
+
+再来看看这样的场景： 标题是编号型标识符，且被交叉引用
+
+例如： `REQ-2024-0088`、`TC-AUTH-032`、`ADR-2024-015`，他们的标题本身就是编号，是人为设计的全局唯一标识符， 需要尊重他的原来的结构与语义。
+
+[source,asciidoc]
+----
+[.requirement, category=性能]
+== REQ-2024-0088
+----
+
+引用时可以这样： `pass:[xref:REQ-2024-0088[REQ-2024-0088, rel=constrains]]`

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

@@ -0,0 +1,48 @@
+[#heading-and-xref]
+== 标题与引用
+
+等号行声明标题和层级。标题前的 attrlist 承载地址、role 和字段。
+
+[source,asciidoc]
+----
+[#regular-heading.concept]
+== 常规标题
+----
+
+`[#regular-heading]` 声明一个稳定地址。 `.concept` 标明标题身份。 `常规标题` 是标题文本。
+
+[source,asciidoc]
+----
+引用规则参见 xref:regular-heading[常规标题]。
+----
+
+该 xref 投影为 `aat:references`，即默认引用谓词。
+
+[source,asciidoc]
+----
+引用规则依赖 xref:regular-heading[常规标题, rel=depends-on]。
+----
+
+`rel=depends-on` 声明从当前标题到目标标题的依赖关系，投影为 `rel:depends-on`。
+
+[TIP]
+====
+1. 需要保证全书里所有出现的稳定地址都最少有1个 `xref` 消费，也就是说可以在需要进行交叉引用时，判断引用目标当前在全书中是否已经有稳定的标识，再确认是否需要手动添加上稳定地址。详细判断规则见 xref:附录 A：结构化写法速查[]。
+2. 按照书籍结构，跨越 `= 书名`、`= 卷/部`、`== 章` 这些大跨度的指代均需要使用 `xref` 手动标注，平衡隐式上下文的阅读压力。
+====
+
+标题声明角色后，其下级标题默认属于同一角色范围。下级标题可声明不同角色以切换语境。
+
+例如:
+
+[source,asciidoc]
+----
+[.rule]
+== 引用规则
+
+=== 基本语法
+
+[.example]
+=== 一个完整示例
+----
+

package/templates/default-workspace/books/07-structured-writing-conventions/parts/010-source-surface/030-source-order-notation.adoc

@@ -0,0 +1,36 @@
+[#source-order-notation]
+== 源文件编排号
+
+源文件编排号写在 part 目录名和 chapter 文件名前部。indexterm:[源文件编排号]
+
+Part 目录和 Chapter 文件统一使用三位数 `0X0` 格式进行编排。
+
+* 初始序列以 `10` 为步长：`010`、`020`、`030`……
+* 十位数字（`X`）用于线性递增，以追加新内容。
+* 个位数字（`0`）预留空间用于中间插入。
+
+[source,text]
+----
+parts/010-source-surface/
+parts/015-new-topic/       <1>
+parts/020-identity-and-relation/
+
+010-opening.adoc
+015-new-context.adoc       <2>
+020-main-flow.adoc
+----
+<1> 使用 `015` 在 `010` 和 `020` 两个 Part 之间插入。
+<2> 使用 `015` 在 `010` 和 `020` 两个 Chapter 之间插入。
+
+**操作规则：**
+
+作者需要两个原子操作：
+
+. **末尾追加**：取当前最大编号，将其十位数字加 `1`，个位保持 `0`。例如，`090` 之后是 `100`。
+. **中间插入**：在 A 与 B 之间插入时，新编号取 A 和 B 的**算术中间值**。例如，在 `010` 与 `020` 之间插入，使用 `015`。此策略可确保插入后仍为后续插入保留最大空间。
+
+使用三位数 `0X0` 格式，能够解决书籍动态维护过程中编号格式的稳定。
+
+标题文本保留语义名称。长期引用的标题使用显式 ID。
+
+编排号帮助维护者观察源文件顺序；显式 ID 帮助读者和工具链稳定引用标题。

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

@@ -0,0 +1,35 @@
+[#role-identity]
+== role 身份
+
+role 写在标题 attrlist 的点号 token 位置。
+
+[source,asciidoc]
+----
+[#regular-heading.concept]
+== 常规标题
+
+[#xref-rule.rule]
+== 引用规则
+----
+
+`#regular-heading` 和 `#xref-rule` 是稳定 ID， `.concept` 和 `.rule` 是 indexterm2:[role]， 标明标题身份。
+
+[cols="1,2", options="header"]
+|===
+|写法 |读者看到的身份
+
+|`[.concept]`
+|标记概念说明。
+
+|`[.rule]`
+|标记规则说明。
+
+|`[.example]`
+|标记示例。
+|===
+
+role 的职责，是在全书范围内保持身份含义的稳定。
+
+一本书使用的 role 种类和数量，取决于该领域的概念结构。每种 role 的语义在全书中保持唯一。
+
+读者和工具链可以依据 role 进行导航文本和提取结构。

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

@@ -0,0 +1,24 @@
+[#relation-predicate]
+== rel 关系谓词
+
+indexterm:[relation predicate] `rel` 是 xref 边上的关系谓词。包含 xref 的标题是关系起点，xref 指向的标题是关系终点。本书把这两个位置称为 source heading 和 target heading。
+
+[source,asciidoc]
+----
+引用规则参见 xref:regular-heading[常规标题]。
+引用规则依赖 xref:regular-heading[常规标题, rel=depends-on]。
+----
+
+第一行投影为 `aat:references`，即默认引用谓词。第二行声明 `rel=depends-on`，投影为 `rel:depends-on`。
+
+`rel` 可以被读者和工具当作关系谓词，所以在全书范围内，每种 `rel` 谓词的语义需要保持唯一且不变。
+
+[horizontal]
+depends-on:: 当前标题的判断、规则或操作以目标标题为依据。阅读顺序和先读建议使用普通 xref 表达。
+illustrates:: 当前标题提供目标标题的示例。
+defines:: 当前标题给出目标标题所代表对象的定义。
+constrains:: 当前标题对目标标题的合法写法或范围施加约束。
+
+关系谓词描述标题之间的边。标题自身的身份使用 role 表达。
+
+标题之间的阅读顺序和先读建议，使用普通 xref（默认 `aat:references`）表达。

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

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

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

@@ -8,7 +8,7 @@ named attributes 是写在源文档表面的字段。
 [#example.example, owner=writing-team]
 == 示例
 
-示例说明 xref:stable-heading[稳定标题, rel=illustrates, weight=strong]。
+示例说明 xref:regular-heading[常规标题, rel=illustrates, weight=strong]。
 ----
 
 `.example` 是 role。`owner=writing-team` 是标题附加字段。`weight=strong` 是 xref 边证据上的附加字段。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/100-source-surface/010-source-and-projection.adoc

@@ -1,44 +0,0 @@
-[#source-and-projection]
-== 源文本与投影
-
-本章用一段示例展示结构化书写约定。Turtle 片段列出关键投影事实；完整投影还会保留 raw、路径、行号和边证据。
-希望你能通过本章节的演示来理解你写下的文字能够给未来的你提供稳定的查询与导航结构。
-
-[source,asciidoc]
-----
-= 结构化写作样例
-
-[#stable-heading.concept]
-== 稳定标题
-
-稳定标题提供可引用的阅读单位。
-
-[#xref-rule.rule]
-== 引用规则
-
-引用规则参见 xref:stable-heading[稳定标题]。
-引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on, weight=strong]。
-----
-
-源文档把 `稳定标题` 写成可引用的阅读单位，把 `引用规则` 写成规则说明，并在正文里写出参见和依赖两种引用。
-
-[source,turtle]
-----
-:stable-heading a aat:Heading ;
-  aat:headline "稳定标题" ;
-  aat:addressLabel "stable-heading" ;
-  aat:role "concept" .
-
-:xref-rule a aat:Heading ;
-  aat:headline "引用规则" ;
-  aat:addressLabel "xref-rule" ;
-  aat:role "rule" ;
-  aat:references :stable-heading ;
-  rel:depends-on :stable-heading .
-
-:xref-edge-depends-on a aat:XrefEdge ;
-  aat:rel "depends-on" ;
-  aat:weight "strong" .
-----
-
-读者看源文档，能直接看到 [.concept]#稳定标题# 是被引用的阅读单位， [.rule]#引用规则# 说明引用写法。下游投影工具链读取同一份源文档，得到 `aat:Heading`、`aat:addressLabel`、`aat:role`、`aat:references` 和 `rel:depends-on`。

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

@@ -1,26 +0,0 @@
-[#heading-and-xref]
-== 标题与引用
-
-等号行是标题。标题前一行的 attrlist 承载地址和 role。
-
-[source,asciidoc]
-----
-[#stable-heading.concept]
-== 稳定标题
-----
-
-`#stable-heading` 给标题一个稳定地址；`.concept` 标明标题身份；`稳定标题` 是读者看到的标题文本。
-
-[source,asciidoc]
-----
-引用规则参见 xref:stable-heading[稳定标题]。
-----
-
-这条 xref 表示参见目标标题。投影时，这条引用使用默认谓词 `aat:references`。
-
-[source,asciidoc]
-----
-引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on]。
-----
-
-写入 `rel=depends-on` 时，作者声明当前标题到目标标题的依赖关系。投影时，这条关系使用 `rel:depends-on`。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/100-source-surface/030-source-order-notation.adoc

@@ -1,23 +0,0 @@
-[#source-order-notation]
-== 源文件编排号
-
-源文件编排号写在 part 目录名和 chapter 文件名前部。indexterm:[源文件编排号]
-
-part 目录使用 `100-`、`200-`、`300-`。chapter 文件在所属 part 内使用 `010-`、`020-`、`030-`。
-
-中间插入新文件时，使用相邻编号之间的空位。
-
-[source,text]
-----
-parts/100-source-surface/
-parts/150-new-topic/
-parts/200-identity-and-relation/
-
-010-opening.adoc
-015-new-context.adoc
-020-main-flow.adoc
-----
-
-标题文本保留语义名称。长期引用的标题使用显式 ID。
-
-编排号帮助维护者观察源文件顺序；显式 ID 帮助读者和工具链稳定引用标题。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/200-identity-and-relation/010-role-identity.adoc

@@ -1,37 +0,0 @@
-[#role-identity]
-== role 身份
-
-`[#xref-rule.rule]` 里的 `.rule` 是 indexterm2:[role]。它把这个标题标成规则说明。
-
-role 写在标题 attrlist 的点号 token 位置。
-
-[source,asciidoc]
-----
-[#stable-heading.concept]
-== 稳定标题
-
-[#xref-rule.rule]
-== 引用规则
-----
-
-`#stable-heading` 和 `#xref-rule` 是稳定 ID。`.concept` 和 `.rule` 标明标题身份。
-
-[cols="1,2", options="header"]
-|===
-|写法 |读者看到的身份
-
-|`[.concept]`
-|标记概念说明。
-
-|`[.rule]`
-|标记规则说明。
-
-|`[.example]`
-|标记示例。
-|===
-
-role 的职责，是在全书范围内保持身份含义的稳定。
-
-一旦一个 role 被定义——例如 `.rule` 代表规则说明——它在全书任何地方都只能代表这个身份，不能产生歧义。一本书需要多少种 role，取决于它所要描述的领域固有的本质复杂度。无论三种还是十种，每一种都必须是确定的。
-
-读者和工具链依赖这种稳定理解来导航文本和提取结构。

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

@@ -1,22 +0,0 @@
-[#relation-predicate]
-== rel 关系谓词
-
-indexterm:[relation predicate] `rel` 是 xref 边上的关系谓词。xref 写在哪个标题下面，哪个标题就是关系起点；xref 指向哪个标题，哪个标题就是关系终点。本书把这两个位置称为 source heading 和 target heading。
-
-[source,asciidoc]
-----
-引用规则参见 xref:stable-heading[稳定标题]。
-引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on]。
-----
-
-第一行表示参见 `稳定标题`，投影为 `aat:references`。第二行写入 `rel=depends-on`，声明 `引用规则` 到 `稳定标题` 的依赖关系，投影为 `rel:depends-on`。
-
-`rel` 会被读者和工具当作关系谓词。同一本书使用 rel 时，应保持谓词含义稳定。
-
-[horizontal]
-depends-on:: 当前标题的判断、规则或操作以目标标题为依据。阅读顺序和先读建议使用普通 xref 表达。
-illustrates:: 当前标题提供目标标题的示例。
-defines:: 当前标题给出目标标题所代表对象的定义。
-constrains:: 当前标题对目标标题的合法写法或范围施加约束。
-
-关系谓词描述标题之间的边。标题自身的身份使用 role 表达。

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

@@ -1 +0,0 @@
-本部展示标题身份和引用关系。role 标明标题身份；rel 标明引用关系。 你应该在自己书籍里增加各类词表约定的章节。