create-asciidoc-multi-book-workspace 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.4.0 - 2026-10-21
+
+### Added
+
+- Add `--solo` to the `create` command and export `initSoloWorkspace` from the package root: generate a workspace that contains only the structured writing conventions book, shelved as book 01.
+- Add the chapter "声明本书的约定" (declaring the book's conventions) to the structured writing conventions sample: `.convention` headings with `declares=roles|relations|values|fields` write a book's controlled vocabularies in the book itself, so readers, check scripts, and query tools read one source. A `fields` declaration can carry `id-prefix` for roles whose address labels are existing technical addresses.
+
+### Changed
+
+- Show in the structured writing conventions sample how a field value attaches a code block or table with `+`, and list every way a description list stops counting as fields: an unattached block, another block between the heading and the list, block attributes on the list, or a nested description list. It also shows how to keep a description list under a heading as body text.
+- State that a heading's role scope is a reading context: projection, checks, and query tools read only the role written on each heading.
+- Add a decision tree for declaring and maintaining conventions, and update the quick reference, glossary, and part introductions.
+
+## 0.3.1 - 2026-10-15
+
+### Changed
+
+- Rework the structured writing conventions sample around names and addressing: headings now serve as the canonical name and default xref target, while `[#...]` is presented only as an explicit address label for existing technical or external addresses.
+- Reorganize part two of the structured writing conventions sample from identity-and-relation into names-roles-and-relations, adding guidance on renames, aliases, concept-boundary changes, splits, and retirements.
+- Update the quick reference, decision trees, glossary, part introductions, and catalog descriptions to drop the stable-ID teaching path.
+
 ## 0.3.0 - 2026-07-26
 
 ### Changed

package/README.md

@@ -13,6 +13,14 @@ pnpm install
 pnpm run build
 ```
 
+For a workspace with only the structured writing conventions book (shelved as book 01), add `--solo`:
+
+```bash
+pnpm create asciidoc-multi-book-workspace my-book --solo
+```
+
+See [Solo Workspace](#solo-workspace).
+
 npm users can run:
 
 ```bash
@@ -36,6 +44,8 @@ console.log(result.targetDir);
 
 The host CLI owns command parsing and user-facing output. This package owns the workspace files it creates.
 
+`initSoloWorkspace` takes the same options and creates the [solo workspace](#solo-workspace).
+
 The generated workspace contains:
 
 ```text
@@ -58,6 +68,23 @@ shared/images/workspace-map.svg
 
 It does not include this repository's `test/`, `.github/`, `src/`, `dist/`, `DESIGN.adoc`, or maintainer release checks.
 
+## Solo Workspace
+
+The solo workspace holds one book: sample book `07-structured-writing-conventions`, shelved as
+`books/01-structured-writing-conventions`, with a short catalog and README written for it:
+
+```text
+README.md
+catalog.adoc
+package.json
+.gitignore
+tools/adoc-books.mjs
+books/01-structured-writing-conventions
+shared/attributes.adoc
+```
+
+The other sample books stay in the template and are generated only by the default workspace.
+
 ## Generated Workspace
 
 The generated `package.json` directly lists the AsciiDoc toolchain:
@@ -81,6 +108,7 @@ pnpm run clean
 ```text
 src/                         # TypeScript initializer and user runtime source
 templates/default-workspace/ # true source for the generated user workspace
+templates/solo-workspace/    # catalog and README written for the solo workspace
 test/                        # maintainer tests
 DESIGN.adoc                  # maintainer design specification
 .github/                     # maintainer CI

package/dist/create.js

@@ -1,13 +1,20 @@
 #!/usr/bin/env node
 import path from "node:path";
-import { initWorkspace } from "./init-workspace.js";
+import { initSoloWorkspace, initWorkspace } from "./init-workspace.js";
 function usage() {
     return [
         "Usage:",
-        "  create-asciidoc-multi-book-workspace <target>",
+        "  create-asciidoc-multi-book-workspace <target> [--solo] [--force]",
+        "",
+        "Options:",
+        "  --solo   one book only: the structured writing conventions sample, shelved as",
+        "           books/01-structured-writing-conventions",
+        "  --force  write into a non-empty target; template output paths are overwritten,",
+        "           other files are kept",
         "",
         "Examples:",
         "  pnpm create asciidoc-multi-book-workspace my-books",
+        "  pnpm create asciidoc-multi-book-workspace my-book --solo",
         "  npm create asciidoc-multi-book-workspace@latest my-books"
     ].join("\n");
 }
@@ -23,7 +30,8 @@ async function main() {
         process.exitCode = 1;
         return;
     }
-    const result = await initWorkspace({ targetDir: target, force: args.includes("--force") });
+    const init = args.includes("--solo") ? initSoloWorkspace : initWorkspace;
+    const result = await init({ targetDir: target, force: args.includes("--force") });
     const displayTarget = path.relative(process.cwd(), result.targetDir) || ".";
     console.log(`Created AsciiDoc multi-book workspace in ${displayTarget}`);
     console.log("");

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { initWorkspace } from "./init-workspace.js";
+export { initSoloWorkspace, initWorkspace } from "./init-workspace.js";
 export type { InitWorkspaceOptions, InitWorkspaceResult } from "./init-workspace.js";

package/dist/index.js

@@ -1 +1 @@
-export { initWorkspace } from "./init-workspace.js";
+export { initSoloWorkspace, initWorkspace } from "./init-workspace.js";

package/dist/init-workspace.d.ts

@@ -7,3 +7,4 @@ export interface InitWorkspaceResult {
     packageName: string;
 }
 export declare function initWorkspace(options: InitWorkspaceOptions): Promise<InitWorkspaceResult>;
+export declare function initSoloWorkspace(options: InitWorkspaceOptions): Promise<InitWorkspaceResult>;

package/dist/init-workspace.js

@@ -1,10 +1,10 @@
 import { cp, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { defaultWorkspaceTemplate, templatePackageNamePlaceholder } from "./template-manifest.js";
+import { defaultWorkspaceCopies, packageJsonTemplate, soloWorkspaceCopies, templatePackageNamePlaceholder } from "./template-manifest.js";
 const sourceDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(sourceDir, "..");
-const templateRoot = path.join(packageRoot, "templates", defaultWorkspaceTemplate);
+const templatesRoot = path.join(packageRoot, "templates");
 const runtimeScript = path.join(packageRoot, "dist", "runtime", "adoc-books.mjs");
 async function exists(filePath) {
     try {
@@ -32,27 +32,29 @@ function safePackageName(rawName) {
         .replaceAll(/^-+|-+$/g, "");
     return normalized || "asciidoc-books";
 }
-async function copyTemplatePath(name, targetDir) {
-    await cp(path.join(templateRoot, name), path.join(targetDir, name), {
-        force: true,
-        recursive: true
-    });
-}
-export async function initWorkspace(options) {
+async function createWorkspace(options, copies) {
     const targetDir = path.resolve(options.targetDir);
     const targetExists = await exists(targetDir);
     if (targetExists && !options.force && !await isEmptyDirectory(targetDir)) {
         throw new Error(`target directory is not empty: ${targetDir}`);
     }
     await mkdir(targetDir, { recursive: true });
-    for (const name of ["README.md", "catalog.adoc", "books", "shared"]) {
-        await copyTemplatePath(name, targetDir);
+    for (const { from, to } of copies) {
+        await cp(path.join(templatesRoot, from), path.join(targetDir, to), {
+            force: true,
+            recursive: true
+        });
     }
-    const packageTemplate = await readFile(path.join(templateRoot, "package.json.template"), "utf8");
+    const packageTemplate = await readFile(path.join(templatesRoot, packageJsonTemplate), "utf8");
     const packageName = safePackageName(path.basename(targetDir));
     await writeFile(path.join(targetDir, "package.json"), packageTemplate.replaceAll(templatePackageNamePlaceholder, packageName), "utf8");
-    await writeFile(path.join(targetDir, ".gitignore"), await readFile(path.join(templateRoot, "gitignore.template"), "utf8"), "utf8");
     await mkdir(path.join(targetDir, "tools"), { recursive: true });
     await cp(runtimeScript, path.join(targetDir, "tools", "adoc-books.mjs"), { force: true });
     return { targetDir, packageName };
 }
+export async function initWorkspace(options) {
+    return createWorkspace(options, defaultWorkspaceCopies);
+}
+export async function initSoloWorkspace(options) {
+    return createWorkspace(options, soloWorkspaceCopies);
+}

package/dist/template-manifest.d.ts

@@ -1,3 +1,10 @@
-export declare const defaultWorkspaceTemplate = "default-workspace";
+export interface TemplateCopy {
+    /** Path under `templates/`. */
+    from: string;
+    /** Path inside the generated workspace. */
+    to: string;
+}
 export declare const templatePackageNamePlaceholder = "{{name}}";
-export declare const fixedTemplateOutputPaths: readonly ["README.md", "catalog.adoc", "package.json", ".gitignore", "tools/adoc-books.mjs", "books", "shared"];
+export declare const packageJsonTemplate = "default-workspace/package.json.template";
+export declare const defaultWorkspaceCopies: readonly TemplateCopy[];
+export declare const soloWorkspaceCopies: readonly TemplateCopy[];

package/dist/template-manifest.js

@@ -1,11 +1,26 @@
-export const defaultWorkspaceTemplate = "default-workspace";
 export const templatePackageNamePlaceholder = "{{name}}";
-export const fixedTemplateOutputPaths = [
-    "README.md",
-    "catalog.adoc",
-    "package.json",
-    ".gitignore",
-    "tools/adoc-books.mjs",
-    "books",
-    "shared"
+// Rendered with the target's package name instead of copied, so it stays outside the copy
+// tables; every workspace shape renders this same file.
+export const packageJsonTemplate = "default-workspace/package.json.template";
+// A copy table is the complete list of template content a workspace shape receives;
+// the initializer adds only the rendered package.json and tools/adoc-books.mjs.
+// `gitignore.template` exists because npm drops `.gitignore` files from published packages.
+export const defaultWorkspaceCopies = [
+    { from: "default-workspace/README.md", to: "README.md" },
+    { from: "default-workspace/catalog.adoc", to: "catalog.adoc" },
+    { from: "default-workspace/books", to: "books" },
+    { from: "default-workspace/shared", to: "shared" },
+    { from: "default-workspace/gitignore.template", to: ".gitignore" }
+];
+// One book on its own shelf: sample book 07 is shelved as 01. The catalog and README are
+// written for this shelf; shared/images/ stays behind because only the sample catalog uses it.
+export const soloWorkspaceCopies = [
+    { from: "solo-workspace/README.md", to: "README.md" },
+    { from: "solo-workspace/catalog.adoc", to: "catalog.adoc" },
+    {
+        from: "default-workspace/books/07-structured-writing-conventions",
+        to: "books/01-structured-writing-conventions"
+    },
+    { from: "default-workspace/shared/attributes.adoc", to: "shared/attributes.adoc" },
+    { from: "default-workspace/gitignore.template", to: ".gitignore" }
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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

@@ -32,33 +32,40 @@
 |`010-opening.adoc`
 |Chapter 文件的源文件编排号。规则与 Part 目录编排号一致。
 
-|`[#stable-id]`
-|为标题声明一个稳定的引用地址。稳定 ID 仅当以下两个条件同时满足时才需显式声明：
-(1) 该标题被至少一个 `xref` 交叉引用；
-(2) 标题文本本身可能变更或在全书范围内可能重复。
-若标题本身已是领域内唯一且稳定的标识符（如专有名词、唯一实体名、标准化编号），即使被交叉引用，也无需额外声明稳定 ID——标题文本即地址。
+|`== 标题`
+|创建标题节点；标题给出当前规范名称。
 
-|`[#stable-id.concept]`
-|声明稳定 ID，并用 role 标明标题身份。
-需要能够回答： “这个标题在整本书的知识体系中扮演什么认知功能”
+|`[.concept]`
+|用 role 标记标题在书中的作用。
 
-|`[#example.example, owner=writing-team]`
-|role 声明标题身份；named attributes 保留附加字段。
+|`[#address-label]`
+|为标题附加显式寻址标签。它用于找到标题。
+
+|`[.example, owner=writing-team]`
+|role 和 named attributes 保留标题的作用与附加字段。
+
+|`[.convention, declares=roles]`
+|约定声明。标题下的描述列表是本书的 role 词表；`declares` 还可以取 `relations`、`values`（配 `for` 与 `field`）和 `fields`（配 `for`）。
 
 |`summary::` + 下一行说明文本
 |标题下描述列表字段。用于较多字段或多行字段值。
 
-|`pass:[xref:stable-id[显示文本]]`
+|字段文字之后的 `+` + 块
+|把代码块、表格等挂到字段上，块属于字段值。字段之间不插入不带 `+` 的块。
+
+|`pass:[xref:标题[显示文本]]`
 |显示为链接，投影为 references。
 
-|`pass:[xref:stable-id[显示文本, rel=depends-on]]`
+|`pass:[xref:标题[显示文本, rel=depends-on]]`
 |显示为链接，同时声明 depends-on 关系。
 
 |===
 
 全书标题需要保持 `标题层级连续`。
 
-role 描述标题身份。rel 描述 xref 边上的关系谓词。附加字段可以写在标题 attrlist、标题下描述列表或 xref named attributes 中。
+role 描述标题在书中的作用。rel 描述 xref 边上的关系谓词。附加字段可以写在标题 attrlist、标题下描述列表或 xref named attributes 中。
+
+标题改名时，更新引用；旧称有保留价值时写入别名。概念被拆分或废止时，保留历史标题并写明后续使用的标题。
 
 `[appendix]`、`[glossary]` 和 `[bibliography]` 是 section style。它们改变紧随其后 section 的语义；标题层级仍由 `=` 数量决定。
 

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

@@ -27,33 +27,38 @@
    └─ 否：写入标准等号标题。流程结束。
 ----
 
-== stable ID 的生命周期与寻址机制
+== 名称变化与寻址标签
 
-触发场景:: 作者评估是否需要为当前标题显式声明寻址 ID。
+触发场景:: 作者发现当前标题、旧称或引用地址发生变化。
 
 [source,text]
 ----
-1. 当前标题文本是否已是领域内唯一且稳定的标识符？
-   ├─ 是：不声明 `[#stable-id]`；直接使用标题文本作为引用地址。流程结束。
-   └─ 否：评估交叉引用状态。
+1. 当前标题还是该对象的规范名称吗？
+   ├─ 是：继续使用标题。
+   └─ 否：判断变化类型。
 
-2. 该标题在全书范围内是否被至少一个 `xref` 交叉引用？
-   ├─ 否：不声明 `[#stable-id]`。流程结束。
-   └─ 是：在等号标题上方的 attrlist 中显式声明 `[#stable-id]`。流程结束。
-----
+2. 只是换成更准确的名称吗？
+   ├─ 是：改标题，更新引用；旧称有价值时写入别名。
+   └─ 否：检查概念边界。
 
-触发场景:: 项目全局构建或审查阶段检查 stable ID 消费状态。
+3. 概念边界改变了吗？
+   ├─ 是：检查描述、纳入条件、排除条件、相关标题和既有结论。
+   └─ 否：完成名称更新。
 
-[source,text]
-----
-1. 扫描源文件中所有手工显式声明的 `[#stable-id]`。
-   ├─ 每个 ID 对应的 xref 引用次数 >= 1：保留声明，审查通过。
-   └─ 某个 ID 对应的 xref 引用次数 == 0：移除该 `[#stable-id]` 声明。
+4. 旧概念被拆分或废止了吗？
+   ├─ 是：保留历史标题，写明后续标题。
+   └─ 否：继续维护当前标题。
+
+5. 是否已有外部技术地址必须保留？
+   ├─ 是：为标题保留显式寻址标签。
+   └─ 否：不增加标签。
 ----
 
+跨改名追踪记录和冻结内容版本，由工具层分别处理，不由标题的显式寻址标签承担。
+
 == role 的作用域与语境管理
 
-触发场景:: 作者为标题标记认知功能与身份语义。
+触发场景:: 作者为标题标记认知作用。
 前提:: 当前书稿已经约定 role 受控词表，例如 `.concept`、`.rule`、`.example`。
 
 [source,text]
@@ -63,7 +68,8 @@
    └─ 是：评估语境连续性。
 
 2. 当前子标题承载的认知角色是否与父标题声明的 role 相同？
-   ├─ 是：不重复声明 role；下级标题默认属于同一角色范围。流程结束。
+   ├─ 是：写作时可以不重复声明 role，读者按语境理解为同一角色范围。
+   │      工具只读标题自己写下的 role：想让检查核对它的字段、让查询列出它，就自己写上 role。流程结束。
    └─ 否：从受控词表中选取匹配新语境的 role，显式写入当前标题 attrlist。
           该声明完成语境切换。流程结束。
 ----
@@ -85,7 +91,7 @@
 
 3. 引用目的是什么？
    ├─ 表达阅读顺序、先读建议或普通参见：
-   │      写入普通 xref，例如 `xref:target-id[显示文本]`。
+   │      写入普通 xref，例如 `xref:目标标题[显示文本]`。
    │      投影为默认谓词 `aat:references`。流程结束。
    └─ 声明明确的逻辑关系边：选取 `rel` 谓词。
 
@@ -111,9 +117,38 @@
    │      例如 `[owner=writing-team, status=active]`。流程结束。
    └─ 字段较多，或包含多行字段值：
           写入紧随标题下方的第一个连续描述列表。
-          例如 `key:: value`。流程结束。
+          例如 `key:: value`。进入块评估。
+
+3. 字段值是否需要附带代码块、表格或另一段正文？
+   ├─ 是：在字段文字之后写一行 `+`，再写块；块属于字段值。
+   │      字段之间不插入不带 `+` 的块，否则字段列表在块前结束。流程结束。
+   └─ 否：流程结束。
 ----
 
+== 约定的声明与维护
+
+触发场景:: 作者为本书引入或修改 role、rel 谓词、字段取值或字段。
+
+[source,text]
+----
+1. 本书是否已有对应的约定声明？
+   ├─ 是：在该声明的描述列表中增加、修改或删除 term；进入类型评估。
+   └─ 否：新建声明标题，放在读者最先读到约定的地方（例如前言里专设一节“本书的书写约定”），
+          写 `[.convention, declares=...]`；进入类型评估。
+
+2. 声明的是什么？
+   ├─ role：`declares=roles`。
+   ├─ rel 谓词：`declares=relations`。
+   ├─ 某个 role 的附加字段取值：`declares=values, for=<role>, field=<字段名>`。
+   └─ 某个 role 的标题下描述列表字段：`declares=fields, for=<role>`。
+
+3. term 是否写成写作时使用的那个词？
+   ├─ 否：去掉点号与反引号，例如 `.concept` 写成 `concept`；回到本步重新判断。
+   └─ 是：在描述中写出这个词的含义。流程结束。
+----
+
+约定变化时只改声明。检查脚本和查询工具从声明读出词表，不另外维护一份。
+
 == 源文件物理编排与编号运算
 
 触发场景:: 作者为 Part 目录或 Chapter 源文件生成文件编排号。

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

@@ -4,14 +4,16 @@
 
 [glossary]
 heading:: 使用等号标题创建的书稿结构单位。
-stable ID:: 作者为标题显式声明的稳定引用地址，语法为 `[#id]`。
-仅当标题被交叉引用、且标题文本自身不能保证全局唯一和不变时才需使用。
-若标题文本已是领域内唯一的稳定标识符（如实体名称、标准化编号），
-标题文本本身即承担 stable ID 的寻址功能，无需额外声明。
+规范名称:: 当前书稿采用的标题名称。
+显式寻址标签:: 作者用 `[#label]` 附加给标题的地址标签。它用于找到标题。
+别名:: 标题以外仍有检索、历史或语境价值的名称。
+不透明记录键:: 工具层用于跨改名追踪同一条记录的机器键。
+内容哈希:: 标识某次冻结内容的校验值。
 source-order notation:: 写在源文件路径表面的排序符号。
-role:: 标题身份标记，例如 `.concept` 或 `.rule`。
+role:: 标题节点在书中承担的叙述作用，例如 `.concept`、`.rule` 或 `.example`。
 ordinary reference:: 普通 xref。投影时使用默认谓词 `aat:references`。
 relation predicate:: xref `rel` 字段选择的边谓词。
 source heading:: xref 所在的标题。
 target heading:: xref selector 指向的标题。
 surface field:: 源文档表面的附加字段。标题字段可来自标题 attrlist 或标题下描述列表；xref 边字段来自 xref named attributes。
+约定声明:: 带 `.convention` role 的标题。`declares` 字段说明它声明 role、rel 谓词、字段取值还是字段；标题下的描述列表是词表，term 是词，描述是含义。

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

@@ -36,18 +36,20 @@ include::parts/010-source-surface/_partintro.adoc[]
 
 include::parts/010-source-surface/010-source-and-projection.adoc[]
 
-include::parts/010-source-surface/020-default-semantics.adoc[]
+include::parts/010-source-surface/020-heading-address-and-xref.adoc[]
 
 include::parts/010-source-surface/030-source-order-notation.adoc[]
 
-= 给标题和引用加意图
+= 名称、角色与关系
 
 [partintro]
-include::parts/020-identity-and-relation/_partintro.adoc[]
+include::parts/020-names-roles-and-relations/_partintro.adoc[]
 
-include::parts/020-identity-and-relation/010-role-identity.adoc[]
+include::parts/020-names-roles-and-relations/010-names-and-address-labels.adoc[]
 
-include::parts/020-identity-and-relation/020-relation-predicate.adoc[]
+include::parts/020-names-roles-and-relations/020-heading-roles.adoc[]
+
+include::parts/020-names-roles-and-relations/030-relation-predicate.adoc[]
 
 = 字段与术语
 
@@ -58,6 +60,8 @@ include::parts/030-fields-and-terminology/010-surface-fields.adoc[]
 
 include::parts/030-fields-and-terminology/020-glossary.adoc[]
 
+include::parts/030-fields-and-terminology/030-declaring-conventions.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 和附加字段形成可读、可维护、可投影的源文档的方式。作者可按写作目的选择其中写法。
+本书说明标题、引用、role、rel 和附加字段怎样共同构成可读、可维护、可投影的源文档。标题保存当前规范名称；引用用地址找到标题；显式寻址标签只在已有技术地址需要保留时使用。

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

@@ -1,3 +1,3 @@
 == 致谢
 
-感谢 Asciidoctor 和 RDF 投影相关文档提供稳定术语和结构坐标。
+感谢 Asciidoctor 和 RDF 投影相关文档提供术语与结构坐标。

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

@@ -1,14 +1,7 @@
 == 前言
 
-这本书按源文档写法组织。阅读时先看源文档片段和投影片段，再对照后续章节理解每个标记承担的职责。
+这本书把标题、引用、role、rel 和附加字段放在同一份 AsciiDoc 源文档中。标题给出当前规范名称；xref 找到标题；role 说明标题在书中的作用；rel 说明引用表达的关系。
 
-实际书稿按写作目的选择这些写法。
-长期引用且标题文本可能变更的标题使用稳定 ID；
-若标题本身已是唯一且稳定的实体名称，标题文本直接作为引用地址。
-带有明确身份的标题使用 role；表达关系的引用使用 rel；
-随源稿保留的短字段使用 named attributes；字段较多或需要多行值的标题字段使用标题下描述列表。
+显式寻址标签只保留已经存在的技术地址。旧称、俗称和历史名称写入别名，不隐藏在地址字符串中。字段较少且值较短时写在标题 attrlist；字段较多或需要多行值时写在标题下的连续描述列表。
 
-业务含义由书稿自己的约定承载。本书展示同一份 AsciiDoc 源文本如何同时服务阅读、维护和工具链投影。
-
-通过展示标题、稳定 ID、role、xref、rel 和附加字段如何形成可读、可维护、可投影的源文档，让你能够理解，你可以拥有一种这样的表达方式，可以按照某种约定，就能够提升你书籍的质量，能够让下游的工具链继续消费你的书。 你可以参考本书里你所需要的结构。
-合适的结构能够提升书籍的可阅读、可维护性。你可以按写作目的选择其中写法。
+同一份源文档因此同时保留阅读结构、维护所需的名称和关系，以及工具可以继续投影的字段。

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

@@ -2,49 +2,49 @@
 == 源文本与投影
 
 本章用一段示例展示结构化书写约定。Turtle 片段列出关键投影事实；完整投影还会保留 raw、路径、行号和边证据。
-希望你能通过本章节的演示来理解你写下的文字能够给未来的你提供稳定的查询与导航结构。
+本章节的演示展示文字如何形成清晰的查询与导航结构。
 
 [source,asciidoc]
 ----
 = 结构化写作样例
 
-[#regular-heading.concept]
+[.concept]
 == 常规标题
 
 常规标题提供可引用的阅读单位。
 
-[#basic-syntax.example]
+[.example]
 === 基本语法
 
 基本语法是常规标题下的直接子标题。
 
-[#xref-rule.rule]
+[.rule]
 == 引用规则
 
-引用规则参见 xref:regular-heading[常规标题]。
-引用规则依赖 xref:regular-heading[常规标题, rel=depends-on, weight=strong]。
+引用规则参见 xref:常规标题[]。
+引用规则依赖 xref:常规标题[常规标题, rel=depends-on, weight=strong]。
 ----
 
 源文档把 `常规标题` 写成可引用的阅读单位，在其下写出 `基本语法` 子标题，把 `引用规则` 写成规则说明，并在正文里写出参见和依赖两种引用。
 
-Turtle 示例中的 `<urn:aat:doc:...#heading-*>` 和 `<urn:aat:doc:...#xref-edge-*>` 表示投影生成的 IRI；`aat:addressLabel` 保留源文档中的寻址 label。
+Turtle 示例中的 `<urn:aat:doc:...#heading-*>` 和 `<urn:aat:doc:...#xref-edge-*>` 表示投影生成的文档节点 IRI。本例没有为标题附加显式寻址标签，因此 `aat:addressLabel` 与标题文字一致。
 
 [source,turtle]
 ----
 <urn:aat:doc:...#heading-l3-o0> a aat:Heading ;
   aat:headline "常规标题" ;
-  aat:addressLabel "regular-heading" ;
+  aat:addressLabel "常规标题" ;
   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:addressLabel "基本语法" ;
   aat:role "example" .
 
 <urn:aat:doc:...#heading-l13-o0> a aat:Heading ;
   aat:headline "引用规则" ;
-  aat:addressLabel "xref-rule" ;
+  aat:addressLabel "引用规则" ;
   aat:role "rule" ;
   aat:references <urn:aat:doc:...#heading-l3-o0> ;
   rel:depends-on <urn:aat:doc:...#heading-l3-o0> .
@@ -54,7 +54,7 @@ Turtle 示例中的 `<urn:aat:doc:...#heading-*>` 和 `<urn:aat:doc:...#xref-edg
   aat:weight "strong" .
 ----
 
-读者看源文档，能直接看到 [.concept]#常规标题# 是被引用的阅读单位，`基本语法` 是它的下级标题， [.rule]#引用规则# 说明引用写法。投影读取同一份源文档，为标题生成 IRI，并在标题节点上保留 `aat:headline`、`aat:addressLabel` 和 `aat:role`；标题层级投影为 `aat:containsDirectly`，xref 投影为 `aat:references` 和 `rel:depends-on`。
+源文档中的 [.concept]#常规标题# 是被引用的阅读单位，`基本语法` 是它的下级标题， [.rule]#引用规则# 说明引用写法。投影读取同一份源文档，为标题生成 IRI，并在标题节点上保留 `aat:headline`、`aat:addressLabel` 和 `aat:role`；标题层级投影为 `aat:containsDirectly`，xref 投影为 `aat:references` 和 `rel:depends-on`。
 
 [source,asciidoc]
 ----
@@ -65,8 +65,8 @@ Turtle 示例中的 `<urn:aat:doc:...#heading-*>` 和 `<urn:aat:doc:...#xref-edg
 ----
 
 此处的 `pass:[xref:贾宝玉]` 直接使用标题文本作为寻址地址，
-因为“贾宝玉”在本书范围内唯一且不会变更为其他名称。
-交叉引用宏语法是 `pass:[xref:target-id[optional-display-text]]` ，所以这里省略了别名，渲染引擎默认会展示标题文字。
+因为“贾宝玉”在当前书稿中作为唯一标题名称使用。
+交叉引用宏语法是 `pass:[xref:目标标题[可选显示文本]]`，所以这里省略了显示文本，渲染引擎默认会展示标题文字。
 
 '''
 
@@ -80,4 +80,4 @@ Turtle 示例中的 `<urn:aat:doc:...#heading-*>` 和 `<urn:aat:doc:...#xref-edg
 == REQ-2024-0088
 ----
 
-引用时可以这样： `pass:[xref:REQ-2024-0088[REQ-2024-0088, rel=constrains]]`
+`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-heading-address-and-xref.adoc

@@ -0,0 +1,55 @@
+[#heading-address-and-xref]
+== 标题、寻址与引用
+
+等号行创建标题和层级。标题给出当前规范名称；标题前的 attrlist 可以承载 role 和字段。
+
+[source,asciidoc]
+----
+[.concept]
+== 常规标题
+----
+
+`.concept` 标明标题在书中的作用。`常规标题` 是当前规范名称。
+
+[source,asciidoc]
+----
+引用规则参见 xref:常规标题[]。
+----
+
+该 xref 投影为 `aat:references`，即默认引用谓词。
+
+[source,asciidoc]
+----
+引用规则依赖 xref:常规标题[常规标题, rel=depends-on]。
+----
+
+`rel=depends-on` 声明从当前标题到目标标题的依赖关系，投影为 `rel:depends-on`。
+
+[source,asciidoc]
+----
+[#catalog-entry-482]
+== 宿舍集中备考者
+----
+
+`catalog-entry-482` 是附加给标题的显式寻址标签。外部目录已经使用这个地址时，引用可以继续使用它；标题“宿舍集中备考者”仍是当前规范名称。本书各章开头的英文标签用于阅读器页面地址；它们负责找到章节。
+
+[TIP]
+====
+1. 显式寻址标签只在已有技术地址、外部链接或阅读器页面需要保留时出现。没有这种需要时，标题直接承担引用地址。写法速查见 xref:structured-writing-quick-reference[附录 A：结构化写法速查]；完整判断流程见 xref:structured-writing-decision-trees[附录 B：结构化写法决策树]。
+2. 按照书籍结构，跨越 `= 书名`、`= 卷/部`、`== 章` 这些大跨度的指代均需要使用 `xref` 手动标注，平衡隐式上下文的阅读压力。
+====
+
+标题声明角色后，其下级标题默认属于同一角色范围。下级标题可声明不同角色以切换语境。角色范围是阅读上的语境；投影、检查和查询工具只读标题自己写下的 role，下级标题不会因此被当作同一 role 的标题核对字段或列出。
+
+例如:
+
+[source,asciidoc]
+----
+[.rule]
+== 引用规则
+
+=== 基本语法
+
+[.example]
+=== 一个完整示例
+----

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

@@ -13,7 +13,7 @@ Part 目录和 Chapter 文件统一使用三位数 `0X0` 格式进行编排。
 ----
 parts/010-source-surface/
 parts/015-new-topic/       <1>
-parts/020-identity-and-relation/
+parts/020-names-roles-and-relations/
 
 010-opening.adoc
 015-new-context.adoc       <2>
@@ -31,6 +31,6 @@ parts/020-identity-and-relation/
 
 使用三位数 `0X0` 格式，能够解决书籍动态维护过程中编号格式的稳定。
 
-标题文本保留语义名称。长期引用的标题使用显式 ID。
+编排号只安排源文件顺序。标题保存当前规范名称；引用用标题或已有的显式寻址标签找到标题。
 
-编排号帮助维护者观察源文件顺序；显式 ID 帮助读者和工具链稳定引用标题。
+编排号、标题和寻址标签承担不同职责，不互相替代。

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

@@ -1 +1 @@
-本部从一段源文档出发，展示读者看到的写作意图和投影得到的结构事实。
+标题、引用和文件路径同时构成书稿的阅读结构与可投影的源文档表面。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/020-names-roles-and-relations/010-names-and-address-labels.adoc

@@ -0,0 +1,20 @@
+[#names-and-address-labels]
+== 名称变化与寻址标签
+
+标题不只是排版上的显示文字。它是当前书稿采用的名称，也是读者、项目和引用者正在使用的名称。
+
+[.population]
+=== 宿舍集中备考者
+
+别名::
+
+* 宿舍高强度备考者（旧称）
+* 宿舍备考学生（常用称呼）
+
+标题改成“宿舍集中备考者”后，书中的 xref 与装配引用随标题更新。“宿舍高强度备考者”仍有历史检索价值时，作为旧称保留在别名中。
+
+名称变得更准确时，改标题并更新引用。概念边界改变时，同时检查描述、纳入条件、排除条件、相关标题和既有结论。旧概念被拆分或废止时，保留历史标题，写明后续应使用的标题。
+
+显式寻址标签只保留已有的技术地址。带有语义的标签是地址别名，不替代标题，也不代替概念变化的审查。
+
+工具若要跨改名追踪同一条记录，由工具层保存不透明记录键。某次冻结内容的校验，由内容哈希或快照承担。标题继续保存当前规范名称。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/{020-identity-and-relation/010-role-identity.adoc → 020-names-roles-and-relations/020-heading-roles.adoc}

@@ -1,22 +1,22 @@
-[#role-identity]
-== role 身份
+[#heading-roles]
+== 标题的 role
 
 role 写在标题 attrlist 的点号 token 位置。
 
 [source,asciidoc]
 ----
-[#regular-heading.concept]
+[.concept]
 == 常规标题
 
-[#xref-rule.rule]
+[.rule]
 == 引用规则
 ----
 
-`#regular-heading` 和 `#xref-rule` 是稳定 ID，`.concept` 和 `.rule` 是 role，标明标题身份。
+`.concept` 和 `.rule` 是 role。它们说明标题在当前书中承担概念说明或规则说明的作用。
 
 [cols="1,2", options="header"]
 |===
-|写法 |读者看到的身份
+|写法 |读者看到的作用
 
 |`[.concept]`
 |标记概念说明。
@@ -28,8 +28,10 @@ role 写在标题 attrlist 的点号 token 位置。
 |标记示例。
 |===
 
-role 的职责，是在全书范围内保持身份含义的稳定。
+同一个 role 在全书中保持同一种叙述作用。
 
 一本书使用的 role 种类和数量，取决于该领域的概念结构。每种 role 的语义在全书中保持唯一。
 
+全书的 role 词表写成约定声明，见 xref:declaring-conventions[声明本书的约定]。
+
 读者和工具链可以依据 role 进行导航文本和提取结构。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/{020-identity-and-relation/020-relation-predicate.adoc → 020-names-roles-and-relations/030-relation-predicate.adoc}

@@ -5,20 +5,22 @@
 
 [source,asciidoc]
 ----
-引用规则参见 xref:regular-heading[常规标题]。
-引用规则依赖 xref:regular-heading[常规标题, rel=depends-on]。
+引用规则参见 xref:常规标题[]。
+引用规则依赖 xref:常规标题[常规标题, rel=depends-on]。
 ----
 
 第一行投影为 `aat:references`，即默认引用谓词。第二行声明 `rel=depends-on`，投影为 `rel:depends-on`。
 
 `rel` 可以被读者和工具当作关系谓词，所以在全书范围内，每种 `rel` 谓词的语义需要保持唯一且不变。
 
+全书采用的 rel 谓词写成约定声明，见 xref:declaring-conventions[声明本书的约定]。下面列出常用的几种：
+
 [horizontal]
 depends-on:: 当前标题的判断、规则或操作以目标标题为依据。阅读顺序和先读建议使用普通 xref 表达。
 illustrates:: 当前标题提供目标标题的示例。
 defines:: 当前标题给出目标标题所代表对象的定义。
 constrains:: 当前标题对目标标题的合法写法或范围施加约束。
 
-关系谓词描述标题之间的边。标题自身的身份使用 role 表达。
+关系谓词描述标题之间的边。标题在书中的作用由 role 表达。
 
 标题之间的阅读顺序和先读建议，使用普通 xref（默认 `aat:references`）表达。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/020-names-roles-and-relations/_partintro.adoc

@@ -0,0 +1 @@
+标题给出当前名称；寻址标签提供已有的技术地址；role 说明标题节点在书中的作用；rel 说明标题之间的关系。

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

@@ -5,10 +5,10 @@
 
 [source,asciidoc]
 ----
-[#example.example, owner=writing-team]
+[.example, owner=writing-team]
 == 示例
 
-示例说明 xref:regular-heading[常规标题, rel=illustrates, weight=strong]。
+示例说明 xref:常规标题[rel=illustrates, weight=strong]。
 ----
 
 `.example` 是 role。`owner=writing-team` 是标题附加字段。`weight=strong` 是 xref 边证据上的附加字段。
@@ -19,7 +19,7 @@
 
 [source,asciidoc]
 ----
-[#rule.example, status=active]
+[.example, status=active]
 == 示例规则
 
 priority:: normal
@@ -30,6 +30,43 @@ summary::
 示例规则正文从这里开始。
 ----
 
-`priority:: normal` 和 `summary::` 属于 `示例规则` 标题的附加字段。投影时它们成为标题字段，例如 `aat:priority` 和 `aat:summary`。
+`priority:: normal` 和 `summary::` 属于 `示例规则` 标题的附加字段。投影时它们成为标题字段，例如 `aat:priority` 和 `aat:summary`；`情况` 这样不是 ASCII 标识符的字段名投影为 `aat:field-` 加百分号编码。
+
+字段值需要附带代码块、表格或另一段正文时，用 `+` 把块挂到字段上。挂上来的块属于这个字段的值。
+
+[source,asciidoc]
+------
+[.rule, verdict=adapt]
+== 关闭标签
+
+情况:: 关闭当前标签。
+规则:: 先结束输入法的组字，再关闭。
+出处:: `editorCommands.ts:835-839`。
++
+[source,ts]
+----
+closeActiveEditor()
+----
+判定:: 改写。
+------
+
+`出处` 的值是出处那一行文字和挂上来的代码块。字段值按作者写下的原文保存：反引号、xref 和 include 指令都保留原样。
+
+没有 `+` 的块不属于字段。字段列表在那个块之前结束，块和它之后的内容都是标题的正文；块之后再写的描述列表也不再是字段。字段之间需要代码时，用 `+` 挂上，不要直接插入代码块。
+
+另有三种写法让整串描述列表都不算字段，标题一个字段也得不到：标题与描述列表之间有别的块（段落、提示块、代码块、图片等）；描述列表带 style（如 `[horizontal]`）、ID、块标题或其他块属性；某个条目里嵌套了描述列表。这时描述列表是标题的正文。反过来，要让标题正下方的描述列表是正文而不是字段，就在它前面放一段导语，或给它加 `[horizontal]` 等 style。
 
 字段名和字段值来自本书自己的约定。同一本书使用附加字段时，应保持字段写法和字段含义稳定。
+
+[source,asciidoc]
+----
+[.concept]
+== 宿舍集中备考者
+
+aliases::
+
+* 宿舍高强度备考者（旧称）
+* 宿舍备考学生（常用称呼）
+----
+
+`aliases` 记录其他名称；它不取代标题，也不作为隐藏的第二个规范名称。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-terminology/020-glossary.adoc

@@ -1,6 +1,6 @@
 [#glossary-conventions]
 == 术语表
 
-术语表记录本书采用的关键用词，并为它们给出稳定定义。role 标明标题身份，rel 标明引用关系。
+术语表记录本书采用的关键用词。规范名称、显式寻址标签、别名、role、rel 和附加字段分别指向不同对象。
 
-稳定术语帮助作者、读者和维护者使用同一组词理解源文档。术语的定义集中维护在书后的术语表中。
+role 说明标题节点在书中的作用；rel 说明引用边表达的关系。术语的定义集中维护在书后的术语表中。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-terminology/030-declaring-conventions.adoc

@@ -0,0 +1,70 @@
+[#declaring-conventions]
+== 声明本书的约定
+
+一本书采用的 role、rel、字段取值和字段构成它的约定。约定写在书里：读者从这里知道每个词的含义，检查脚本和查询工具从同一处读出受控词表。词表只写这一处，书和工具不会各说各的。
+
+声明约定的标题带 `.convention` role 和 `declares` 字段。声明的内容写成标题下的第一个连续描述列表：每个 term 是一个词，描述是这个词的含义。
+
+[source,asciidoc]
+----
+[.convention, declares=roles]
+=== 标题的 role
+
+concept:: 概念：本书使用的一个词及其含义。
+rule:: 规则：一条可检查的写法规定。
+example:: 示例：用一个具体场景说明抽象判断。
+convention:: 约定：声明本书的 role、rel、字段取值或字段。
+
+[.convention, declares=relations]
+=== 关系谓词
+
+depends-on:: 当前标题的判断、规则或操作以目标标题为依据。
+illustrates:: 当前标题提供目标标题的示例。
+----
+
+`declares` 的取值说明描述列表里的 term 是什么：
+
+[horizontal]
+roles:: role 名称。写作时用在 `[.concept]` 的位置。
+relations:: rel 谓词。写作时用在 `rel=depends-on` 的位置。
+values:: 某个 role 的某个附加字段允许的取值。`for` 写这个 role，`field` 写字段名。
+fields:: 某个 role 的标题下描述列表要写出的字段。`for` 写这个 role。这个 role 的标题带显式寻址标签、标签本身又是已有的技术地址时（例如规则的标签同时是测试的名字），可以再写 `id-prefix`，规定标签的开头，例如 `id-prefix=rule-`；一旦写了，这个 role 的每个标题都要写出以它开头的标签。
+
+字段取值和字段用同样的写法声明：
+
+[source,asciidoc]
+----
+[.convention, declares=values, for=rule, field=verdict]
+==== 规则的判定
+
+adopt:: 照搬：理由成立，形式也照搬。
+adapt:: 改写：理由成立，形式换成本项目更顺手的写法。
+skip:: 不搬：只服务于原来的处境。
+
+[.convention, declares=fields, for=rule]
+==== 规则的格式
+
+情况:: 在什么情况下。
+规则:: 发生什么。
+出处:: 依据的源文件与行号。
+----
+
+`规则的判定` 说明：带 `.rule` 的标题写 `verdict` 字段，取值是 `adopt`、`adapt` 或 `skip`。`规则的格式` 说明：带 `.rule` 的标题，标题下的描述列表写出 `情况`、`规则` 和 `出处`。xref:surface-fields[附加字段] 中的 `关闭标签` 就是一条符合这两项声明的规则；它多写的 `判定` 字段不在声明里，声明只规定必须写出的字段。
+
+声明的写法：
+
+* term 写词本身：写 `concept`，不写 `.concept`，也不加反引号。term 就是写作时使用的那个词。
+* 声明的描述列表紧跟在声明标题之下，与标题之间没有别的块（段落、提示块、图片等）；它不带 `[horizontal]` 等 style，也不带 ID、块标题或其他块属性，条目里不嵌套描述列表。违反任何一条，整串描述列表都是正文，声明标题读不出任何词。导语写在上一级标题里。
+* 一个声明标题只声明一种内容。同一个 role 的取值和字段分开声明。
+* `convention` 本身也写进 role 词表，因为声明标题使用这个 role。
+
+声明通常放在读者最先读到约定的地方，例如前言里的“本书的书写约定”一节；某个 role 的格式也可以放在最先使用这个 role 的部分。工具按 `.convention` role 找到声明，不依赖位置。
+
+检查脚本读出声明以后，对每个带 role 的标题核对，不论它写没写寻址标签：
+
+* role 在 role 词表中。
+* `declares=values` 声明的字段写了，取值在列表中。没有声明的附加字段（如 `owner`）不受约束；`.convention` 标题例外，它只带 `declares`、`for`、`field` 和 `id-prefix`。
+* `declares=fields` 声明的字段全部写出。
+* 声明了 `id-prefix` 时，标题写出寻址标签，标签以它开头。
+
+正文中的每个 xref，若带 `rel`，谓词在关系谓词词表中。约定变化时只改声明，检查跟着变。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-terminology/_partintro.adoc

@@ -1 +1 @@
-本部展示字段和术语表。字段随源文档保留；术语表帮助读者统一理解本书采用的用词。
+字段补充标题与引用已经表达的内容；术语表统一全书采用的名称；约定声明把本书的 role、rel 和字段写成工具可读的词表。

package/templates/default-workspace/catalog.adoc

@@ -46,7 +46,7 @@ v0.1, 2026-05
 
 |让源书稿保持可读，同时保留可被工具链读取的结构关系
 |xref:books/07-structured-writing-conventions/book.adoc[07 结构化书写约定标本]
-|它展示标题、稳定 ID、role、xref、rel 和附加字段如何形成结构化书稿表面。
+|它展示标题、引用、role、xref、rel 和附加字段如何形成结构化书稿表面。
 |===
 
 == 样本书
@@ -58,7 +58,7 @@ v0.1, 2026-05
 * xref:books/04-reference-manual/book.adoc[04 参考手册]：结构选择、路径规则和引用模式。
 * xref:books/05-upper-volume/book.adoc[05 上册]：独立分卷的上册。
 * xref:books/06-lower-volume/book.adoc[06 下册]：独立分卷的下册，并用示例说明跨卷引用写法。
-* xref:books/07-structured-writing-conventions/book.adoc[07 结构化书写约定标本]：标题、稳定 ID、role、xref、rel 和附加字段的结构化写法。
+* xref:books/07-structured-writing-conventions/book.adoc[07 结构化书写约定标本]：标题、引用、role、xref、rel 和附加字段的结构化写法。
 
 == 工作区地图
 

package/templates/solo-workspace/README.md

@@ -0,0 +1,24 @@
+# My Books
+
+An AsciiDoc multi-book workspace that starts with one book: `books/01-structured-writing-conventions`.
+
+## Commands
+
+```bash
+pnpm install
+pnpm run build   # writes build/html/index.html
+pnpm run check   # checks the catalog, books, xrefs, anchors, and local HTML resources
+pnpm run clean   # removes build/
+```
+
+To fetch diagram images into the local HTML output instead of linking Kroki URLs:
+
+```bash
+ADOC_BOOKS_FETCH_DIAGRAMS=1 pnpm run build
+```
+
+## Add A Book
+
+Copy `books/01-structured-writing-conventions` to `books/<NN-book-id>`, edit its `book.adoc`, then add an
+`xref:books/<NN-book-id>/book.adoc[...]` line to `catalog.adoc`.
+`pnpm run check` fails until `catalog.adoc` and `books/` list the same books.

package/templates/solo-workspace/catalog.adoc

@@ -0,0 +1,7 @@
+= AsciiDoc 书架
+:idprefix:
+:idseparator: -
+
+== 书目
+
+* xref:books/01-structured-writing-conventions/book.adoc[01 结构化书写约定标本]：标题、引用、role、xref、rel 和附加字段的结构化写法。

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

@@ -1,47 +0,0 @@
-[#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. 全书中手工声明的稳定地址至少需要一个 `xref` 消费。写法速查见 xref:structured-writing-quick-reference[附录 A：结构化写法速查]；完整判断流程见 xref:structured-writing-decision-trees[附录 B：结构化写法决策树]。
-2. 按照书籍结构，跨越 `= 书名`、`= 卷/部`、`== 章` 这些大跨度的指代均需要使用 `xref` 手动标注，平衡隐式上下文的阅读压力。
-====
-
-标题声明角色后，其下级标题默认属于同一角色范围。下级标题可声明不同角色以切换语境。
-
-例如:
-
-[source,asciidoc]
-----
-[.rule]
-== 引用规则
-
-=== 基本语法
-
-[.example]
-=== 一个完整示例
-----

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

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