1. 摘要

本书展示标题、稳定 ID、role、xref、rel 和 named attributes 如何形成可读、可维护、可投影的书稿表面。

本书用于观察结构化写法，不作为每本书的必选清单。

版本说明

本文档属于 AsciiDoc 多本书工作区示例。colophon 位于书籍前置区域，记录本样本书的版本、来源或出版信息。

示例版本：v0.1。

献辞

献给每一位愿意为自己写下的标题、引用和标记负责的作者。

前言

这本标本书按书稿表面组织。阅读时先看第一部的源文档片段和投影片段，再对照后续章节理解每个标记承担的职责。

读者可以按实际书稿需要采用其中的写法。普通书稿可以只使用清晰标题和普通 xref；需要更强结构时，再为重要标题补充稳定 ID、role、rel 或少量附加字段。

本书把业务含义留给书稿自己的约定。它展示同一份 AsciiDoc 源文本如何同时服务阅读、维护和工具链投影。

致谢

感谢 Asciidoctor 和 RDF 投影相关文档提供稳定术语和结构坐标。

第一部：源文本表面

本部展示作者写下的源文本表面，以及工具链可以从同一份文本读出的关键结构事实。

2. 源文本与投影

本章用一段短源文档展示结构化书写约定。示例只展示关键投影事实；完整投影还会保留 raw、路径、行号和边证据。

= 结构化写作样例

