create-asciidoc-multi-book-workspace 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +10 -0
- package/package.json +1 -1
- package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/appendix-a.adoc +1 -6
- package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/appendix-b-decision-trees.adoc +2 -16
- package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/glossary.adoc +0 -1
- package/templates/default-workspace/books/07-structured-writing-conventions/book.adoc +4 -7
- package/templates/default-workspace/books/07-structured-writing-conventions/parts/010-source-surface/030-source-order-notation.adoc +1 -1
- package/templates/default-workspace/books/07-structured-writing-conventions/parts/020-identity-and-relation/010-role-identity.adoc +1 -1
- package/templates/default-workspace/books/07-structured-writing-conventions/parts/020-identity-and-relation/020-relation-predicate.adoc +1 -1
- package/templates/default-workspace/books/07-structured-writing-conventions/parts/{030-fields-and-lookup → 030-fields-and-terminology}/010-surface-fields.adoc +1 -1
- package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-terminology/020-glossary.adoc +6 -0
- package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-terminology/_partintro.adoc +1 -0
- package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/index.adoc +0 -39
- package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-lookup/020-index-and-glossary.adoc +0 -14
- package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-lookup/_partintro.adoc +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.0 - 2026-07-26
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- Restructure the structured writing conventions sample around fields and terminology, including a dedicated glossary chapter and escaped xref syntax examples.
|
|
8
|
+
|
|
9
|
+
### Removed
|
|
10
|
+
|
|
11
|
+
- Retire the index-term tutorial, index section, and the associated generated sample paths from the structured writing conventions workspace.
|
|
12
|
+
|
|
3
13
|
## 0.2.1 - 2026-06-27
|
|
4
14
|
|
|
5
15
|
### Fixed
|
package/package.json
CHANGED
|
@@ -54,18 +54,13 @@
|
|
|
54
54
|
|`pass:[xref:stable-id[显示文本, rel=depends-on]]`
|
|
55
55
|
|显示为链接，同时声明 depends-on 关系。
|
|
56
56
|
|
|
57
|
-
|`indexterm2:[role]`
|
|
58
|
-
|正文可见索引词。
|
|
59
|
-
|
|
60
|
-
|`indexterm:[relation predicate]`
|
|
61
|
-
|正文隐藏索引词。
|
|
62
57
|
|===
|
|
63
58
|
|
|
64
59
|
全书标题需要保持 `标题层级连续`。
|
|
65
60
|
|
|
66
61
|
role 描述标题身份。rel 描述 xref 边上的关系谓词。附加字段可以写在标题 attrlist、标题下描述列表或 xref named attributes 中。
|
|
67
62
|
|
|
68
|
-
`[appendix]`、`[glossary]
|
|
63
|
+
`[appendix]`、`[glossary]` 和 `[bibliography]` 是 section style。它们改变紧随其后 section 的语义；标题层级仍由 `=` 数量决定。
|
|
69
64
|
|
|
70
65
|
对于跨文件的交叉引用，为了避免重复编写相对路径，你可以在文档的头部（Header）定义一个文档属性（Document Attribute）来存储这个基础路径。
|
|
71
66
|
|
|
@@ -19,9 +19,9 @@
|
|
|
19
19
|
├─ 是：使用更小一级标题将该区域独立划分，后续用 xref 指向该标题。流程结束。
|
|
20
20
|
└─ 否：评估 section style。
|
|
21
21
|
|
|
22
|
-
4.
|
|
22
|
+
4. 当前标题是否承载附录、术语表或参考文献等后置结构？
|
|
23
23
|
├─ 是：在等号标题上方声明对应 section style：
|
|
24
|
-
│ `[appendix]`、`[glossary]
|
|
24
|
+
│ `[appendix]`、`[glossary]` 或 `[bibliography]`。
|
|
25
25
|
│ section style 改变紧随其后 section 的语义；标题层级仍由 `=` 数量决定。
|
|
26
26
|
│ 流程结束。
|
|
27
27
|
└─ 否：写入标准等号标题。流程结束。
|
|
@@ -135,20 +135,6 @@
|
|
|
135
135
|
流程结束。
|
|
136
136
|
----
|
|
137
137
|
|
|
138
|
-
== index term 落位
|
|
139
|
-
|
|
140
|
-
触发场景:: 作者为读者检索和书后索引添加索引入口。
|
|
141
|
-
|
|
142
|
-
[source,text]
|
|
143
|
-
----
|
|
144
|
-
1. 索引目标词是否已经自然出现在当前正文句子中？
|
|
145
|
-
├─ 是：使用正文可见索引词宏 `indexterm2:[<primary>]` 包裹该词。
|
|
146
|
-
│ 正文保持可见，同时提取为一级索引项。流程结束。
|
|
147
|
-
└─ 否：使用正文隐藏索引词宏 `indexterm:[<primary>]`。
|
|
148
|
-
按需使用多级形式，例如 `indexterm:[<primary>, <secondary>]`。
|
|
149
|
-
隐藏索引词贴近相关段落内容，放在相关句子末尾。流程结束。
|
|
150
|
-
----
|
|
151
|
-
|
|
152
138
|
== 语法透传与 callouts
|
|
153
139
|
|
|
154
140
|
触发场景:: 作者书写代码、日志或工具语法文本。
|
|
@@ -49,14 +49,14 @@ include::parts/020-identity-and-relation/010-role-identity.adoc[]
|
|
|
49
49
|
|
|
50
50
|
include::parts/020-identity-and-relation/020-relation-predicate.adoc[]
|
|
51
51
|
|
|
52
|
-
=
|
|
52
|
+
= 字段与术语
|
|
53
53
|
|
|
54
54
|
[partintro]
|
|
55
|
-
include::parts/030-fields-and-
|
|
55
|
+
include::parts/030-fields-and-terminology/_partintro.adoc[]
|
|
56
56
|
|
|
57
|
-
include::parts/030-fields-and-
|
|
57
|
+
include::parts/030-fields-and-terminology/010-surface-fields.adoc[]
|
|
58
58
|
|
|
59
|
-
include::parts/030-fields-and-
|
|
59
|
+
include::parts/030-fields-and-terminology/020-glossary.adoc[]
|
|
60
60
|
|
|
61
61
|
[appendix]
|
|
62
62
|
include::backmatter/appendix-a.adoc[]
|
|
@@ -69,6 +69,3 @@ include::backmatter/glossary.adoc[]
|
|
|
69
69
|
|
|
70
70
|
[bibliography]
|
|
71
71
|
include::backmatter/bibliography.adoc[]
|
|
72
|
-
|
|
73
|
-
[index]
|
|
74
|
-
include::backmatter/index.adoc[]
|
|
@@ -12,7 +12,7 @@ role 写在标题 attrlist 的点号 token 位置。
|
|
|
12
12
|
== 引用规则
|
|
13
13
|
----
|
|
14
14
|
|
|
15
|
-
`#regular-heading` 和 `#xref-rule` 是稳定 ID
|
|
15
|
+
`#regular-heading` 和 `#xref-rule` 是稳定 ID，`.concept` 和 `.rule` 是 role，标明标题身份。
|
|
16
16
|
|
|
17
17
|
[cols="1,2", options="header"]
|
|
18
18
|
|===
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
[#relation-predicate]
|
|
2
2
|
== rel 关系谓词
|
|
3
3
|
|
|
4
|
-
|
|
4
|
+
`rel` 是 xref 边上的关系谓词。包含 xref 的标题是关系起点，xref 指向的标题是关系终点。本书把这两个位置称为 source heading 和 target heading。
|
|
5
5
|
|
|
6
6
|
[source,asciidoc]
|
|
7
7
|
----
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
|
|
16
16
|
`owner=writing-team` 写在标题 attrlist 中，投影时成为标题字段。`weight=strong` 写在 xref 中，投影时成为边证据字段。
|
|
17
17
|
|
|
18
|
-
标题字段较少且值较短时，写在标题 attrlist 中。标题字段较多，或字段值需要换行时，写在标题下的第一个连续描述列表中。
|
|
18
|
+
标题字段较少且值较短时，写在标题 attrlist 中。标题字段较多，或字段值需要换行时，写在标题下的第一个连续描述列表中。
|
|
19
19
|
|
|
20
20
|
[source,asciidoc]
|
|
21
21
|
----
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
本部展示字段和术语表。字段随源文档保留；术语表帮助读者统一理解本书采用的用词。
|
package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/index.adoc
DELETED
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
= 索引
|
|
2
|
-
|
|
3
|
-
索引 section 位于书籍后置区域。正文中的索引词宏是索引词来源。
|
|
4
|
-
|
|
5
|
-
AsciiDoc 区分正文可见索引词和正文隐藏索引词：
|
|
6
|
-
|
|
7
|
-
[cols="1,2", options="header"]
|
|
8
|
-
|===
|
|
9
|
-
|写法 |含义
|
|
10
|
-
|
|
11
|
-
|`indexterm2:[<primary>]`
|
|
12
|
-
|正文可见，同时作为一级索引项。
|
|
13
|
-
|
|
14
|
-
|`indexterm:[<primary>]`
|
|
15
|
-
|正文不可见，作为一级索引项。
|
|
16
|
-
|
|
17
|
-
|`indexterm:[<primary>, <secondary>]`
|
|
18
|
-
|正文不可见，作为二级索引项。
|
|
19
|
-
|
|
20
|
-
|`indexterm:[<primary>, <secondary>, <tertiary>]`
|
|
21
|
-
|正文不可见，作为三级索引项。
|
|
22
|
-
|===
|
|
23
|
-
|
|
24
|
-
正文中已经出现该词时，优先使用正文可见索引词。需要补充未出现在正文里的索引入口时，使用正文隐藏索引词。
|
|
25
|
-
|
|
26
|
-
隐藏索引词应贴近它标记的段落内容。本书把隐藏索引词放在相关句子末尾。
|
|
27
|
-
|
|
28
|
-
Asciidoctor 的内置 HTML5 转换器不会自动生成索引目录。`[index]` section 是 PDF 和 DocBook 工具链自动填充索引目录的种子位置；在本 HTML 样本中，它展示后置索引章节的位置和索引词写法。
|
|
29
|
-
|
|
30
|
-
本书正文中的索引词示例：
|
|
31
|
-
|
|
32
|
-
[source,asciidoc]
|
|
33
|
-
----
|
|
34
|
-
indexterm2:[role]
|
|
35
|
-
indexterm:[relation predicate]
|
|
36
|
-
indexterm:[源文件编排号]
|
|
37
|
-
indexterm:[中间值插入]
|
|
38
|
-
indexterm:[描述列表]
|
|
39
|
-
----
|
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
[#index-and-glossary]
|
|
2
|
-
== 索引词与术语表
|
|
3
|
-
|
|
4
|
-
索引词帮助读者在书后找到词。术语表解释本书采用的词。role 标明标题身份，rel 标明引用关系。
|
|
5
|
-
|
|
6
|
-
正文里已经自然出现该词时，使用可见索引词标记。需要补充未出现在正文里的索引入口时，使用隐藏索引词。
|
|
7
|
-
|
|
8
|
-
[source,asciidoc]
|
|
9
|
-
----
|
|
10
|
-
indexterm2:[role]
|
|
11
|
-
indexterm:[relation predicate]
|
|
12
|
-
----
|
|
13
|
-
|
|
14
|
-
稳定术语帮助作者、读者和维护者使用同一组词理解源文档。
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
本部展示字段、索引词和术语表。字段随源文档保留；索引词和术语表帮助读者找词、解词。
|