= 结构化写作样例

[#regular-heading.concept]
== 常规标题

常规标题提供可引用的阅读单位。

[#basic-syntax.example]
=== 基本语法

基本语法是常规标题下的直接子标题。

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

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

<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]
== 林黛玉

林黛玉是……她与 xref:贾宝玉[rel=love] 有木石前盟。

[.requirement, category=性能]
== REQ-2024-0088

[#regular-heading.concept]
== 常规标题

引用规则参见 xref:regular-heading[常规标题]。

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

[.rule]
== 引用规则

=== 基本语法

[.example]
=== 一个完整示例

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

[#regular-heading.concept]
== 常规标题

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

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

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

示例说明 xref:regular-heading[常规标题, rel=illustrates, weight=strong]。

[#rule.example, status=active]
== 示例规则

priority:: normal
summary::
示例规则说明标题字段的描述列表写法。
多行说明保留为同一个标题字段。

示例规则正文从这里开始。

indexterm2:[role]
indexterm:[relation predicate]

1. 当前标题是否为文档大标题？
   ├─ 是：使用 `= 书名`，并放置于文档首行。流程结束。
   └─ 否：评估逻辑层级。

2. 当前标题与紧邻上级标题的层级关系是否连续？
   ├─ 否：补充中间层级标题，保持标题层级连续；回到节点 2 重新评估。
   └─ 是：评估区域划分。

3. 当前标题下的文本区域后续是否需要被精准指向或提及？
   ├─ 是：使用更小一级标题将该区域独立划分，后续用 xref 指向该标题。流程结束。
   └─ 否：评估 section style。

4. 当前标题是否承载附录、术语表、参考文献或索引等后置结构？
   ├─ 是：在等号标题上方声明对应 section style：
   │      `[appendix]`、`[glossary]`、`[bibliography]` 或 `[index]`。
   │      section style 改变紧随其后 section 的语义；标题层级仍由 `=` 数量决定。
   │      流程结束。
   └─ 否：写入标准等号标题。流程结束。

1. 当前标题文本是否已是领域内唯一且稳定的标识符？
   ├─ 是：不声明 `[#stable-id]`；直接使用标题文本作为引用地址。流程结束。
   └─ 否：评估交叉引用状态。

2. 该标题在全书范围内是否被至少一个 `xref` 交叉引用？
   ├─ 否：不声明 `[#stable-id]`。流程结束。
   └─ 是：在等号标题上方的 attrlist 中显式声明 `[#stable-id]`。流程结束。

1. 扫描源文件中所有手工显式声明的 `[#stable-id]`。
   ├─ 每个 ID 对应的 xref 引用次数 >= 1：保留声明，审查通过。
   └─ 某个 ID 对应的 xref 引用次数 == 0：移除该 `[#stable-id]` 声明。

1. 当前标题是否为其父标题的下级标题？
   ├─ 否：从受控词表中选取匹配当前语境的 role，写入标题 attrlist。流程结束。
   └─ 是：评估语境连续性。

2. 当前子标题承载的认知角色是否与父标题声明的 role 相同？
   ├─ 是：不重复声明 role；下级标题默认属于同一角色范围。流程结束。
   └─ 否：从受控词表中选取匹配新语境的 role，显式写入当前标题 attrlist。
          该声明完成语境切换。流程结束。

1. 当前引用是否跨越 `= 书名`、`= 卷/部`、`== 章` 等大跨度指代？
   ├─ 是：手动写入 `xref`，平衡隐式上下文的阅读压力；进入关系评估。
   └─ 否：评估文件位置。

2. 目标标题是否位于不同的物理源文件中？
   ├─ 是：在文档头部定义文档属性存储基础路径；
   │      后续通过该属性调用基础路径进行跨文件引用；进入关系评估。
   └─ 否：进入关系评估。

3. 引用目的是什么？
   ├─ 表达阅读顺序、先读建议或普通参见：
   │      写入普通 xref，例如 `xref:target-id[显示文本]`。
   │      投影为默认谓词 `aat:references`。流程结束。
   └─ 声明明确的逻辑关系边：选取 `rel` 谓词。

4. 根据全书约定的关系谓词选择 `rel`。
   ├─ 当前标题的判断、规则或操作以目标标题为依据：使用 `rel=depends-on`。
   ├─ 当前标题提供目标标题的示例：使用 `rel=illustrates`。
   ├─ 当前标题给出目标标题所代表对象的定义：使用 `rel=defines`。
   └─ 当前标题对目标标题的合法写法或范围施加约束：使用 `rel=constrains`。

1. 字段描述的主体是什么？
   ├─ xref 引用边：将字段写入 xref 的 named attributes 中。流程结束。
   └─ heading 标题节点：评估字段体积。

2. heading 字段数量和长度是否适合写入标题 attrlist？
   ├─ 字段较少，且字段值较短：写入标题前方 attrlist。
   │      例如 `[owner=writing-team, status=active]`。流程结束。
   └─ 字段较多，或包含多行字段值：
          写入紧随标题下方的第一个连续描述列表。
          例如 `key:: value`。流程结束。

1. 新文件在逻辑序列中的位置是什么？
   ├─ 位于当前既有序列的最后方：执行末尾追加。
   └─ 位于当前既有文件 A 与文件 B 之间：执行中间插入。

2. 末尾追加：
   提取当前同级列表中的最大编号，将其十位数字加 1，个位保持 0。
   流程结束。

3. 中间插入：
   提取上文文件 A 和下文文件 B 的编号，计算两者的算术中间值。
   例如在 `010` 与 `020` 之间插入，使用 `015`。
   流程结束。

1. 索引目标词是否已经自然出现在当前正文句子中？
   ├─ 是：使用正文可见索引词宏 `indexterm2:[<primary>]` 包裹该词。
   │      正文保持可见，同时提取为一级索引项。流程结束。
   └─ 否：使用正文隐藏索引词宏 `indexterm:[<primary>]`。
          按需使用多级形式，例如 `indexterm:[<primary>, <secondary>]`。
          隐藏索引词贴近相关段落内容，放在相关句子末尾。流程结束。

1. 正文中是否出现 AsciiDoc 原生语法字符，且需要阻止其被解析引擎渲染？
   ├─ 是：使用 `pass:[]` 宏包裹该内容。
   │      若需要代码字体样式，在外层叠加反引号包裹。流程结束。
   └─ 否：评估解释关联。

2. 当前是否为代码或日志结构，且配有单独的文字解释？
   ├─ 是：使用 AsciiDoc callouts 标注代码或日志与解释之间的关联。流程结束。
   └─ 否：正常书写。流程结束。

indexterm2:[role]
indexterm:[relation predicate]
indexterm:[源文件编排号]
indexterm:[中间值插入]
indexterm:[描述列表]