[#stable-heading.concept]
== 稳定标题

稳定标题提供可引用的阅读单位。

[#xref-rule.rule]
== 引用规则

引用规则参见 xref:stable-heading[稳定标题]。
引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on, weight=strong]。

这段源文档写下了两个标题、两个稳定 ID、两个 role、一个普通 xref 和一个显式关系 xref。

: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. 标题与引用

标题使用等号声明。重要标题可以添加稳定 ID。需要标明标题身份时，可以在标题 attrlist 中添加 role。

[#stable-heading.concept]
== 稳定标题

这一段中，#stable-heading 是稳定 ID，.concept 是 role，稳定标题 是标题文本。

引用规则参见 xref:stable-heading[稳定标题]。

这条 xref 表示参见目标标题。投影时，这条引用使用默认谓词 aat:references。

引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on]。

写入 rel=depends-on 时，作者声明当前标题到目标标题的依赖关系。投影时，这条关系使用 rel:depends-on。

第二部：显式身份与关系

本部展示显式身份和显式关系。role 描述标题身份；rel 描述 xref 边上的关系谓词。

4. role 身份

role 标明标题身份。作者使用标题 attrlist 中的点号 token 声明该标题在书稿中的角色。

需要标明标题身份时，可以把 role 写在稳定 ID 后面。

[#stable-heading.concept]
== 稳定标题

[#xref-rule.rule]
== 引用规则

#stable-heading 和 #xref-rule 是稳定 ID。.concept 和 .rule 是 role。role 帮助读者和工具判断标题承担的身份。

role 示例作用

role 示例	作用
`[.concept]`	标记概念说明。
`[.rule]`	标记规则说明。
`[.example]`	标记示例。

[.concept]

标记概念说明。

[.rule]

标记规则说明。

[.example]

标记示例。

同一本书使用 role 时，应保留小型、稳定、可读的 role 集。role 用于标题身份；标题之间的关系由 xref 和 rel 表达。

5. rel 关系谓词

rel 是 xref 边上的关系谓词。xref 所在的标题是 source heading，xref 指向的标题是 target heading。

引用规则参见 xref:stable-heading[稳定标题]。
引用规则依赖 xref:stable-heading[稳定标题, rel=depends-on]。

第一行表示参见 稳定标题，投影为 aat:references。第二行写入 rel=depends-on，声明 引用规则 到 稳定标题 的依赖关系，投影为 rel:depends-on。

rel 会被读者和工具当作关系谓词。同一本书使用 rel 时，应保持谓词含义稳定。

depends-on	source heading 的判断、规则或操作以 target heading 为依据。阅读顺序和先读建议使用普通 xref 表达。
illustrates	source heading 提供 target heading 的示例。
defines	source heading 给出 target heading 所代表对象的定义。
constrains	source heading 对 target heading 的合法写法或范围施加约束。

关系谓词描述标题之间的边。标题自身的身份使用 role 表达。

第三部：附加字段与检索入口

本部展示附加字段、索引词和术语表。附加字段保留源文档表面事实；索引词和术语表服务读者检索和概念解释。

6. 附加字段

named attributes 是源文档表面字段。标题 attrlist 和 xref attribute 可以携带 named attributes；工具链可以保留这些字段。

[#example.example, owner=writing-team]
== 示例

示例说明 xref:stable-heading[稳定标题, rel=illustrates, weight=strong]。

.example 是 role。owner=writing-team 是标题附加字段。weight=strong 是 xref 边证据上的附加字段。

字段名和字段值应来自本书自己的约定。同一本书使用附加字段时，应保持字段写法和字段含义稳定。

7. 索引词与术语表

索引词面向书后索引和读者检索。术语表面向词义解释。role 面向标题身份。rel 面向标题之间的关系。

正文里已经自然出现该词时，使用可见索引词标记。正文没有自然出现该词，但当前位置需要索引入口时，才使用隐藏索引词。

indexterm2:[role]
indexterm:[relation predicate]

术语表用于解释本书采用的少量术语。稳定术语帮助作者、读者和维护者使用同一组词理解源文档。

Appendix A: 附录 A：结构化写法速查

写法含义

写法	含义
`== 标题`	创建书稿阅读结构。
`[#stable-id]`	为重要标题声明稳定 ID。
`[#stable-id.concept]`	声明稳定 ID，并用 role 标明标题身份。
`显示文本`	普通引用；默认语义为 references。
`显示文本`	显式关系引用；`rel` 选择关系谓词。
`[#example.example, owner=writing-team]`	role 声明标题身份；named attributes 保留附加字段。
`role`	正文可见索引词。
	正文隐藏索引词。

== 标题

创建书稿阅读结构。

[#stable-id]

为重要标题声明稳定 ID。

[#stable-id.concept]

声明稳定 ID，并用 role 标明标题身份。

显示文本

普通引用；默认语义为 references。

显示文本

显式关系引用；rel 选择关系谓词。

[#example.example, owner=writing-team]

role 声明标题身份；named attributes 保留附加字段。

role

正文可见索引词。

正文隐藏索引词。

role 描述标题身份。rel 描述 xref 边上的关系谓词。named attributes 是附加字段。

术语表

本术语表记录结构化书写约定中的核心术语。

heading: 使用等号标题创建的书稿结构单位。
stable ID: 作者声明的稳定引用地址，例如 #stable-heading。
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 区分正文可见索引词和正文隐藏索引词：

写法含义

写法	含义
`<primary>`	正文可见，同时作为一级索引项。
	正文不可见，作为一级索引项。
	正文不可见，作为二级索引项。
	正文不可见，作为三级索引项。

<primary>

正文可见，同时作为一级索引项。

正文不可见，作为一级索引项。

正文不可见，作为二级索引项。

正文不可见，作为三级索引项。

正文中已经出现该词时，优先使用正文可见索引词。正文没有出现该词，但当前位置需要进入索引时，才使用正文隐藏索引词。

隐藏索引词应贴近它标记的段落内容。本书把隐藏索引词放在相关句子末尾，避免形成独立空段落。

Asciidoctor 的内置 HTML5 转换器不会自动生成索引目录。[index] section 是 PDF 和 DocBook 工具链自动填充索引目录的种子位置；在本 HTML 样本中，它展示后置索引章节的位置和索引词写法。

本书正文中的索引词示例：

indexterm2:[role]
indexterm:[relation predicate]

结构化书写约定标本