1. 摘要
本书会通过展示标题、稳定 ID、role、xref、rel 和 named attributes 如何形成可读、可维护、可投影的源文档，让你能够理解，你可以有这样一种表达方式，按照某种约定，能够提升你书籍的质量，能够让下游的工具链继续消费你的书。 你可以参考你当前写书所需要的结构，合适的结构能够提升书籍的可阅读，可维护性。你可以按写作目的选择其中写法。
版本说明
本文档属于 实时全模态视频通话体验规约书架。colophon 位于书籍前置区域，记录本样本书的版本、来源或出版信息。
示例版本：v0.1。
献辞
献给每一位愿意为自己写下的标题、引用和标记负责的作者。
前言
这本标本书按源文档写法组织。阅读时先看源文档片段和投影片段，再对照后续章节理解每个标记承担的职责。
实际书稿按写作目的选择这些写法。长期引用的标题使用稳定 ID；带有明确身份的标题使用 role；表达关系的引用使用 rel；随源稿保留的字段使用 named attributes。
业务含义由书稿自己的约定承载。本书展示同一份 AsciiDoc 源文本如何同时服务阅读、维护和工具链投影。
致谢
感谢 Asciidoctor 和 RDF 投影相关文档提供稳定术语和结构坐标。
Part I: 从源文档看结构
本部从一段源文档出发，展示读者看到的写作意图和投影得到的结构事实。
2. 源文本与投影
本章用一段示例展示结构化书写约定。Turtle 片段列出关键投影事实；完整投影还会保留 raw、路径、行号和边证据。 希望你能通过本章节的演示来理解你写下的文字能够给未来的你提供稳定的查询与导航结构。
= 结构化写作样例
[#stable-heading.concept]
== 稳定标题
稳定标题提供可引用的阅读单位。
[#xref-rule.rule]
== 引用规则
引用规则参见 xref:stable-heading[稳定标题]。
引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on, weight=strong]。源文档把 稳定标题 写成可引用的阅读单位，把 引用规则 写成规则说明，并在正文里写出参见和依赖两种引用。
: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" .读者看源文档，能直接看到 稳定标题 是被引用的阅读单位， 引用规则 说明引用写法。下游投影工具链读取同一份源文档，得到 aat:Heading、aat:addressLabel、aat:role、aat:references 和 rel:depends-on。
3. 标题与引用
等号行是标题。标题前一行的 attrlist 承载地址和 role。
[#stable-heading.concept]
== 稳定标题#stable-heading 给标题一个稳定地址；.concept 标明标题身份；稳定标题 是读者看到的标题文本。
引用规则参见 xref:stable-heading[稳定标题]。这条 xref 表示参见目标标题。投影时，这条引用使用默认谓词 aat:references。
引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on]。写入 rel=depends-on 时，作者声明当前标题到目标标题的依赖关系。投影时，这条关系使用 rel:depends-on。
4. 源文件编排号
源文件编排号写在 part 目录名和 chapter 文件名前部。
part 目录使用 100-、200-、300-。chapter 文件在所属 part 内使用 010-、020-、030-。
中间插入新文件时，使用相邻编号之间的空位。
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 帮助读者和工具链稳定引用标题。
Part II: 给标题和引用加意图
本部展示标题身份和引用关系。role 标明标题身份；rel 标明引用关系。 你应该在自己书籍里增加各类词表约定的章节。
5. role 身份
[#xref-rule.rule] 里的 .rule 是 role。它把这个标题标成规则说明。
role 写在标题 attrlist 的点号 token 位置。
[#stable-heading.concept]
== 稳定标题
[#xref-rule.rule]
== 引用规则#stable-heading 和 #xref-rule 是稳定 ID。.concept 和 .rule 标明标题身份。
| 写法 | 读者看到的身份 |
|---|---|
|
标记概念说明。 |
|
标记规则说明。 |
|
标记示例。 |
role 的职责，是在全书范围内保持身份含义的稳定。
一旦一个 role 被定义——例如 .rule 代表规则说明——它在全书任何地方都只能代表这个身份，不能产生歧义。一本书需要多少种 role，取决于它所要描述的领域固有的本质复杂度。无论三种还是十种，每一种都必须是确定的。
读者和工具链依赖这种稳定理解来导航文本和提取结构。
6. rel 关系谓词
rel 是 xref 边上的关系谓词。xref 写在哪个标题下面，哪个标题就是关系起点；xref 指向哪个标题，哪个标题就是关系终点。本书把这两个位置称为 source heading 和 target heading。
引用规则参见 xref:stable-heading[稳定标题]。
引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on]。第一行表示参见 稳定标题，投影为 aat:references。第二行写入 rel=depends-on，声明 引用规则 到 稳定标题 的依赖关系，投影为 rel:depends-on。
rel 会被读者和工具当作关系谓词。同一本书使用 rel 时，应保持谓词含义稳定。
| depends-on |
当前标题的判断、规则或操作以目标标题为依据。阅读顺序和先读建议使用普通 xref 表达。 |
| illustrates |
当前标题提供目标标题的示例。 |
| defines |
当前标题给出目标标题所代表对象的定义。 |
| constrains |
当前标题对目标标题的合法写法或范围施加约束。 |
关系谓词描述标题之间的边。标题自身的身份使用 role 表达。
Part III: 字段、索引与术语
本部展示字段、索引词和术语表。字段随源文档保留；索引词和术语表帮助读者找词、解词。
7. 附加字段
named attributes 是写在源文档表面的字段。
[#example.example, owner=writing-team]
== 示例
示例说明 xref:stable-heading[稳定标题, rel=illustrates, weight=strong]。.example 是 role。owner=writing-team 是标题附加字段。weight=strong 是 xref 边证据上的附加字段。
owner=writing-team 写在标题 attrlist 中，投影时成为标题字段。weight=strong 写在 xref 中，投影时成为边证据字段。
字段名和字段值来自本书自己的约定。同一本书使用附加字段时，应保持字段写法和字段含义稳定。
8. 索引词与术语表
索引词帮助读者在书后找到词。术语表解释本书采用的词。role 标明标题身份，rel 标明引用关系。
正文里已经自然出现该词时，使用可见索引词标记。需要补充未出现在正文里的索引入口时，使用隐藏索引词。
indexterm2:[role]
indexterm:[relation predicate]稳定术语帮助作者、读者和维护者使用同一组词理解源文档。
Appendix A: 附录 A：结构化写法速查
| 写法 | 含义 |
|---|---|
|
Document title（文档标题）。在 book 文档类型中作为整本书标题。 |
|
Document title 之后的 Level 0 Section。在 book 文档类型中可作为 Part（部）。 |
|
Level 1 Section（一级章节）。创建书稿阅读结构，在 book 文档类型中通常作为 Chapter（章）。 |
|
Level 2 Section（二级章节 / 节）。 |
|
Level 3 Section（三级章节 / 小节）。 |
|
Level 4 Section（四级章节）。 |
|
Level 5 Section（五级章节）。AsciiDoc 支持的最深层级。 |
|
part 目录的源文件编排号。 |
|
chapter 文件的源文件编排号。 |
|
为重要标题声明稳定 ID。 |
|
声明稳定 ID，并用 role 标明标题身份。 |
|
role 声明标题身份；named attributes 保留附加字段。 |
显示为链接，投影为 references。 |
|
显示为链接，同时声明 depends-on 关系。 |
|
|
正文可见索引词。 |
正文隐藏索引词。 |
role 描述标题身份。rel 描述 xref 边上的关系谓词。named attributes 是附加字段。
[appendix]、[glossary]、[bibliography] 和 [index] 是 section style。它们改变紧随其后 section 的语义；标题层级仍由 = 数量决定。
对于跨文件的交叉引用，为了避免重复编写相对路径，你可以在文档的头部（Header）定义一个文档属性（Document Attribute）来存储这个基础路径。
你可以在主文档的开头定义一个变量（比如 :book-b-dir:），后续引用时通过 {book-b-dir} 来调用它。
如果你的建模中存在需要对一段区域精准指向、提及的情况，优先考虑使用 更小一级/更小一节 的标题把这段区域划分出来，之后就可以继续使用 xref 进行交叉引用。
术语表
本术语表记录结构化书写约定中的核心术语。
- heading
-
使用等号标题创建的书稿结构单位。
- stable ID
-
作者声明的稳定引用地址，例如
#stable-heading。 - source-order notation
-
写在源文件路径表面的排序符号。
- role
-
标题身份标记，例如
.concept或.rule。 - ordinary reference
-
普通 xref。投影时使用默认谓词
aat:references。 - relation predicate
-
xref
rel字段选择的边谓词。 - source heading
-
xref 所在的标题。
- target heading
-
xref selector 指向的标题。
- surface field
-
named attributes 携带的源文档表面字段。
- index term
-
服务书后索引和读者检索的索引入口。
参考坐标
以下资料提供 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-sections] Asciidoctor Docs, Sections, https://docs.asciidoctor.org/asciidoc/latest/sections/
索引
索引 section 位于书籍后置区域。正文中的索引词宏是索引词来源。
AsciiDoc 区分正文可见索引词和正文隐藏索引词：
| 写法 | 含义 |
|---|---|
|
正文可见，同时作为一级索引项。 |
正文不可见，作为一级索引项。 |
|
正文不可见，作为二级索引项。 |
|
正文不可见，作为三级索引项。 |
正文中已经出现该词时，优先使用正文可见索引词。需要补充未出现在正文里的索引入口时，使用正文隐藏索引词。
隐藏索引词应贴近它标记的段落内容。本书把隐藏索引词放在相关句子末尾。
Asciidoctor 的内置 HTML5 转换器不会自动生成索引目录。[index] section 是 PDF 和 DocBook 工具链自动填充索引目录的种子位置；在本 HTML 样本中，它展示后置索引章节的位置和索引词写法。
本书正文中的索引词示例：
indexterm2:[role]
indexterm:[relation predicate]
indexterm:[源文件编排号]