• AsciiDoc 用户指南

    AsciiDoc 用户指南

    1. ===================
    2. AsciiDoc 是一种文本文件书写格式,文章,手册,书籍和UNIX手册。AsciiDoc 文件可以 asciidoc(1) 命令转换成 HTML DocBook 标记。AsciiDoc 是一种先进的结构:AsciiDoc 语法和输出标记(几乎可以转换成任意的 SGML/XML 标记)都可以有用户自己定义和扩展。
    3. 简介
    4. ------------
    5. **********************************************************************
    6. 这是一个很大的文档,它可能需要做成一本手册,快速参考或正式资料。
    7. 如果你是一个 AsciiDoc 新手请阅读本节和 <<X6,起步>> 一节 或看看代码文件夹 `doc` 中的例子 AsciiDoc `.txt`
    8. **********************************************************************
    9. 纯文本是最通用的电子文档格式,无论你使用那种计算机环境都可以读写纯文本文件。不过纯文本不是使用最多的文档格式。HTML, PDF and roff (roff 用于手册页) 是使用最广泛的 UNIX 文档格式。 DocBook 是一种流行的 UNIX 文件标记格式,可转换为 HTMLPDF 和其他文稿格式。
    10. AsciiDoc 是一种人们方便读写的纯文本格式,可以使用 asciidoc(1) 转换成 DocBook HTML 。你可以使用 asciidoc(1) 直接生成 HTML 或运行 asciidoc(1) 通过你喜欢的 DocBook 工具链输出 DocBook ,使用 AsciiDoc a2x(1) 工具链输出产品 PDF, EPUB, DVI, LaTeX, PostScript, man page, HTML 和其他文本格式。
    11. AsciiDoc 格式本身的特性决定他的易用性:AsciiDoc 文件容易标记,方便查看、校对和编辑。
    12. AsciiDoc 是一个轻量级软件:只有一个 Python 脚本文件和一些配置文件。除了 asciidoc(1) 和一个 Python 程序,AsciiDoc 文件转换成 DocBook HTML 不需要其他的软件。看下面的 <<X11, AsciiDoc 文档例子>>
    13. 你可以像写普通文本文件一样写一个 AsciiDoc 文档,暂时没有标签和陌生的符号。AsciiDoc 语法规则已经尽量少并且易懂。
    14. 通用的文本标记可能你并不喜欢(经常遇到):如果默认的语法你不喜欢,你可以通过修改文本格式 asciidoc(1) 配置文件定义自己的语法。你可以通过创建自己的配置文件可以把 AsciiDoc 文档转换成任何 SGML/XML 标记。
    15. asciidoc(1) 根据配置文件的设置把 AsciiDoc 的文章,图书,手册页 转换成 HTML DocBook 格式。
    16. .我对 AsciiDoc 的期望
    17. **********************************************************************
    18. DocBook 已经成为开源文档事实上的标准格式。但是 DocBook 是一种复杂的语言,直接书写比较困难,写成的文本也难于阅读。-- 我发现自己花太多的时间写标签,查手册和修改语法错误,然后才能写内容。
    19. **********************************************************************
    20. [[X6]]
    21. 起步
    22. ---------------
    23. 安装 AsciiDoc
    24. ~~~~~~~~~~~~~~~~~~~
    25. 查看 `README` `INSTALL` 文件了解安装要求和步骤,打包格式查看 <<X38,附录 B: 打包说明>>。
    26. [[X11]]
    27. AsciiDoc 文档例子
    28. ~~~~~~~~~~~~~~~~~~~~~~~~~~
    29. 尽快感受 AsciiDoc 的方法是访问 AsciiDoc 网站或现有例子。
    30. - 看看 AsciiDoc 网站 http://www.methods.co.nz/asciidoc/ 首页的样例链接。点击左边菜单项目 'Page Source' 可以看到相应的 AsciiDoc 代码。
    31. - 阅读 `./doc` 文件夹中的 `.txt` 代码文件和相应的 HTML DocBook XML 文件。
    32. AsciiDoc 文档类型
    33. -----------------------
    34. AsciiDoc 文档有三种类型:article(文章), book(图书),和 manpage(手册页)。所有文件类型使用相同 AsciiDoc 格式除了少量细微的差别。
    35. 使用 asciidoc(1) `-d` (`--doctype`) 参数设置 AsciiDoc 文档类型 -- 默认文档类型是 'article(文章)'
    36. AsciiDoc 文档代码使用 `.txt` 文件扩展名。
    37. article(文章)
    38. ~~~~~~~~~~~~~
    39. 主要用于短文,文章和一般内容。参见 AsciiDoc 下载目录中 `./doc/article.txt` 例子
    40. book(图书)
    41. ~~~~~~~~~~
    42. 图书除了使用文章的格式,增加了级别为0的图书段落部分。
    43. 图书文档通常用于生产DocBook的输出,因为
    44. DocBook的处理器可以自动生成脚注,表格内容,表格的列表,数字清单,清单和例子和索引。
    45. AsciiDoc标记支持标准的DocBook文前内容和文后内容 <<X16,特殊段落>>(贡献,序言,书目,词汇,
    46. 索引,版权页)加脚注和索引项。
    47. .图书文档例子
    48. 图书::
    49. The `./doc/book.txt` file in the AsciiDoc distribution.
    50. 多部分图书::
    51. The `./doc/book-multi.txt` file in the AsciiDoc distribution.
    52. 手册页
    53. ~~~~~~~
    54. 用于生成 UNIX 手册页。 AsciiDoc 控制文档遵循专有的头标题和段落命名规则 -- 详情参见 <<X1,手册页文档>>
    55. 也可以AsciiDoc目录查看asciidoc(1)手册页代码 (`./doc/asciidoc.1.txt`)。
    56. [[X5]]
    57. AsciiDoc 输出
    58. -----------------
    59. asciidoc(1) 命令转换一个AsciiDoc格式文件到其他格式使用 `-b` (`--backend`) 命令行参数。asciidoc(1)本身内置了很少文件格式信息,所有转换规则包含在可定制的配置文件里面。输出专有单数列在了<<X88,附录 H>>。
    60. AsciiDoc 支持一下输出格式:
    61. docbook
    62. ~~~~~~~
    63. AsciiDoc可以生成一下DocBook文档格式:article, book refentry (对应 AsciiDoc 'article', 'book' 'manpage' 文档类型)
    64. DocBook文档不能直接预览。多数Linux发行版使用转换工具(一个工具集)见 <<X12,转换 DocBook 文件>> 转换到其他格式如 Postscript, HTML, PDF, DVI, PostScript, LaTeX, roff (原生联机手册格式), HTMLHelp, JavaHelp and text
    65. AsciiDoc <<X86,前言>> 部分转换成 DocBook book '前言' 部分虽然他通常是 'Preface' 独立段落 (参见 `./doc/book.txt` 图书样例)。
    66. [[X33]]
    67. xhtml11
    68. ~~~~~~~
    69. asciidoc(1) 默认输出为 `xhtml11` ,用于生成 XHTML 1.1 并使用 CSS2。默认输出文件使用 `.html` 扩展名。'xhtml11' 文档生成受以下参数影响(默认行为生成的 XHTML 没有段落编号,嵌入式CSS,也没有警告图标):
    70. [[X35]]
    71. 样式表
    72. ^^^^^^^^^^^
    73. AsciiDoc 输出 XHTML 使用的 CSS2 样式在安装目录中 `./stylesheets/` 文件夹里面。
    74. [重要]
    75. =====================================================================
    76. 所有浏览器都有 CSS 问题,但是微软的 IE6 有太多的漏洞和错误,`xhtml11-quirks.css` 样式和 `xhtml11-quirks.conf` 配置文件在处理的时候对 IE6 进行优化。如果你不使用 IE6 ,那么样式文件和配置文件可以使用 `--attribute quirks!` 命令行参数忽略。
    77. =====================================================================
    78. 默认 'xhtml11' 样式表:
    79. `./stylesheets/xhtml11.css`::
    80. 主样式表。
    81. `./stylesheets/xhtml11-manpage.css`::
    82. 用于手册页文档转换。
    83. `./stylesheets/xhtml11-quirks.css`::
    84. 调整 IE6 兼容性的样式表。
    85. 使用 'theme' 参数可以定义样式表。例如,命令行参数 `-a theme=foo` 会使用 `foo.css`, `foo-manpage.css` and `foo-quirks.css` 代替默认的样式表。
    86. 使用 'stylesheet' 参数可以在 XHTML 文档中包含一个附加样式表。例如,命令行参数 `-a
    87. stylesheet=newsletter.css` 会使用 `newsletter.css`
    88. html4
    89. ~~~~~
    90. 用于生成纯(无样式)的 HTML 4.01 转换标记
    91. 文档结构
    92. ------------------
    93. 一个 AsciiDoc 文档由一个 <<X8,基本区块>> 序列组成,由可选的文档头部开始,后面是可选的序言,再后面是0或多个文档段落。
    94. 几乎所有的零或多个基本结构组合起来都是有效的 AsciiDoc 文档:文档范围涵盖单个句子和多部分的图书。
    95. 基本区块
    96. ~~~~~~~~~~~~~~
    97. 基本区块由一行或多行文本,也可以包括其他的基本区块。
    98. AsciiDoc 区块概括如下[这是一个大概的结构指南,不是严格的语法定义]:
    99. 文档 ::= (头部?,前言?,章节*)
    100. 头部 ::= (标题,(作者,修订?)?)
    101. 作者 ::= (名字,(中间名?,姓氏)?,Email地址?)
    102. 修订 ::= (版本?,日期)
    103. 前言 ::= (段落)
    104. 章节 ::= (标题,段落?,(章节)*)
    105. 段落 ::= ((块标题?,块)|宏块)+
    106. ::= (自然段|独立块|列表|表格)
    107. 列表 ::= (无序列表|有序列表|定义列表|标注列表)
    108. 无序列表| ::= (项目)+
    109. 有序列表 ::= (项目)+
    110. 标注列表 ::= (项目)+
    111. 定义列表 ::= (条目)+
    112. 条目 ::= (标签,项目)
    113. 标签 ::= (项目+)
    114. 项目 ::= (项目文本,(列表|段落列表|列表后续)*)
    115. 注释:
    116. - '?' 表示01个, '+' 表示0或多个, '*' 表示1或多个.
    117. - 所有的基本块有独立的界线分开.
    118. - `BlockId`, `AttributeEntry` and `AttributeList` block elements (not
    119. shown) can occur almost anywhere.
    120. - There are a number of document type and backend specific
    121. restrictions imposed on the block syntax.
    122. - 下面的基本部分不能包含空行: 头部, 标题, 自然段, 项目文本.
    123. - 段落列表为有 '列表元素' 项目的段落.
    124. - 列表后续参见 <<X15,列表后续内容>>.
    125. 头部
    126. ~~~~~~
    127. 头部包含文档标题加上作者和版本信息。头部是可选的但是必须在文档的开始 <<X17,标题>>. 头部可以在注释和<<X18,属性项目>> 前面. 标题后面的作者和修订信息可选。头部可以包含在属性条目行。该文件标题是隔开的一个或多个空行从文档的其余部分. 下面是一个 AsciiDoc 文档头部的例子:
    128. 使用 AsciiDoc 编写文档
    129. ====================================
    130. Joe Bloggs <jbloggs@mymail.com>
    131. v2.0, February 2003:
    132. Rewritten for version 2 release.
    133. 作者行包括作者姓名和作者的Email地址。作者姓名包括名字和可选的使用空格隔开的中间名和姓氏。多个单词的名字,中间名,姓氏使用下划线链接。email必须使用尖括号<>包含。作者名称不能包含尖括号<>. 下面是一些作者行的例子:
    134. Joe Bloggs <jbloggs@mymail.com>
    135. Joe Bloggs
    136. Vincent Willem van_Gogh
    137. 修订行在作者后面可选。版本行可以使用下面的格式:
    138. . 文档修订版本号后跟可选的修订日期后跟可选的修订注释:
    139. * 制定了版本号后面必须跟一个逗号。
    140. * 版本号是一个以上的数字.
    141. * 版本号前面的非数字字符会被忽略掉.
    142. * 版本注释前面必须有冒号。版本注释从冒号到下一个空行或属性标志由普通文本替换
    143. * 版本号和注释设置后如果日期没有设置系统会使用 'docdate' 参数输出。
    144. . 使用 RCS/CSV/SVN $Id$ 标记 (如果使用 $Id$ 作为版本标记则作者行会被忽略).
    145. 下面是一些版本行的例子:
    146. v2.0, February 2003
    147. February 2003
    148. v2.0,
    149. v2.0, February 2003: Rewritten for version 2 release.
    150. February 2003: Rewritten for version 2 release.
    151. v2.0,: Rewritten for version 2 release.
    152. :Rewritten for version 2 release.
    153. 你可以使用asciidoc(1) `-a` (`--attribute`) 设置头部内容通过参数 'revnumber', 'revremark', 'revdate', 'email', 'author', 'authorinitials', 'firstname' and 'lastname' . 例子:
    154. $ asciidoc -a revdate=2004/07/27 article.txt
    155. 'revnumber' 参数可以使用 RCS/CSV/SVN $Id$ 标签.Attributes can also be added to the header for substitution in the header template with <<X18,Attribute Entry>> elements.
    156. [[X87]]
    157. 文档头部附加信息
    158. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    159. DocBook 定义了很多元素,例如:版权,文档历史和原作者信息。AsciiDoc 头部提供基本的修订和作者信息 -- 附加信息像版权信息和文档历史会作为可选包含从独立的包含 DocBook 项目 文档信息文件那些包含在 DocBook '文章信息' '图书信息' 项目:
    160. - 文档信息文件必须和文档再同一个目录下面,文件名称类似 `<docname>-docinfo.xml` 。例如,如果源文件为 `mydoc.txt` 那么文档信息文件应该为`mydoc-docinfo.xml`
    161. - 文档信息文件将被包含进 DocBook 输出,如果指定 `docinfo` 参数,例如:
    162. $ asciidoc -a docinfo -b docbook mydoc.txt
    163. 参见 AsciiDoc 文件夹中的 `./doc/article-docinfo.xml` 例子
    164. [[X86]]
    165. 前言
    166. ~~~~~~~~
    167. 前言是可选没有标题的段落,位于头部和第一章节之间。
    168. 章节
    169. ~~~~~~~~
    170. AsciiDoc 支持0-45个章节级别(虽然只有图书允许包含0级别的章节)。章节级别的说明见 <<X17,标题>>
    171. 章节使用配置文件转换标记模板。章节模板使用下列方式制定(按优先权重排序):
    172. 1. 通过设置名称的第一个位置属性或 'template' 属性的配置文件的模板的名称。以下三个章节标题功能相当:
    173. +
    174. .....................................................................
    175. [[terms]]
    176. [glossary]
    177. List of Terms
    178. -------------
    179. ["glossary",id="terms"]
    180. List of Terms
    181. -------------
    182. [template="glossary",id="terms"]
    183. List of Terms
    184. -------------
    185. .....................................................................
    186. 2. 标题符合配置文件中的 <<X16,specialsections>> (特殊章节) 部分.
    187. 3. 其他不属于上面的使用 `sect<level>` 模板名称的。
    188. 使用 `-n` (`--section-numbers`) 命令行参数设置 HTML 输出的自动编号 (DocBook 行号由 DocBook toolchain 命令自动生成)
    189. 章节编号根据章节标题自动生成如果应用 `sectids` 参数(默认设置)。这个特征主要是为了保证内容链接表的效果:错误的章节编号被 JavaScript TOC 脚本动态生成的 *after* 页面载入,例如,如果你访问的标签是动态生成的 TOC 地址并载入了页面但是浏览器会忽略(因为没有生成) 章节编号。
    190. 章节编号按照下面的算法生成:
    191. - 为所有非字母数字加上下划线。
    192. - Strip leading or trailing underscores.
    193. - 转换成小写字母。
    194. - 预设 `idprefix` 参数(所以没有与现有文件的ID名称冲突的可能性)。如果 `idprefix `属性没有定义会加上一个下划线
    195. - 如果自动生成的章节编号存在则在名称后添加编号后缀(`_2``_3`...)。
    196. 例如标题 'Jim's House' 将生成编号为 `_jim_s_house`。
    197. [[X16]]
    198. 特殊章节
    199. ^^^^^^^^^^^^^^^^
    200. 附加 DocBook 正文前和正文后的章节到正常章节 -- 例如:前言,参考书目,目录,索引。
    201. AsciiDoc 配置文件中有 `[specialsections]` 部分;他们会映射具体的章节到标记模板。格式如下:
    202. <title>=<template>
    203. `<title>` 是Python规则 `<template>` 是配置文件标记模板章节名称。如果 `<title>` 是一个 AsciiDoc 文档的章节标题则输出使用 `<template>` 标记模板(替代默认的 `sect<level>` 章节模板)。如果 'title' 组合 `{title}` 默认的 AsciiDoc 章节标题, `{title}` 参数设置为符合 'title' 规则的组合。如果 `<template>` 为空则所有符合 `<title>` 的标题被删除。
    204. AsciiDoc 使用下面的特殊章节标题进行重构:
    205. 前言 (图书专用)
    206. 摘要 (文章专用)
    207. 贡献者 (图书专用)
    208. 术语表
    209. 参考文献|参考书目
    210. 版权标志 (图书专用)
    211. 索引
    212. 附录 [A-Z][:.] <title>
    213. 内置元素
    214. ~~~~~~~~~~~~~~~
    215. <<X34,内置文档元素>> 用来标记字符的格式和不同类型的替换。内置项目和内置项目语法在 asciidoc(1) 配置文件中定义。
    216. 这里是 AsciiDoc 内置元素处理命令列表:
    217. 特殊字符::
    218. 这些字符转义特殊字符使用后端标记(一般是 "<", ">", 和 "&"),
    219. 参阅配置文件 `[specialcharacters]` 部分
    220. 引用::
    221. 标记单词和短语的字符,通常是字符格式。参阅配置文件的 `[quotes]` 部分。
    222. 专用词语::
    223. 词或短语根据标签选出不用进一步注释。参阅配置文件 `[specialwords]` 部分。
    224. 替换::
    225. 每替换定义一个字或词短语的模式去搜索相应的替换文本。参阅配置文件 `[replacements]` 部分
    226. 参数::
    227. 使用相应的参数值替换大括号封闭(属性引用)的文档参数名称。
    228. 内置宏::
    229. 内置宏被替换使用配置文件中设置的内容。
    230. 文档处理
    231. -------------------
    232. AsciiDoc 代码文档像下面读取和处理:
    233. 1. 分析文档头部,使用头部参数替换配置文件中 `[header]` 模板部分等待输出。
    234. 2. 分析文档所有 '章节' 和组成元素转换后等待输出。
    235. 3. 替换配置文件 `[footer]` 部分并且写入输出文件
    236. asciidoc(1) 安装下面顺序确定块类型(从先到后):(章节),标题,宏,列表,分割块,表格,属性项,属性列表,块标题,段落。
    237. 默认段落定义 `[paradef-default]` 最后检查。
    238. 知道分析顺序可以帮助你设计明确的宏,列表,块的样式规则。
    239. 内置替换再块内按下面顺序执行。
    240. 1. 特殊字符
    241. 2. 引用
    242. 3. 特殊词
    243. 4. 替换
    244. 5. 属性
    245. 6. 内置宏
    246. 7. 替换
    247. 替换或替换顺序在执行于标题,段落和分割块的时候由配置文件参数决定。
    248. 格式化文本
    249. ---------------
    250. [[X51]]
    251. 文本描述
    252. ~~~~~~~~~~~
    253. 使用描述字符封闭的词语和句子会被格式化:
    254. _强调_::
    255. 使用 \'单引号' \_下划线_ 封闭的词句表示强调。
    256. *粗体*::
    257. 使用 \*星号* 封闭的词句表示粗体。
    258. [[X81]]+等宽字体+::
    259. 短语 \+使用加号封闭的字符+ 显示为等宽字体。 \`使用重音符号封闭的字符`(重音符号)也会
    260. 显示为等宽字符,但是这种情况下,封闭的文本显示不受进一步定义 (参阅 <<X80,内置文字>>)。
    261. `单引号引用'::
    262. 使用 \`一个重音符号(译注:不是单引号,一般在键盘的左上部)到一个单引号之间' 的字句
    263. 表示单引号引用。
    264. ``双引号引用''::
    265. 使用 \\``两个重音符号(译注:不是单引号,一般在键盘的左上部)到两个单引号之间'' 的字句
    266. 表示双引号引用。
    267. #无引用文本#::
    268. \#井号包围的文本# 没有效果,这是一种允许应用内置属性到其他无格式文本的机制(见下例)
    269. 引用文字的前缀可以是 <<X21,属性列表>>。目前只适用于指定字体颜色,背景颜色和大小(只用于XHTML/HTML,不能用于 DocBook)使用的前三个位置的属性参数。第一个参数是文本的颜色,第二个背景颜色;第三是字体的大小。颜色是有效的CSS颜色和字体的大小是数字以em为单位。下面是一些例子:
    270. 引用文本会被加上前缀使用 <<X21,属性列表>>。
    271. ---------------------------------------------------------------------
    272. [red]#红色文本#.
    273. [,yellow]*加粗文本黄色背景*.
    274. [blue,#b0e0e6]+等宽的蓝色文本浅蓝色背景+
    275. [,,2]#2倍大小文本#.
    276. ---------------------------------------------------------------------
    277. 新的引用可以通过修改配置文件定义。参阅 <<X7,配置文件>> 相关部分。
    278. .引用文本文件
    279. - 引用不能交叉。
    280. - 不同类型的引用可以嵌套
    281. - 为了防止使用引用格式,可以在引号前面放一个反斜杠。不清楚是否引用你需要在前后都添加转义符,
    282. 多字符引用你需要转义单个字符。
    283. - 配置文件 `[quotes]` 部分可以是设置为空。
    284. [[X52]]
    285. 限制引用和非限制引用
    286. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    287. 这是引用的两种类型:
    288. 限制引用
    289. ++++++++++++++++++
    290. 引用的文字,必须由空格或常用毗邻标点符号分割。这些是最常用的引用类型。
    291. 非限制引用
    292. ++++++++++++++++++++
    293. 非限制引用没有边界的限制,可放置在任何地方内置文本。为了保持一致,并使其更容易记住非限制引用是双重的`_``*``+'和``限制引用
    294. __非限制强调文本__
    295. **非限制加粗文本**
    296. ++非限制等宽文本++
    297. ##非限制加引号的文本##
    298. 下面例子加粗字母F:
    299. **F**ile Open...
    300. 上标和下标
    301. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    302. \^中间的字符^ 为上标, \~中间的字符~ 为下标. 例如:
    303. e^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
    304. and ~some sub text~
    305. 效果:
    306. e^&#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
    307. and ~some sub text~
    308. 上边和下标执行 <<X52,非限制引用>> 所以可以使用反斜杠转义和使用属性列表。
    309. 换行
    310. ~~~~~~~~~~~
    311. 加号后面跟一个空格为强制换行。转换到 HTML 后为换行标签 (`br`) ,转换到 DocBook 时为自定义的 XML `asciidoc-br` 处理命令。 `asciidoc-br` 处理命令参阅 <<X43,a2x(1)>>。
    312. 分页
    313. ~~~~~~~~~~~
    314. 一行只有三个或更多小于号 (`<<<`) 将会生成硬换页在输出到 DocBook 和 打印格式的 HTML,使用 CSS `page-break-after` 属性用于 HTML 输出和自定义的 XML 处理指令 `asciidoc-pagebreak` 用于 DocBook输出。`asciidoc-pagebreak` 处理指令参见 <<X43,a2x(1)>> 。硬分页符有时方便,但作为一般规则,你应该让你的网页处理器,为您产生分页符。
    315. 分割行
    316. ~~~~~~
    317. 一行只有三个或更多省略号将会生成一个分割行。输出 HTML 时生成分割线 (`hr`) 标签,输出 DocBook 时生成 `asciidoc-hr` 的 XML 处理指令,`asciidoc-hr` 指令参阅 <<X43,a2x(1)>> 。
    318. 制表符
    319. ~~~~~
    320. 默认情况下输入制表符的文件将转换为8位。 Tab扩展与'tabsize'的配置项文件中设置 `[miscellaneous]` 部分,可在覆盖包括通过设置 `include` 包括宏的属性列表 'tabsize' 属性的文件。例如:
    321. include::addendum.txt[tabsize=2]
    322. 该选项卡的大小也可以使用属性设置命令行选项,
    323. 例如 `--attribute tabsize=4`
    324. 替换
    325. ~~~~~~~~~~~~
    326. AsciiDoc 默认定义了下列替换:
    327. (C) 版权, (TM) 商标, (R) 注册商标, -- 破折号, ... 省略号, -> 右箭头, <- 左箭头, => 右双箭头, <= 左双箭头.
    328. 效果如下:
    329. (C) 版权, (TM) 商标, (R) 注册商标, -- 破折号, ... 省略号, -> 右箭头, <- 左箭头, => 右双箭头, <= 左双箭头.
    330. 你可以包含任何内码引用于 AsciiDoc 代码中。例如:
    331. &#x278a; &#182;
    332. 效果:
    333. &#x278a; &#182;
    334. To render a replacement literally escape it with a leading back-slash.
    335. <<X7,配置文件>> 段落说明了如何配置你自己替换项目.
    336. 特殊词语
    337. ~~~~~~~~~~~~~
    338. 词语在配置文件中 `[specialwords]` 部分定义会自动标记,而不必到明确标记。
    339. <<X7,配置文件>> 说明如何添加和替换特殊词语。
    340. [[X17]]
    341. 标题
    342. ------
    343. 文档和段落标题会使用下面两种格式中的一种:
    344. 双行标题
    345. ~~~~~~~~~~~~~~~
    346. 双行标题由一个标题行,一个硬回车和一个下划线组成。下划线由重复字符组成和上面标题等宽:
    347. 不同级别的标题默认的下划线如下:
    348. 0级 (顶级): ======================
    349. 1级: ----------------------
    350. 2级: ~~~~~~~~~~~~~~~~~~~~~~
    351. 3级: ^^^^^^^^^^^^^^^^^^^^^^
    352. 4级 (最低级): ++++++++++++++++++++++
    353. 样例:
    354. 一级段落标题
    355. -----------
    356. 二级子段落标题
    357. ~~~~~~~~~~~~
    358. [[X46]]
    359. 单行标题
    360. ~~~~~~~~~~~~~~~
    361. 单行标题由等号封闭的文字构成(等号的个数表示段落级别)。下面是一些样例:
    362. = Document Title (level 0) =
    363. == Section title (level 1) ==
    364. === Section title (level 2) ===
    365. ==== Section title (level 3) ====
    366. ===== Section title (level 4) =====
    367. = 文档标题 (0级) =
    368. == 段落标题 (1级) ==
    369. === 段落标题 (2级) ===
    370. ==== 段落标题 (3级) ====
    371. ===== 段落标题 (4级) =====
    372. .注意
    373. - 标题和标记之间必须有一个或多个空格.
    374. - 标题的界定符是可选的.
    375. - 改变单行标题语法可以编辑 configuration 文件 `[titles]` section `sect0`...`sect4` 项.
    376. 浮动标题
    377. ~~~~~~~~~~~~~~~
    378. 设置标题的首位属性或 'style' 属性为 'float' 可以实现自由浮动标题。自由浮动标题看上去像普通标题,但是没有普通的文本结构,没有普通段落的层次,不使用普通的规则。浮动标题可以在上下文使用特殊的标题:例如侧边栏和警告框。样例:
    379. [float]
    380. 第二天
    381. ~~~~~~~~~~~~~~
    382. [[X42]]
    383. 块标题
    384. ------------
    385. '块标题' 元素是一个句点开始的文本行。块标题应用到紧跟在后面的段落,列表,表格或区块。例如:
    386. ........................
    387. .Notes
    388. - Note 1.
    389. - Note 2.
    390. ........................
    391. 显示效果:
    392. .Notes
    393. - Note 1.
    394. - Note 2.
    395. [[X41]]
    396. 块标志元素
    397. ---------------
    398. A 'BlockId' is a single line block element containing a unique
    399. identifier enclosed in double square brackets. It is used to assign an
    400. identifier to the ensuing block element for use by referring links.
    401. For example:
    402. [[chapter-titles]]
    403. Chapter titles can be ...
    404. The preceding example identifies the following paragraph so it can be
    405. linked from other location, for example with
    406. `<<chapter-titles,chapter titles>>`.
    407. 'BlockId' elements can be applied to Title, Paragraph, List,
    408. DelimitedBlock, Table and BlockMacro elements. The BlockId element
    409. sets the `{id}` attribute for substitution in the subsequent block's
    410. markup template. If a second argument is supplied it sets the
    411. `{reftext}` attribute which is used to set the DocBook `xreflabel`
    412. attribute.
    413. The 'BlockId' element has the same syntax and serves a similar
    414. function to the <<X30,anchor inline macro>>.
    415. [[X79]]
    416. 属性列表元素
    417. ---------------------
    418. An 'AttributeList' block element is an <<X21,attribute list>> on a
    419. line by itself. 'AttributeList' attributes are only applied to the
    420. following block element -- the attributes are available for markup
    421. template substitution. Often the first attribute in the list is used
    422. to specify the following element's <<X23,style>>.
    423. By default only attribute references are substituted within attribute
    424. values, this is because not all attributes are destined to be marked
    425. up and rendered as text (for example the table 'cols' attribute). To
    426. perform normal inline text substitutions (special characters, quotes,
    427. macros, replacements) on an attribute value you need to enclose it in
    428. single quotes. In the following quote block the second attribute value
    429. in the AttributeList is quoted to ensure the 'http' macro is expanded
    430. to a hyperlink.
    431. ---------------------------------------------------------------------
    432. [quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']
    433. _____________________________________________________________________
    434. Sir, a woman's preaching is like a dog's walking on his hind legs. It
    435. is not done well; but you are surprised to find it done at all.
    436. _____________________________________________________________________
    437. ---------------------------------------------------------------------
    438. 公共属性
    439. ~~~~~~~~~~~~~~~~~
    440. 大多数的文本块支持下列属性:
    441. [cols="1e,1,5a",frame="topbot",options="header"]
    442. |====================================================================
    443. |Name |Backends |Description
    444. |id |html4, xhtml11, docbook |
    445. Unique identifier typically serve as link targets.
    446. Can also be set by the 'BlockId' element.
    447. |role |docbook |
    448. Role contains a string used to classify or subclassify an element.
    449. Used to add the 'role' attribute to DocBook block elements.
    450. |reftext |docbook |
    451. 'reftext' is used to set the DocBook 'xreflabel' attribute.
    452. Can also be set by the 'BlockId' element.
    453. |====================================================================
    454. [cols="1e,1,5a",frame="topbot",options="header"]
    455. |====================================================================
    456. |名称 |Backends |说明
    457. |id |html4, xhtml11, docbook |
    458. 唯一标识符通常作为链接目标。也可以由 'BlockId' 元素设置。
    459. |role |docbook |
    460. Role 包含可用于分类或子类元素一个字符串。用于添加 'role' 属性到 DocBook 的块元素。
    461. |reftext |docbook |
    462. 'reftext'是用来设置DocBook的'xreflabel'属性。也可以由 'BlockId' 元素设置。
    463. |====================================================================
    464. 段落
    465. ----------
    466. Paragraphs are blocks of text terminated by a blank line, the end of
    467. file, or the start of a DelimitedBlock. Paragraph markup is specified
    468. by configuration file `[paradef*]` sections.
    469. Normal paragraphs consist of one or more non-blank lines of text. The
    470. first line must start hard against the left margin (no intervening
    471. white space). The default processing expectation is that of a normal
    472. paragraph of text. 'literal' and 'verse' paragraph styles are
    473. available (in addition to the 'default' paragraph style).
    474. [[X85]]
    475. 文字段落样式
    476. ~~~~~~~~~~~~~~~~~~~~~~~~
    477. Literal paragraphs are rendered verbatim in a monospaced font without
    478. any distinguishing background or border. By default there is no text
    479. formatting or substitutions within Literal paragraphs apart from
    480. Special Characters and Callouts. For example:
    481. ---------------------------------------------------------------------
    482. [literal]
    483. Consul *necessitatibus* per id,
    484. consetetur, eu pro everti postulant
    485. homero verear ea mea, qui.
    486. ---------------------------------------------------------------------
    487. 效果:
    488. [literal]
    489. Consul *necessitatibus* per id,
    490. consetetur, eu pro everti postulant
    491. homero verear ea mea, qui.
    492. verse paragraph style
    493. ~~~~~~~~~~~~~~~~~~~~~
    494. The 'verse' paragraph <<X23,style>> preserves line boundaries and is
    495. useful for lyrics and poems. For example:
    496. ---------------------------------------------------------------------
    497. [verse]
    498. Consul *necessitatibus* per id,
    499. consetetur, eu pro everti postulant
    500. homero verear ea mea, qui.
    501. ---------------------------------------------------------------------
    502. 效果:
    503. [verse]
    504. Consul *necessitatibus* per id,
    505. consetetur, eu pro everti postulant
    506. homero verear ea mea, qui.
    507. 段落缩进
    508. ~~~~~~~~~~~~~~~~~~~
    509. Indented paragraphs (the first line indented by one or more space or
    510. tab characters) are rendered using the <<X85,literal paragraph
    511. style>>. For example:
    512. ---------------------------------------------------------------------
    513. Consul *necessitatibus* per id,
    514. consetetur, eu pro everti postulant
    515. homero verear ea mea, qui.
    516. ---------------------------------------------------------------------
    517. 效果:
    518. Consul *necessitatibus* per id,
    519. consetetur, eu pro everti postulant
    520. homero verear ea mea, qui.
    521. NOTE: Because <<X64,lists>> can be indented it's possible for your
    522. indented paragraph to be misinterpreted as a list -- in situations
    523. like this apply the 'literal' style to a normal paragraph.

    [[X28]]
    提醒段落

    1. ~~~~~~~~~~~~~~~~~~~~~
    2. 'Tip', 'Note', 'Important', 'Warning' and 'Caution' paragraph
    3. definitions support the corresponding DocBook admonishment elements --
    4. just write a normal paragraph but place `NOTE:`, `TIP:`, `IMPORTANT:`,
    5. `WARNING:` or `CAUTION:` as the first word of the paragraph. For
    6. example:
    7. NOTE: This is an example note.
    8. or the alternative syntax:
    9. [NOTE]
    10. This is an example note.
    11. Renders:
    12. NOTE: This is an example note.
    13. TIP: If your admonition is more than a single paragraph use an
    14. <<X22,admonition block>> instead.
    15. [[X47]]
    16. 提醒图标和标题
    17. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    18. NOTE: 定制警告图标 `icons`, `iconsdir`, `icon` `caption` 属性不能用于生成 DocBook。如果你确定使用 DocBook <<X43,a2x(1)>> `--no-icons` `--icons-dir` 选项可以用于设置适当的XSL样式表参数。
    19. By default the asciidoc(1) `xhtml11` and `html4` backends generate
    20. text captions instead of icon image links. To generate links to icon
    21. images define the <<X45,`icons`>> attribute, for example using the `-a
    22. icons` command-line option.
    23. The <<X44,`iconsdir`>> attribute sets the location of linked icon
    24. images.
    25. You can override the default icon image using the `icon` attribute to
    26. specify the path of the linked image. For example:
    27. [icon="./images/icons/wink.png"]
    28. NOTE: What lovely war.
    29. Use the `caption` attribute to customize the admonition captions (not
    30. applicable to `docbook` backend). The following example suppresses the
    31. icon image and customizes the caption of a NOTE admonition (undefining
    32. the `icons` attribute with `icons=None` is only necessary if
    33. <<X45,admonition icons>> have been enabled):
    34. [icons=None, caption="My Special Note"]
    35. NOTE: This is my special note.
    36. This subsection also applies to <<X22,Admonition Blocks>>.
    37. 分隔的块
    38. ----------------
    39. Delimited blocks are blocks of text enveloped by leading and trailing
    40. delimiter lines (normally a series of four or more repeated
    41. characters). The behavior of Delimited Blocks is specified by entries
    42. in configuration file `[blockdef*]` sections.
    43. 预定义的分隔块
    44. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    45. AsciiDoc ships with a number of predefined DelimitedBlocks (see the
    46. `asciidoc.conf` configuration file in the asciidoc(1) program
    47. directory):
    48. Predefined delimited block underlines:
    49. CommentBlock: //////////////////////////
    50. PassthroughBlock: ++++++++++++++++++++++++++
    51. ListingBlock: --------------------------
    52. LiteralBlock: ..........................
    53. SidebarBlock: **************************
    54. QuoteBlock: __________________________
    55. ExampleBlock: ==========================
    56. OpenBlock: --
    57. The <<X56,code>>, <<X57,source>> and <<X58,music>> filter blocks are
    58. detailed in the <<X59,Filters>> section.
    59. <<X56,代码>>, <<X57,来源>> <<X58,音乐>> 过滤器块在 <<X59,过滤器>> 段落有详细介绍。
    60. .Default DelimitedBlock substitutions
    61. [cols="2e,7*^",frame="topbot",options="header,autowidth"]
    62. |=====================================================
    63. | |Attributes |Callouts |Macros | Quotes |Replacements
    64. |Special chars |Special words
    65. |PassthroughBlock |Yes |No |Yes |No |No |No |No
    66. |ListingBlock |No |Yes |No |No |No |Yes |No
    67. |LiteralBlock |No |Yes |No |No |No |Yes |No
    68. |SidebarBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
    69. |QuoteBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
    70. |ExampleBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
    71. |OpenBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
    72. |=====================================================
    73. 清单块
    74. ~~~~~~~~~~~~~~
    75. 'ListingBlocks' are rendered verbatim in a monospaced font, they
    76. retain line and whitespace formatting and are often distinguished by a
    77. background or border. There is no text formatting or substitutions
    78. within Listing blocks apart from Special Characters and Callouts.
    79. Listing blocks are often used for computer output and file listings.
    80. Here's an example:
    81. [listing]
    82. ......................................
    83. --------------------------------------
    84. #include <stdio.h>
    85. int main() {
    86. printf("Hello World!\n");
    87. exit(0);
    88. }
    89. --------------------------------------
    90. ......................................
    91. Which will be rendered like:
    92. --------------------------------------
    93. #include <stdio.h>
    94. int main() {
    95. printf("Hello World!\n");
    96. exit(0);
    97. }
    98. --------------------------------------
    99. By convention <<X59,filter blocks>> use the listing block syntax and
    100. are implemented as listing block styles.
    101. [[X65]]
    102. 文字块
    103. ~~~~~~~~~~~~~~
    104. '文字块' 就像文字段落,只是不用内容缩进.
    105. 如果文字块应用了 'listing' 样式就会表现为一个清单块 (这样方便了你使用一个列表包含一个清单块).
    106. ---------------------------------------------------------------------
    107. ...................................
    108. Consul *necessitatibus* per id,
    109. consetetur, eu pro everti postulant
    110. homero verear ea mea, qui.
    111. ...................................
    112. ---------------------------------------------------------------------
    113. 效果:
    114. ...................................
    115. Consul *necessitatibus* per id,
    116. consetetur, eu pro everti postulant
    117. homero verear ea mea, qui.
    118. ...................................
    119. 侧边栏
    120. ~~~~~~~~~~~~~~
    121. 侧边栏是一小段推荐的文字漂浮于主文本的外侧。侧边栏由一个边框包围着独立于主文本。
    122. 侧边栏内容就像正常的段落
    123. 下面是例子:
    124. ---------------------------------------------------------------------
    125. .侧边栏例子
    126. ************************************************
    127. Any AsciiDoc SectionBody element (apart from
    128. SidebarBlocks) can be placed inside a sidebar.
    129. ************************************************
    130. ---------------------------------------------------------------------
    131. 效果如下:
    132. .侧边栏例子
    133. ************************************************
    134. Any AsciiDoc SectionBody element (apart from
    135. SidebarBlocks) can be placed inside a sidebar.
    136. ************************************************
    137. 应用 'abstract' 样式转换摘要,例如:
    138. ---------------------------------------------------------------------
    139. [abstract]
    140. ************************************************
    141. In this paper we will attempt to...
    142. ************************************************
    143. ---------------------------------------------------------------------
    144. [[X26]]
    145. 注释块
    146. ~~~~~~~~~~~~~~
    147. The contents of CommentBlocks are not processed; they are useful for
    148. annotations and for excluding new or outdated content that you don't
    149. want displayed. CommentBlocks are never written to output files.
    150. Example:
    151. ---------------------------------------------------------------------
    152. //////////////////////////////////////////
    153. CommentBlock contents are not processed by
    154. asciidoc(1).
    155. //////////////////////////////////////////
    156. ---------------------------------------------------------------------
    157. 参见 <<X25,行注释>>。
    158. NOTE: System macros are executed inside comment blocks.
    159. [[X76]]
    160. Passthrough Blocks
    161. ~~~~~~~~~~~~~~~~~~
    162. By default the block contents is subject to attribute and macro
    163. substitution, no other markup is generated. PassthroughBlock content
    164. will often be backend specific. Here's an example:
    165. ---------------------------------------------------------------------
    166. ++++++++++++++++++++++++++++++++++++++
    167. <table border="1"><tr>
    168. <td>Cell 1</td>
    169. <td>Cell 2</td>
    170. </tr></table>
    171. ++++++++++++++++++++++++++++++++++++++
    172. ---------------------------------------------------------------------
    173. Use and explicit 'subs' attribute to control substitution. The
    174. following styles can be applied to passthrough blocks:
    175. pass::
    176. By default no substitutions are performed.
    177. asciimath, latexmath::
    178. By default no substitutions are performed, the contents are rendered
    179. as <<X78,mathematical formulas>>.
    180. 引用块
    181. ~~~~~~~~~~~~
    182. 'QuoteBlocks' are used for quoted passages of text. There are two
    183. styles: 'quote' and 'verse'. The style is set by the first positional
    184. attribute, if no style attribute is specified the 'quote' style. The
    185. optional 'attribution' and 'citetitle' attributes (positional
    186. attributes 2 and 3) specify the quote's author and source.
    187. The 'quote' style treats the content like a SectionBody, for example:
    188. ---------------------------------------------------------------------
    189. [quote, Bertrand Russell, The World of Mathematics (1956)]
    190. ____________________________________________________________________
    191. A good notation has subtlety and suggestiveness which at times makes
    192. it almost seem like a live teacher.
    193. ____________________________________________________________________
    194. ---------------------------------------------------------------------
    195. Which is rendered as:
    196. [quote, Bertrand Russell, The World of Mathematics (1956)]
    197. ____________________________________________________________________
    198. A good notation has subtlety and suggestiveness which at times makes
    199. it almost seem like a live teacher.
    200. ____________________________________________________________________
    201. The 'verse' style
    202. retains the content's line breaks, for example:
    203. ---------------------------------------------------------------------
    204. [verse, William Blake, from Auguries of Innocence]
    205. __________________________________________________
    206. To see a world in a grain of sand,
    207. And a heaven in a wild flower,
    208. Hold infinity in the palm of your hand,
    209. And eternity in an hour.
    210. __________________________________________________
    211. ---------------------------------------------------------------------
    212. Which is rendered as:
    213. [verse, William Blake, from Auguries of Innocence]
    214. __________________________________________________
    215. To see a world in a grain of sand,
    216. And a heaven in a wild flower,
    217. Hold infinity in the palm of your hand,
    218. And eternity in an hour.
    219. __________________________________________________
    220. [[X48]]
    221. 样例块
    222. ~~~~~~~~~~~~~~
    223. 'ExampleBlocks' encapsulate the DocBook Example element and are used
    224. for, well, examples. Example blocks can be titled by preceding them
    225. with a 'BlockTitle'. DocBook toolchains normally number examples and
    226. generate a 'List of Examples' backmatter section.
    227. Example blocks are delimited by lines of equals characters and you can
    228. put any block elements apart from Titles, BlockTitles and Sidebars)
    229. inside an example block. For example:
    230. ---------------------------------------------------------------------
    231. .An example
    232. =====================================================================
    233. Qui in magna commodo, est labitur dolorum an. Est ne magna primis
    234. adolescens.
    235. =====================================================================
    236. ---------------------------------------------------------------------
    237. Renders:
    238. .An example
    239. =====================================================================
    240. Qui in magna commodo, est labitur dolorum an. Est ne magna primis
    241. adolescens.
    242. =====================================================================
    243. A title prefix that can be inserted with the `caption` attribute
    244. (`xhtml11` and `html4` backends). For example:
    245. ---------------------------------------------------------------------
    246. [caption="Example 1: "]
    247. .An example with a custom caption
    248. =====================================================================
    249. Qui in magna commodo, est labitur dolorum an. Est ne magna primis
    250. adolescens.
    251. =====================================================================
    252. ---------------------------------------------------------------------
    253. [[X22]]
    254. 警告块
    255. ~~~~~~~~~~~~~~~~~
    256. The 'ExampleBlock' definition includes a set of admonition
    257. <<X23,styles>> (NOTE, TIP, IMPORTANT, WARNING, CAUTION) for generating
    258. admonition blocks (admonitions containing more than just a
    259. <<X28,simple paragraph>>). Just precede the ExampleBlock with an
    260. attribute list containing the admonition style name. For example:
    261. ---------------------------------------------------------------------
    262. [NOTE]
    263. .A NOTE block
    264. =====================================================================
    265. Qui in magna commodo, est labitur dolorum an. Est ne magna primis
    266. adolescens.
    267. . Fusce euismod commodo velit.
    268. . Vivamus fringilla mi eu lacus.
    269. .. Fusce euismod commodo velit.
    270. .. Vivamus fringilla mi eu lacus.
    271. . Donec eget arcu bibendum
    272. nunc consequat lobortis.
    273. =====================================================================
    274. ---------------------------------------------------------------------
    275. Renders:
    276. [NOTE]
    277. .A NOTE block
    278. =====================================================================
    279. Qui in magna commodo, est labitur dolorum an. Est ne magna primis
    280. adolescens.
    281. . Fusce euismod commodo velit.
    282. . Vivamus fringilla mi eu lacus.
    283. .. Fusce euismod commodo velit.
    284. .. Vivamus fringilla mi eu lacus.
    285. . Donec eget arcu bibendum
    286. nunc consequat lobortis.
    287. =====================================================================
    288. See also <<X47,Admonition Icons and Captions>>.
    289. [[X29]]
    290. 开放块
    291. ~~~~~~~~~~~
    292. An 'OpenBlock' renders the block contents without any opening or
    293. closing tags. The open block start and end delimiter is a single line
    294. containing two dashes. Enclosed elements are rendered just as they
    295. would inside a section body. Open blocks are used for <<X15,list item
    296. continuation>>.
    297. [[X64]]
    298. 列表
    299. -----
    300. .列表类型
    301. - 项目符号列表。也称为分项或无序列表。
    302. - 编号列表。又称为有序列表。
    303. - 标记列表。有时被称为变量或定义列表。
    304. - 标注名单(名单标注说明)。
    305. .List behavior
    306. - List item indentation is optional and does not determine nesting,
    307. indentation does however make the source more readable.
    308. - Another list or a literal paragraph immediately following a list
    309. item will be implicitly included in the list item; use <<X15, list
    310. item continuation>> to explicitly append other block elements to a
    311. list item.
    312. - A comment block or a comment line block macro element will terminate
    313. a list -- use inline comment lines to put comments inside lists.
    314. - The `listindex` <<X60,intrinsic attribute>> is the current list item
    315. index (1..). If this attribute is not inside a list then it's value
    316. is the number of items in the most recently closed list. Useful for
    317. displaying the number of items in a list.
    318. .List behavior
    319. - 列表项的缩进是可选的,并不决定嵌套,但可以使源文件更具可读性。
    320. - 另一份清单或文字段落紧跟一个列表项目将包含进改列表项目;使用<<X15,列表项连续性>>标明追加其他块元素列表项。
    321. - A comment block or a comment line block macro element will terminate
    322. a list -- use inline comment lines to put comments inside lists.
    323. - The `listindex` <<X60,intrinsic attribute>> is the current list item
    324. index (1..). If this attribute is not inside a list then it's value
    325. is the number of items in the most recently closed list. Useful for
    326. displaying the number of items in a list.
    327. 项目符号列表
    328. ~~~~~~~~~~~~~~
    329. Bulleted list items start with a single dash or one to five asterisks
    330. followed by some white space then some text. Bulleted list syntaxes
    331. are:
    332. ...................
    333. - List item.
    334. * List item.
    335. ** List item.
    336. *** List item.
    337. **** List item.
    338. ***** List item.
    339. ...................
    340. 编号列表
    341. ~~~~~~~~~~~~~~
    342. List item numbers are explicit or implicit.
    343. .Explicit numbering
    344. List items begin with a number followed by some white space then the
    345. item text. The numbers can be decimal (arabic), roman (upper or lower
    346. case) or alpha (upper or lower case). Decimal and alpha numbers are
    347. terminated with a period, roman numbers are terminated with a closing
    348. parenthesis. The different terminators are necessary to ensure 'i',
    349. 'v' and 'x' roman numbers are are distinguishable from 'x', 'v' and
    350. 'x' alpha numbers. Examples:
    351. .....................................................................
    352. 1. Arabic (decimal) numbered list item.
    353. a. Lower case alpha (letter) numbered list item.
    354. F. Upper case alpha (letter) numbered list item.
    355. iii) Lower case roman numbered list item.
    356. IX) Upper case roman numbered list item.
    357. .....................................................................
    358. .Implicit numbering
    359. List items begin one to five period characters, followed by some white
    360. space then the item text. Examples:
    361. .....................................................................
    362. . Arabic (decimal) numbered list item.
    363. .. Lower case alpha (letter) numbered list item.
    364. ... Lower case roman numbered list item.
    365. .... Upper case alpha (letter) numbered list item.
    366. ..... Upper case roman numbered list item.
    367. .....................................................................
    368. You can use the 'style' attribute to specify an alternative numbering
    369. style. The numbered list style can be one of the following values:
    370. 'arabic', 'loweralpha', 'upperalpha', 'lowerroman', 'upperroman'.
    371. Here are some examples of bulleted and numbered lists:
    372. ---------------------------------------------------------------------
    373. - Praesent eget purus quis magna eleifend eleifend.
    374. 1. Fusce euismod commodo velit.
    375. a. Fusce euismod commodo velit.
    376. b. Vivamus fringilla mi eu lacus.
    377. c. Donec eget arcu bibendum nunc consequat lobortis.
    378. 2. Vivamus fringilla mi eu lacus.
    379. i) Fusce euismod commodo velit.
    380. ii) Vivamus fringilla mi eu lacus.
    381. 3. Donec eget arcu bibendum nunc consequat lobortis.
    382. 4. Nam fermentum mattis ante.
    383. - Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    384. * Fusce euismod commodo velit.
    385. ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
    386. adolescens. Sit munere ponderum dignissim et. Minim luptatum et
    387. vel.
    388. ** Vivamus fringilla mi eu lacus.
    389. * Donec eget arcu bibendum nunc consequat lobortis.
    390. - Nulla porttitor vulputate libero.
    391. . Fusce euismod commodo velit.
    392. . Vivamus fringilla mi eu lacus.
    393. [upperroman]
    394. .. Fusce euismod commodo velit.
    395. .. Vivamus fringilla mi eu lacus.
    396. . Donec eget arcu bibendum nunc consequat lobortis.
    397. ---------------------------------------------------------------------
    398. Which render as:
    399. - Praesent eget purus quis magna eleifend eleifend.
    400. 1. Fusce euismod commodo velit.
    401. a. Fusce euismod commodo velit.
    402. b. Vivamus fringilla mi eu lacus.
    403. c. Donec eget arcu bibendum nunc consequat lobortis.
    404. 2. Vivamus fringilla mi eu lacus.
    405. i) Fusce euismod commodo velit.
    406. ii) Vivamus fringilla mi eu lacus.
    407. 3. Donec eget arcu bibendum nunc consequat lobortis.
    408. 4. Nam fermentum mattis ante.
    409. - Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    410. * Fusce euismod commodo velit.
    411. ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
    412. adolescens. Sit munere ponderum dignissim et. Minim luptatum et
    413. vel.
    414. ** Vivamus fringilla mi eu lacus.
    415. * Donec eget arcu bibendum nunc consequat lobortis.
    416. - Nulla porttitor vulputate libero.
    417. . Fusce euismod commodo velit.
    418. . Vivamus fringilla mi eu lacus.
    419. [upperroman]
    420. .. Fusce euismod commodo velit.
    421. .. Vivamus fringilla mi eu lacus.
    422. . Donec eget arcu bibendum nunc consequat lobortis.
    423. A predefined 'compact' option is available to bulleted and numbered
    424. lists -- this translates to the DocBook 'spacing="compact"' lists
    425. attribute which may or may not be processed by the DocBook toolchain.
    426. Example:
    427. [options="compact"]
    428. - Compact list item.
    429. - Another compact list item.
    430. TIP: To apply the 'compact' option globally define a document-wide
    431. 'compact-option' attribute, e.g. using the `-a compact-option`
    432. command-line option.
    433. 标记列表
    434. ~~~~~~~~~~~~~
    435. Labeled list items consist of one or more text labels followed the
    436. text of the list item.
    437. An item label begins a line with an alphanumeric character hard
    438. against the left margin and ends with one to four colons or two
    439. semi-colons. A list item can have multiple labels, one per line.
    440. The list item text consists of one or more lines of text starting
    441. after the last label (either on the same line or a new line) and can
    442. be followed by nested List or ListParagraph elements. Item text can be
    443. optionally indented.
    444. Here are some examples:
    445. ---------------------------------------------------------------------
    446. In::
    447. Lorem::
    448. Fusce euismod commodo velit.
    449. Fusce euismod commodo velit.
    450. Ipsum:: Vivamus fringilla mi eu lacus.
    451. * Vivamus fringilla mi eu lacus.
    452. * Donec eget arcu bibendum nunc consequat lobortis.
    453. Dolor::
    454. Donec eget arcu bibendum nunc consequat lobortis.
    455. Suspendisse;;
    456. A massa id sem aliquam auctor.
    457. Morbi;;
    458. Pretium nulla vel lorem.
    459. In;;
    460. Dictum mauris in urna.
    461. Vivamus::: Fringilla mi eu lacus.
    462. Donec::: Eget arcu bibendum nunc consequat lobortis.
    463. ---------------------------------------------------------------------
    464. Which render as:
    465. In::
    466. Lorem::
    467. Fusce euismod commodo velit.
    468. Fusce euismod commodo velit.
    469. Ipsum:: Vivamus fringilla mi eu lacus.
    470. * Vivamus fringilla mi eu lacus.
    471. * Donec eget arcu bibendum nunc consequat lobortis.
    472. Dolor::
    473. Donec eget arcu bibendum nunc consequat lobortis.
    474. Suspendisse;;
    475. A massa id sem aliquam auctor.
    476. Morbi;;
    477. Pretium nulla vel lorem.
    478. In;;
    479. Dictum mauris in urna.
    480. Vivamus::: Fringilla mi eu lacus.
    481. Donec::: Eget arcu bibendum nunc consequat lobortis.
    482. Horizontal labeled list style
    483. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    484. The 'horizontal' labeled list style places the list text side-by-side
    485. with the label instead of under the label. Here is an example:
    486. ---------------------------------------------------------------------
    487. [horizontal]
    488. *Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
    489. labitur dolorum an. Est ne magna primis adolescens.
    490. Fusce euismod commodo velit.
    491. *Ipsum*:: Vivamus fringilla mi eu lacus.
    492. - Vivamus fringilla mi eu lacus.
    493. - Donec eget arcu bibendum nunc consequat lobortis.
    494. *Dolor*::
    495. - Vivamus fringilla mi eu lacus.
    496. - Donec eget arcu bibendum nunc consequat lobortis.
    497. ---------------------------------------------------------------------
    498. Which render as:
    499. [horizontal]
    500. *Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
    501. labitur dolorum an. Est ne magna primis adolescens.
    502. Fusce euismod commodo velit.
    503. *Ipsum*:: Vivamus fringilla mi eu lacus.
    504. - Vivamus fringilla mi eu lacus.
    505. - Donec eget arcu bibendum nunc consequat lobortis.
    506. *Dolor*::
    507. - Vivamus fringilla mi eu lacus.
    508. - Donec eget arcu bibendum nunc consequat lobortis.
    509. [NOTE]
    510. =====================================================================
    511. - Current PDF toolchains do not make a good job of determining
    512. the relative column widths for horizontal labeled lists.
    513. - If you are generating DocBook markup then horizontal labeled lists
    514. should not be nested because the 'DocBook XML V4.2' DTD does not
    515. permit nested informal tables (although <<X13,DocBook XSL
    516. Stylesheets>> and <<X31,dblatex>> process them correctly).
    517. - The label width can be set as a percentage of the total width by
    518. setting the 'width' attribute e.g. `width="10%"`
    519. =====================================================================
    520. 答问列表
    521. ~~~~~~~~~~~~~~~~~~~~~~~~~
    522. AsciiDoc comes pre-configured with a 'qanda' style labeled list for generating
    523. DocBook question and answer (Q&A) lists. Example:
    524. ---------------------------------------------------------------------
    525. [qanda]
    526. Question one::
    527. Answer one.
    528. Question two::
    529. Answer two.
    530. ---------------------------------------------------------------------
    531. Renders:
    532. [qanda]
    533. Question one::
    534. Answer one.
    535. Question two::
    536. Answer two.
    537. 专业术语列表
    538. ~~~~~~~~~~~~~~
    539. AsciiDoc comes pre-configured with a 'glossary' style labeled list for
    540. generating DocBook glossary lists. Example:
    541. ---------------------------------------------------------------------
    542. [glossary]
    543. A glossary term::
    544. The corresponding definition.
    545. A second glossary term::
    546. The corresponding definition.
    547. ---------------------------------------------------------------------
    548. For working examples see the `article.txt` and `book.txt` documents in
    549. the AsciiDoc `./doc` distribution directory.
    550. NOTE: To generate valid DocBook output glossary lists must be located
    551. in a glossary section.
    552. 参考书目列表
    553. ~~~~~~~~~~~~~~~~~~
    554. AsciiDoc comes with a predefined 'bibliography' bulleted list style
    555. generating DocBook bibliography entries. Example:
    556. ---------------------------------------------------------------------
    557. [bibliography]
    558. - [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
    559. Programming'. Addison-Wesley. ISBN 0-13-142901-9.
    560. - [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
    561. 'DocBook - The Definitive Guide'. O'Reilly & Associates.
    562. 1999. ISBN 1-56592-580-7.
    563. ---------------------------------------------------------------------
    564. The `[[[<reference>]]]` syntax is a bibliography entry anchor, it
    565. generates an anchor named `<reference>` and additionally displays
    566. `[<reference>]` at the anchor position. For example `[\[[taoup]]]`
    567. generates an anchor named `taoup` that displays `[taoup]` at the
    568. anchor position. Cite the reference from elsewhere your document using
    569. `<<taoup>>`, this displays a hyperlink (`[taoup]`) to the
    570. corresponding bibliography entry anchor.
    571. For working examples see the `article.txt` and `book.txt` documents in
    572. the AsciiDoc `./doc` distribution directory.
    573. NOTE: To generate valid DocBook output bibliography lists must be
    574. located in a bibliography section.
    575. [[X15]]
    576. 列表项连续
    577. ~~~~~~~~~~~~~~~~~~~~~~
    578. Another list or a literal paragraph immediately following a list item
    579. is implicitly appended to the list item; to append other block
    580. elements to a list item you need to explicitly join them to the list
    581. item with a 'list continuation' (a separator line containing a single
    582. plus character). Multiple block elements can be appended to a list
    583. item using list continuations (provided they are legal list item
    584. children in the backend markup).
    585. Here are some examples of list item continuations: list item one
    586. contains multiple continuations; list item two is continued with an
    587. <<X29,OpenBlock>> containing multiple elements:
    588. ---------------------------------------------------------------------
    589. 1. List item one.
    590. +
    591. List item one continued with a second paragraph followed by an
    592. Indented block.
    593. +
    594. .................
    595. $ ls *.sh
    596. $ mv *.sh ~/tmp
    597. .................
    598. +
    599. List item continued with a third paragraph.
    600. 2. List item two continued with an open block.
    601. +
    602. --
    603. This paragraph is part of the preceding list item.
    604. a. This list is nested and does not require explicit item continuation.
    605. +
    606. This paragraph is part of the preceding list item.
    607. b. List item b.
    608. This paragraph belongs to item two of the outer list.
    609. --
    610. ---------------------------------------------------------------------
    611. Renders:
    612. 1. List item one.
    613. +
    614. List item one continued with a second paragraph followed by an
    615. Indented block.
    616. +
    617. .................
    618. $ ls *.sh
    619. $ mv *.sh ~/tmp
    620. .................
    621. +
    622. List item continued with a third paragraph.
    623. 2. List item two continued with an open block.
    624. +
    625. --
    626. This paragraph is part of the preceding list item.
    627. a. This list is nested and does not require explicit item continuation.
    628. +
    629. This paragraph is part of the preceding list item.
    630. b. List item b.
    631. This paragraph belongs to item two of the outer list.
    632. --
    633. 脚注
    634. ---------
    635. The shipped AsciiDoc configuration includes the `footnote:[<text>]`
    636. and `footnoteref:[<id>,<text>]` inline macros for generating
    637. footnotes:
    638. - The `footnote` macro generates a footnote.
    639. - The `footnoteref` macro has two forms: if the text is supplied a
    640. foot note with an ID is generated; if the text is omitted a
    641. reference to the footnote with the specified ID is generated.
    642. - The footnote text can span multiple lines.
    643. Example footnote:
    644. A footnote footnote:[An example footnote.];
    645. a second footnote with a reference ID footnoteref:[note2,Second footnote.];
    646. finally a reference to the second footnote footnoteref:[note2].
    647. Which renders:
    648. A footnote footnote:[An example footnote.];
    649. a second footnote with a reference ID footnoteref:[note2,Second footnote];
    650. finally a reference to the second footnote footnoteref:[note2].
    651. Footnotes are primarily useful when generating DocBook output --
    652. DocBook conversion programs render footnote outside the primary text
    653. flow.
    654. 索引
    655. -------
    656. The shipped AsciiDoc configuration includes the inline macros for
    657. generating document index entries.
    658. `indexterm:[<primary>,<secondary>,<tertiary>]`::
    659. `(((<primary>,<secondary>,<tertiary>)))`::
    660. This inline macro generates an index term (the <secondary> and
    661. <tertiary> attributes are optional). For example
    662. `indexterm:[Tigers,Big cats]` (or, using the alternative syntax
    663. `(((Tigers,Big cats)))`. Index terms that have secondary and
    664. tertiary entries also generate separate index terms for the
    665. secondary and tertiary entries. The index terms appear in the
    666. index, not the primary text flow.
    667. `indexterm2:[<primary>]`::
    668. `((<primary>))`::
    669. This inline macro generates an index term that appears in both the
    670. index and the primary text flow. The `<primary>` should not be
    671. padded to the left or right with white space characters.
    672. For working examples see the `article.txt` and `book.txt` documents in
    673. the AsciiDoc `./doc` distribution directory.
    674. NOTE: Index entries only really make sense if you are generating
    675. DocBook markup -- DocBook conversion programs automatically generate
    676. an index at the point an 'Index' section appears in source document.
    677. 执行输出
    678. --------
    679. Callouts are a mechanism for annotating verbatim text (source code,
    680. computer output and user input for example). Callout markers are
    681. placed inside the annotated text while the actual annotations are
    682. presented in a callout list after the annotated text. Here's an
    683. example:
    684. ---------------------------------------------------------------------
    685. .MS-DOS directory listing
    686. -----------------------------------------------------
    687. 10/17/97 9:04 <DIR> bin
    688. 10/16/97 14:11 <DIR> DOS \<1>
    689. 10/16/97 14:40 <DIR> Program Files
    690. 10/16/97 14:46 <DIR> TEMP
    691. 10/17/97 9:04 <DIR> tmp
    692. 10/16/97 14:37 <DIR> WINNT
    693. 10/16/97 14:25 119 AUTOEXEC.BAT \<2>
    694. 2/13/94 6:21 54,619 COMMAND.COM \<2>
    695. 10/16/97 14:25 115 CONFIG.SYS \<2>
    696. 11/16/97 17:17 61,865,984 pagefile.sys
    697. 2/13/94 6:21 9,349 WINA20.386 \<3>
    698. -----------------------------------------------------
    699. \<1> This directory holds MS-DOS.
    700. \<2> System startup code for DOS.
    701. \<3> Some sort of Windows 3.1 hack.
    702. ---------------------------------------------------------------------
    703. Which renders:
    704. .MS-DOS directory listing
    705. -----------------------------------------------------
    706. 10/17/97 9:04 <DIR> bin
    707. 10/16/97 14:11 <DIR> DOS <1>
    708. 10/16/97 14:40 <DIR> Program Files
    709. 10/16/97 14:46 <DIR> TEMP
    710. 10/17/97 9:04 <DIR> tmp
    711. 10/16/97 14:37 <DIR> WINNT
    712. 10/16/97 14:25 119 AUTOEXEC.BAT <2>
    713. 2/13/94 6:21 54,619 COMMAND.COM <2>
    714. 10/16/97 14:25 115 CONFIG.SYS <2>
    715. 11/16/97 17:17 61,865,984 pagefile.sys
    716. 2/13/94 6:21 9,349 WINA20.386 <3>
    717. -----------------------------------------------------
    718. <1> This directory holds MS-DOS.
    719. <2> System startup code for DOS.
    720. <3> Some sort of Windows 3.1 hack.
    721. .Explanation
    722. - The callout marks are whole numbers enclosed in angle brackets that
    723. refer to an item index in the following callout list.
    724. - By default callout marks are confined to LiteralParagraphs,
    725. LiteralBlocks and ListingBlocks (although this is a configuration
    726. file option and can be changed).
    727. - Callout list item numbering is fairly relaxed -- list items can
    728. start with `<n>`, `n>` or `>` where `n` is the optional list item
    729. number (in the latter case list items starting with a single `>`
    730. character are implicitly numbered starting at one).
    731. - Callout lists should not be nested -- start list items hard against
    732. the left margin.
    733. - If you want to present a number inside angle brackets you'll need to
    734. escape it with a backslash to prevent it being interpreted as a
    735. callout mark.
    736. NOTE: To include callout icons in PDF files generated by
    737. <<X43,a2x(1)>> you need to use the `--icons` command-line option.
    738. 运行记录
    739. ~~~~~~~~~~~~~~~~~~~~
    740. Callout marks are generated by the 'callout' inline macro while
    741. callout lists are generated using the 'callout' list definition. The
    742. 'callout' macro and 'callout' list are special in that they work
    743. together. The 'callout' inline macro is not enabled by the normal
    744. 'macros' substitutions option, instead it has its own 'callouts'
    745. substitution option.
    746. The following attributes are available during inline callout macro
    747. substitution:
    748. `{index}`::
    749. The callout list item index inside the angle brackets.
    750. `{coid}`::
    751. An identifier formatted like `CO<listnumber>-<index>` that
    752. uniquely identifies the callout mark. For example `CO2-4`
    753. identifies the fourth callout mark in the second set of callout
    754. marks.
    755. The `{coids}` attribute can be used during callout list item
    756. substitution -- it is a space delimited list of callout IDs that refer
    757. to the explanatory list item.
    758. 包含运行输出到包含代码
    759. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    760. You can annotate working code examples with callouts -- just remember
    761. to put the callouts inside source code comments. This example displays
    762. the `test.py` source file (containing a single callout) using the
    763. <<X57,Source Code Highlighter Filter>>:
    764. .AsciiDoc source
    765. ---------------------------------------------------------------------
    766. [source,python]
    767. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    768. \include::test.py[]
    769. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    770. \<1> Print statement.
    771. ---------------------------------------------------------------------
    772. .Included `test.py` source
    773. ---------------------------------------------------------------------
    774. print 'Hello World!' # \<1>
    775. ---------------------------------------------------------------------
    776. ------
    777. Macros are a mechanism for substituting parametrized text into output
    778. documents.
    779. Macros have a 'name', a single 'target' argument and an 'attribute
    780. list'. The usual syntax is `<name>:<target>[<attrlist>]` (for
    781. inline macros) and `<name>::<target>[<attrlist>]` (for block
    782. macros). Here are some examples:
    783. http://www.methods.co.nz/asciidoc/index.html[Asciidoc home page]
    784. include::chapt1.txt[tabsize=2]
    785. mailto:srackham@gmail.com[]
    786. .Macro behavior
    787. - `<name>` is the macro name. It can only contain letters, digits or
    788. dash characters and cannot start with a dash.
    789. - The optional `<target>` cannot contain white space characters.
    790. - `<attrlist>` is a <<X21,list of attributes>> enclosed in square
    791. brackets.
    792. - `]` characters in attribute lists that are enclosed in `[]` brackets
    793. must be escaped with a backslash.
    794. - Expansion of non-system macro references can normally be escaped by
    795. prefixing a backslash character (see the AsciiDoc 'FAQ' for examples
    796. of exceptions to this rule).
    797. - System macros cannot be escaped.
    798. - Attribute references in block macros are expanded.
    799. - The substitutions performed prior to Inline macro macro expansion
    800. are determined by the inline context.
    801. - Macros are processed in the order they appear in the configuration
    802. file(s).
    803. - Calls to inline macros can be nested inside different inline macros
    804. (an inline macro call cannot contain a nested call to itself).
    805. - In addition to `<name>`, `<target>` and `<attrlist>` the
    806. `<passtext>` and `<subslist>` named groups are available to
    807. <<X77,passthrough macros>>. A macro is a passthrough macro if the
    808. definition includes a `<passtext>` named group.
    809. 内置宏
    810. ~~~~~~~~~~~~~
    811. Inline Macros occur in an inline element context. Predefined Inline
    812. macros include 'URLs', 'image' and 'link' macros.

    链接
    ^^^^
    ‘http’, ‘https’, ‘ftp’, ‘file’, ‘mailto’ and ‘callto’ URLs are
    rendered using predefined inline macros.

    - If you don't need a customized the link caption you can enter the
      'http', 'https', 'ftp', 'file' URLs and email addresses without any
      special macro syntax.
    - If the `<attrlist>` is empty the URL is displayed.
    
    Here are some examples:
    
      http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]
      http://www.methods.co.nz/asciidoc/
      mailto:joe.bloggs@foobar.com[email Joe Bloggs]
      joe.bloggs@foobar.com
    
    Which are rendered:
    
    http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]
    
    http://www.methods.co.nz/asciidoc/
    
    mailto:joe.bloggs@foobar.com[email Joe Bloggs]
    
    joe.bloggs@foobar.com
    
    - If the `<target>` necessitates space characters they should be
      replaced by `%20`. For example `large%20image.png`.
    - Define an attribute entry if you refer to the same URL more than
      once, this will make your document <<X62,easier to maintain and
      easier to read>>.
    
    内部交叉引用
    ^^^^^^^^^^^^^^^^^^^^^^^^^
    Two AsciiDoc inline macros are provided for creating hypertext links
    within an AsciiDoc document. You can use either the standard macro
    syntax or the (preferred) alternative.
    
    [[X30]]
    锚点
    ++++++
    Used to specify hypertext link targets:
    
      [[<id>,<xreflabel>]]
      anchor:<id>[<xreflabel>]
    
    The `<id>` is a unique identifier that must begin with a letter. The
    optional `<xreflabel>` is the text to be displayed by captionless
    'xref' macros that refer to this anchor. The optional `<xreflabel>` is
    only really useful when generating DocBook output. Example anchor:
    
      [[X1]]
    
    You may have noticed that the syntax of this inline element is the
    same as that of the <<X41,BlockId block element>>, this is no
    coincidence since they are functionally equivalent.
    
    xref
    ++++
    Creates a hypertext link to a document anchor.
    
      <<<id>,<caption>>>
      xref:<id>[<caption>]
    
    The `<id>` refers to an existing anchor `<id>`. The optional
    `<caption>` is the link's displayed text. Example:
    
      <<X21,attribute lists>>
    
    If `<caption>` is not specified then the displayed text is
    auto-generated:
    
    - The AsciiDoc `xhtml11` backend displays the `<id>` enclosed in
      square brackets.
    - If DocBook is produced the DocBook toolchain is responsible for the
      displayed text which will normally be the referenced figure, table
      or section title number followed by the element's title text.
    
    Here is an example:
    
    ---------------------------------------------------------------------
    [[tiger_image]]
    .Tyger tyger
    image::tiger.png[]
    
    This can be seen in <<tiger_image>>.
    ---------------------------------------------------------------------
    
    链接到本地文件
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
    Hypertext links to files on the local file system are specified using
    the 'link' inline macro.
    
      link:<target>[<caption>]
    
    The 'link' macro generates relative URLs. The link macro `<target>` is
    the target file name (relative to the file system location of the
    referring document). The optional `<caption>` is the link's displayed
    text. If `<caption>` is not specified then `<target>` is displayed.
    Example:
    
      link:downloads/foo.zip[download foo.zip]
    
    You can use the `<filename>#<id>` syntax to refer to an anchor within
    a target document but this usually only makes sense when targeting
    HTML documents.
    
    Images can serve as hyperlinks using the <<X9,`image` macro>>.
    
    [[X9]]
    图片
    ^^^^^^
    Inline images are inserted into the output document using the 'image'
    macro. The inline syntax is:
    
      image:<target>[<attributes>]
    
    The contents of the image file `<target>` is displayed. To display the
    image its file format must be supported by the target backend
    application. HTML and DocBook applications normally support PNG or JPG
    files.
    
    `<target>` file name paths are relative to the location of the
    referring document.
    
    [[X55]]
    .Image macro attributes
    - The optional 'alt' attribute is also the first positional attribute,
      it specifies alternative text which is displayed if the output
      application is unable to process the image file. For example:
    
      image:images/logo.png[Company Logo]
    
    - The optional `width` and `height` attributes scale the image size
      and can be used in any combination. The units are pixels.  The
      following example scales the previous example to a height of 32
      pixels:
    
      image:images/logo.png["Company Logo",height=32]
    
    - The optional `link` attribute is used to link the image to an
      external document. The following example links a screenshot
      thumbnail to a full size version:
    
      image:screen-thumbnail.png[height=32,link="screen.png"]
    
    - The optional `scaledwidth` attribute is only used in DocBook block
      images (specifically for PDF documents). The following example
      scales the images to 75% of the available print width:
    
      image::images/logo.png[scaledwidth="75%",alt="Company Logo"]
    
    - The optional `align` attribute is used for horizontal image
      alignment.  Allowed values are `center`, `left` and `right`. For
      example:
    
      image::images/tiger.png["Tiger image",align="left"]
    
    - The optional `float` attribute floats the image `left` or `right` on
      the page (works with HTML outputs only, has no effect on DocBook
      outputs). `float` and `align` attributes are mutually exclusive.
      Use the `unfloat::[]` block macro to stop floating.
    
    注释行
    ^^^^^^^^^^^^^
    See <<X25,comment block macro>>.
    
    块宏
    ~~~~~~~~~~~~
    A Block macro reference must be contained in a single line separated
    either side by a blank line or a block delimiter.
    
    Block macros behave just like Inline macros, with the following
    differences:
    
    - They occur in a block context.
    - The default syntax is `<name>::<target>[<attrlist>]` (two
      colons, not one).
    - Markup template section names end in `-blockmacro` instead of
      `-inlinemacro`.
    
    块标志
    ^^^^^^^^^^^^^^^^
    The Block Identifier macro sets the `id` attribute and has the same
    syntax as the <<X30,anchor inline macro>> since it performs
    essentially the same function -- block templates employ the `id`
    attribute as a block link target. For example:
    
      [[X30]]
    
    This is equivalent to the `[id="X30"]` block attribute list.
    
    [[X49]]
    图片
    ^^^^^^
    Formal titled images are inserted into the output document using the
    'image' macro. The syntax is:
    
      image::<target>[<attributes>]
    
    The block `image` macro has the same <<X55,macro attributes>> as its
    <<X9,inline counterpart>>.
    
    Images can be titled by preceding the `image` macro with a
    'BlockTitle'.  DocBook toolchains normally number examples and
    generate a 'List of Figures' backmatter section.
    
    For example:
    
      .Main circuit board
      image::images/layout.png[J14P main circuit board]
    
    A title prefix that can be inserted with the `caption` attribute
    (`xhtml11` and `html4` backends). For example:
    
      .Main circuit board
      [caption="Figure 2: "]
      image::images/layout.png[J14P main circuit board]
    
    [[X66]]
    .Embedding images in XHTML documents
    *********************************************************************
    If you define the `data-uri` attribute then images will be embedded in
    XHTML outputs using the
    http://en.wikipedia.org/wiki/Data:_URI_scheme[data URI scheme].  You
    can use the 'data-uri' attribute with the 'xhtml11' backend to produce
    single-file XHTML documents with embedded images and CSS, for example:
    
      $ asciidoc -a data-uri mydocument.txt
    
    NOTE: All current popular browsers support 'data URIs', although
    versions of Internet Explorer prior to version 8 do not support 'data
    URIs'.
    
    *********************************************************************
    
    [[X25]]
    注释行
    ^^^^^^^^^^^^^
    Single lines starting with two forward slashes hard up against the
    left margin are treated as comments. Comment lines do not appear in
    the output unless the 'showcomments' attribute is defined.  Comment
    lines have been implemented as both block and inline macros so a
    comment line can appear as a standalone block or within block elements
    that support inline macro expansion. Example comment line:
    
      // This is a comment.
    
    If the 'showcomments' attribute is defined comment lines are written
    to the output:
    
    - The normal AsciiDoc inline text formatting is applied to comment
      lines.
    - In DocBook the comment lines are enclosed by the 'remark' element
      (which may or may not be rendered by your toolchain).
    - The 'showcomments' attribute does not expose <<X26,Comment Blocks>>.
      Comment Blocks are never passed to the output.
    
    系统宏
    ~~~~~~~~~~~~~
    System macros are block macros that perform a predefined task and are
    hardwired into the asciidoc(1) program.
    
    - You can escape system macros with a leading backslash character
      (as you can with other macros).
    - The syntax and tasks performed by system macros is built into
      asciidoc(1) so they don't appear in configuration files.  You can
      however customize the syntax by adding entries to a configuration
      file `[macros]` section.
    
    [[X63]]
    包含宏
    ^^^^^^^^^^^^^^
    The `include` and `include1`  system macros to include the contents of
    a named file into the source document.
    
    The `include` macro includes a file as if it were part of the parent
    document -- tabs are expanded and system macros processed. The
    contents of `include1` files are not subject to tab expansion or
    system macro processing nor are attribute or lower priority
    substitutions performed. The `include1` macro's intended use is to
    include verbatim embedded CSS or scripts into configuration file
    headers.  Example:
    
    ------------------------------------
    \include::chapter1.txt[tabsize=4]
    ------------------------------------
    
    .Include macro behavior
    - If the included file name is specified with a relative path then the
      path is relative to the location of the referring document.
    - Include macros can appear inside configuration files.
    - Files included from within 'DelimitedBlocks' are read to completion
      to avoid false end-of-block underline termination.
    - Attribute references are expanded inside the include 'target'; if an
      attribute is undefined then the included file is silently skipped.
    - The 'tabsize' macro attribute sets the number of space characters to
      be used for tab expansion in the included file (not applicable to
      `include1` macro).
    - The 'depth' macro attribute sets the maximum permitted number of
      subsequent nested includes (not applicable to `include1` macro which
      does not process nested includes). Setting 'depth' to one disables
      nesting inside the included file. By default, nesting is limited to
      a depth of five.
    - Internally the `include1` macro is translated to the `include1`
      system attribute which means it must be evaluated in a region where
      attribute substitution is enabled. To inhibit nested substitution in
      included files it is preferable to use the `include` macro and set
      the attribute `depth=1`.
    
    Conditional Inclusion Macros
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    Lines of text in the source document can be selectively included or
    excluded from processing based on the existence (or not) of a document
    attribute.  There are two conditional inclusion macros; the first
    includes document text between the `ifdef` and `endif` macros if a
    document attribute is defined:
    
      ifdef::<attribute>[]
      :
      endif::<attribute>[]
    
    The second includes document text between the `ifndef` and `endif`
    macros if the attribute is not defined:
    
      ifndef::<attribute>[]
      :
      endif::<attribute>[]
    
    `<attribute>` is an attribute name which is optional in the trailing
    `endif` macro.
    
    If you only want to process a single line of text then the text can be
    put inside the square brackets and the `endif` macro omitted, for
    example:
    
      ifdef::revnumber[Version number 42]
    
    Is equivalent to:
    
      ifdef::revnumber[]
      Version number 42
      endif::revnumber[]
    
    Take a look at the `*.conf` configuration files in the AsciiDoc
    distribution for examples of conditional inclusion macro usage.
    
    .Two types of conditional inclusion
    *********************************************************************
    Conditional inclusion macros are evaluated when they are read, but
    there is another type of conditional inclusion based on attribute
    references, the latter being evaluated when the output file is
    written.
    
    These examples illustrate the two forms of conditional inclusion. The
    only difference between them is that the first is evaluated at program
    load time while the second is evaluated when the output is written:
    
      ifdef::world[]
        Hello World!
      endif::world[]
    
      {world#}Hello World!
    
    In this example when the `{world#}` conditional attribute reference
    is evaluates to a zero length string if `world` is defined; if `world`
    is not defined the whole line is dropped.
    
    The subtle difference between the two types of conditional inclusion
    has implications for AsciiDoc configuration files: AsciiDoc has to
    read the configuration files *before* reading the source document,
    this is necessary because the AsciiDoc source syntax is mostly defined
    by the configuration files.  This means that any lines of markup
    enveloped by conditional inclusion macros will be included or excluded
    *before* the attribute entries in the AsciiDoc document header are
    read, so setting related attributes in the AsciiDoc source document
    header will have no effect.  If you need to control configuration file
    markup inclusion with attribute entries in the AsciiDoc source file
    header you need to use attribute references to control inclusion
    instead of conditional inclusion macros (attribute references are
    substituted at the time the output is written rather than at program
    startup).
    
    *********************************************************************
    
    执行系统宏
    ^^^^^^^^^^^^^^^^^^^^^^^^
    The 'eval', 'sys' and 'sys2' block macros exhibit the same behavior as
    their same named <<X24, system attribute references>>. The difference
    is that system macros occur in a block macro context whereas system
    attributes are confined to an inline context where attribute
    substitution is enabled.
    
    The following example displays a long directory listing inside a
    literal block:
    
      ------------------
      sys::[ls -l *.txt]
      ------------------
    
    NOTE: There are no block macro versions of the 'eval3' and 'sys3'
    system attributes.
    
    模板系统宏
    ^^^^^^^^^^^^^^^^^^^^^
    The `template` block macro allows the inclusion of one configuration
    file template section within another.  The following example includes
    the `[admonitionblock]` section in the `[admonitionparagraph]`
    section:
    
      [admonitionparagraph]
      template::[admonitionblock]
    
    .Template macro behavior
    - The `template::[]` macro is useful for factoring configuration file
      markup.
    - `template::[]` macros cannot be nested.
    - `template::[]` macro expansion is applied to all sections
      after all configuration files have been read.
    
    
    [[X77]]
    Passthrough macros
    ~~~~~~~~~~~~~~~~~~
    Passthrough macros are analogous to <<X76,passthrough blocks>> and are
    used to pass text directly to the output. The substitution performed
    on the text is determined by the macro definition but can be overridden
    by the `<subslist>`.  The usual syntax is
    `<name>:<subslist>[<passtext>]` (for inline macros) and
    `<name>::<subslist>[<passtext>]` (for block macros).
    
    pass::
      Inline and block. Passes text unmodified apart from explicitly
      specified substitutions). Examples:
    
      pass:[<q>To be or not to be</q>]
      pass:attributes,quotes[<u>the '{author}'</u>]
    
    asciimath, latexmath::
      Inline and block. Passes text unmodified.  Used for
      <<X78,mathematical formulas>>.
    
    \+++::
      Inline and block. The triple-plus passthrough is functionally
      identical to the 'pass' macro but you don't have to escape `]`
      characters and you can prefix with quoted attributes in the inline
      version. Example:
    
      Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMathML formula
    
    $$::
      Inline and block. The double-dollar passthrough is functionally
      identical to the triple-plus passthrough with one exception: special
      characters are escaped. Example:
    
      $$`[[a,b],[c,d]]((n),(k))`$$
    
    [[X80]]`::
      Text quoted with single backtick characters constitutes an 'inline
      literal' passthrough. The enclosed text is rendered in a monospaced
      font and is only subject to special character substitution.  This
      makes sense since monospace text is usually intended to be rendered
      literally and often contains characters that would otherwise have to
      be escaped. If you need monospaced text containing inline
      substitutions use a <<X81,plus character instead of a backtick>>.
    
    宏定义
    ~~~~~~~~~~~~~~~~~
    Each entry in the configuration `[macros]` section is a macro
    definition which can take one of the following forms:
    
    `<pattern>=<name>[<subslist]`::
            Inline macro definition.
    `<pattern>=#<name>[<subslist]`::
            Block macro definition.
    `<pattern>=+<name>[<subslist]`::
            System macro definition.
    `<pattern>`::
            Delete the existing macro with this `<pattern>`.
    
    `<pattern>` is a Python regular expression and `<name>` is the name of
    a markup template. If `<name>` is omitted then it is the value of the
    regular expression match group named 'name'.  The optional
    `[<subslist]` is a comma-separated list of substitution names enclosed
    in `[]` brackets, it sets the default substitutions for passthrough
    text, if omitted then no passthrough substitutions are performed.
    
    .Pattern named groups
    The following named groups can be used in macro `<pattern>` regular
    expressions and are available as markup template attributes:
    
    name::
      The macro name.
    
    target::
      The macro target.
    
    attrlist::
      The macro attribute list.
    
    passtext::
      Contents of this group are passed unmodified to the output subject
      only to 'subslist' substitutions.
    
    subslist::
      Processed as a comma-separated list of substitution names for
      'passtext' substitution, overrides the the macro definition
      'subslist'.
    
    .Here's what happens during macro substitution
    - Each contextually relevant macro 'pattern' from the `[macros]`
      section is matched against the input source line.
    - If a match is found the text to be substituted is loaded from a
      configuration markup template section named like
      `<name>-inlinemacro` or `<name>-blockmacro` (depending on the macro
      type).
    - Global and macro attribute list attributes are substituted in the
      macro's markup template.
    - The substituted template replaces the macro reference in the output
      document.
    
    
    表格
    ------
    The AsciiDoc table syntax looks and behaves like other delimited block
    types and supports standard <<X73,block configuration entries>>.
    Formatting is easy to read and, just as importantly, easy to enter.
    
    - Cells and columns can be formatted using built-in customizable styles.
    - Horizontal and vertical cell alignment can be set on columns and
      cell.
    - Horizontal and vertical cell spanning is supported.
    
    .Use tables sparingly
    *********************************************************************
    When technical users first start creating documents, tables (complete
    with column spanning and table nesting) are often considered very
    important. The reality is that tables are seldom used, even in
    technical documentation.
    
    Try this exercise: thumb through your library of technical books,
    you'll be surprised just how seldom tables are actually used, even
    less seldom are tables containing block elements (such as paragraphs
    or lists) or spanned cells. This is no accident, like figures, tables
    are outside the normal document flow -- tables are for consulting not
    for reading.
    
    Tables are designed for, and should normally only be used for,
    displaying column oriented tabular data.
    *********************************************************************
    
    表格样例
    ~~~~~~~~~~~~~~
    
    .Simple table
    [width="15%"]
    |=======
    |1 |2 |A
    |3 |4 |B
    |5 |6 |C
    |=======
    
    .AsciiDoc source
    ---------------------------------------------------------------------
    [width="15%"]
    |=======
    |1 |2 |A
    |3 |4 |B
    |5 |6 |C
    |=======
    ---------------------------------------------------------------------
    
    .Columns formatted with strong, monospaced and emphasis styles
    [width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"]
    |==========================
    |      2+|Columns 2 and 3
    |1       |Item 1  |Item 1
    |2       |Item 2  |Item 2
    |3       |Item 3  |Item 3
    |4       |Item 4  |Item 4
    |footer 1|footer 2|footer 3
    |==========================
    
    .AsciiDoc source
    ---------------------------------------------------------------------
    .An example table
    [width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"]
    |==========================
    |      2+|Columns 2 and 3
    |1       |Item 1  |Item 1
    |2       |Item 2  |Item 2
    |3       |Item 3  |Item 3
    |4       |Item 4  |Item 4
    |footer 1|footer 2|footer 3
    |==========================
    ---------------------------------------------------------------------
    
    .Horizontal and vertical source data
    [width="80%",cols="3,^2,^2,10",options="header"]
    |=========================================================
    |Date |Duration |Avg HR |Notes
    
    |22-Aug-08 |10:24 | 157 |
    Worked out MSHR (max sustainable heart rate) by going hard
    for this interval.
    
    |22-Aug-08 |23:03 | 152 |
    Back-to-back with previous interval.
    
    |24-Aug-08 |40:00 | 145 |
    Moderately hard interspersed with 3x 3min intervals (2min
    hard + 1min really hard taking the HR up to 160).
    
    |=========================================================
    
    Short cells can be entered horizontally, longer cells vertically.  The
    default behavior is to strip leading and trailing blank lines within a
    cell. These characteristics aid readability and data entry.
    
    .AsciiDoc source
    ---------------------------------------------------------------------
    .Windtrainer workouts
    [width="80%",cols="3,^2,^2,10",options="header"]
    |=========================================================
    |Date |Duration |Avg HR |Notes
    
    |22-Aug-08 |10:24 | 157 |
    Worked out MSHR (max sustainable heart rate) by going hard
    for this interval.
    
    |22-Aug-08 |23:03 | 152 |
    Back-to-back with previous interval.
    
    |24-Aug-08 |40:00 | 145 |
    Moderately hard interspersed with 3x 3min intervals (2min
    hard + 1min really hard taking the HR up to 160).
    
    |=========================================================
    ---------------------------------------------------------------------
    
    .A table with externally sourced CSV data
    [format="csv",cols="^1,4*2",options="header"]
    |===================================================
    ID,Customer Name,Contact Name,Customer Address,Phone
    include::customers.csv[]
    |===================================================
    
    .AsciiDoc source
    ---------------------------------------------------------------------
    [format="csv",cols="^1,4*2",options="header"]
    |===================================================
    ID,Customer Name,Contact Name,Customer Address,Phone
    \include::customers.csv[]
    |===================================================
    ---------------------------------------------------------------------
    
    
    .Cell spans, alignments and styles
    [cols="e,m,^,>s",width="25%"]
    |============================
    |1 >s|2 |3 |4
    ^|5 2.2+^.^|6 .3+<.>m|7
    ^|8
    |9 2+>|10
    |============================
    
    .AsciiDoc source
    ---------------------------------------------------------------------
    [cols="e,m,^,>s",width="25%"]
    |============================
    |1 >s|2 |3 |4
    ^|5 2.2+^.^|6 .3+<.>m|7
    ^|8
    |9 2+>|10
    |============================
    ---------------------------------------------------------------------
    
    [[X68]]
    表格数据输入格式
    ~~~~~~~~~~~~~~~~~~~~~~~~
    AsciiDoc table data can be 'psv', 'dsv' or 'csv' formatted.  The
    default table format is 'psv'.
    
    AsciiDoc 'psv' ('Prefix Separated Values') and 'dsv' ('Delimiter
    Separated Values') formats are cell oriented -- the table is treated
    as a sequence of cells -- there are no explicit row separators.
    
    - 'psv' prefixes each cell with a separator whereas 'dsv' delimits
      cells with a separator, that really the only difference (apart from
      different default separators).
    - 'psv' and 'dsv' separators are Python regular expressions.
    - The default 'psv' separator contains <<X84, cell specifier>> related
      named regular expression groups.
    - The default 'dsv' separator is `:|\n` (a colon or a line break).
    - 'psv' and 'dsv' cell separators can be escaped by preceding them
      with a backslash character.
    
    Here are four 'psv' cells (the second item spans two columns; the
    last contains an escaped separator):
    
      |One 2+|Two and three |A \| separator character
    
    'csv'  is the quasi-standard row oriented 'Comma Separated Values
    (CSV)' format commonly used to import and export spreadsheet and
    database data.
    
    [[X69]]
    Table attributes
    ~~~~~~~~~~~~~~~~
    Individual tables are customized by an optional <<X79,AttributeList>>
    preceding the table. Specify attributes when you want to change the
    default table format:
    
    format::
    'psv' (default), 'dsv' or 'csv' (See <<X68, Table Data Formats>>).
    
    separator::
    The cell separator. A Python regular expression ('psv' and 'dsv'
    formats) or a single character ('csv' format).
    
    frame::
    Defines the table border and can take the following values: 'topbot'
    (top and bottom), 'all' (all sides), 'none' and 'sides' (left and
    right sides). The default value is 'all'.
    
    grid::
    Defines which ruler lines are drawn between table rows and columns.
    The 'grid' attribute value can be any of the following values: 'none',
    'cols', 'rows' and 'all'. The default value is 'all'.
    
    align::
    Use the 'align' attribute to horizontally align the table on the
    page (works with HTML outputs only, has no effect on DocBook outputs).
    The following values are valid: 'left', 'right', and 'center'.
    
    float::
    Use the 'float' attribute to float the table 'left' or 'right' on the
    page (works with HTML outputs only, has no effect on DocBook outputs).
    Floating only makes sense in conjunction with the table 'width'
    attribute set to less than 100% (otherwise the table will take up all
    the available space).  'float' and 'align' attributes are mutually
    exclusive.  Use the `unfloat::[]` block macro to stop floating.
    
    halign::
    Use the 'halign' attribute to horizontally align all cells in a table.
    The following values are valid: 'left', 'right', and 'center'
    (defaults to 'left'). Overridden by <<X70,Column specifiers>>  and
    <<X84,Cell specifiers>>.
    
    valign::
    Use the 'valign' attribute to vertically align all cells in a table.
    The following values are valid: 'top', 'bottom', and 'middle'
    (defaults to 'top'). Overridden by <<X70,Column specifiers>>  and
    <<X84,Cell specifiers>>.
    
    options::
    The 'options' attribute can contain the following comma separated
    values: 'header', 'footer'. By default header and footer rows are
    omitted.
    
    cols::
    The 'cols' attribute is a comma separated list of <<X70,column
    specifiers>>. For example `cols="2<p,2*,4p,>"`.
    
    - If 'cols' is present it must specify all columns.
    - If the 'cols' attribute is not specified the number of columns is
      calculated as the number of data items in the *first line* of the
      table.
    - The degenerate form for the 'cols' attribute is an integer
      specifying the number of columns e.g. `cols=4`.
    
    width::
    The 'width' attribute is expressed as a percentage value
    ('"1%"'...'"99%"'). The width specifies the table width relative to
    the available width. HTML backends use this value to set the table
    width attribute. It's a bit more complicated with DocBook, see the
    <<X89,DocBook table widths>> sidebar.
    
    filter::
    The 'filter' attribute defines an external shell command that is
    invoked for each cell. The built-in 'asciidoc' table style is
    implemented using a filter.
    
    [[X89]]
    .DocBook table widths
    *********************************************************************
    The AsciiDoc docbook backend generates CALS tables. CALS tables do not
    support a table width attribute -- table width can only be controlled
    using absolute column widths. If the AsciiDoc table width attribute is
    specified the docbook backend emits absolute column widths (see
    calculated <<X72,markup attributes>> ); if no table width is specified
    proportional column widths are used and the table occupies all of the
    available width.
    
    Specifying fixed column widths not media independent because different
    presentation media have different physical characteristics e.g.
    printed paper vs. web browsers.  To get round this limitation 'DocBook
    XSL Stylesheets' have implemented
    http://www.sagehill.net/docbookxsl/Tables.html#TableWidth[processing
    instructions] for setting the table width as a percentage of the
    available width. AsciiDoc emits these processing instructions and, to
    facilitate their use, uses proportional column widths (by defaulting
    the AsciiDoc 'pageunits' attribute to '*'). To generate DocBook tables
    with fixed  widths set 'pageunits' to a CALS absolute unit such as
    'pt'.
    
    *********************************************************************
    
    [[X70]]
    Column Specifiers
    ~~~~~~~~~~~~~~~~~
    Column specifiers define how columns are rendered and appear in the
    table <<X69,cols attribute>>.  A column specifier consists of an
    optional column multiplier followed by optional alignment, width and
    style values and is formatted like:
    
      [<multiplier>*][<align>][<width>][<style>]
    
    - All components are optional. The multiplier must be first and the
      style last. The order of `<align>` or `<width>` is not important.
    - Column `<width>` can be either an integer proportional value (1...)
      or a percentage (1%...100%). The default value is 1. To ensure
      portability across different backends, there is no provision for
      absolute column widths (not to be confused with output column width
      <<X72,markup attributes>> which are available in both percentage and
      absolute units).
    - The '<align>' column alignment specifier is formatted like:
    
      [<horizontal>][.<vertical>]
    +
    Where `<horizontal>` and `<vertical>` are one of the following
    characters: `<`, `^` or `>` which represent `left`, `center` and
    `right` horizontal alignment or `top`, `middle` and `bottom` vertical
    alignment respectively.
    
    - A `<multiplier>` can be used to specify repeated columns e.g.
      `cols="4*<"` specifies four left-justified columns. Default value 1.
    - The `<style>` name specifies a <<X71,table style>> to used to markup
      column cells (you can use the full style names if you wish but the
      first letter is normally sufficient).
    - Column specific styles are not applied to 'header' row formatting.
    
    [[X84]]
    Cell Specifiers
    ~~~~~~~~~~~~~~~
    Cell specifiers allow individual cells in 'psv' formatted tables to be
    spanned, multiplied, aligned and styled.  Cell specifiers prefix 'psv'
    `|` delimiters and are formatted like:
    
      [<span>*|+][<align>][<style>]
    
    - '<span>' specifies horizontal and vertical cell spans ('+' operator) or
      the number of times the cell is replicated ('*' operator). '<span>'
      is formatted like:
    
      [<colspan>][.<rowspan>]
    +
    Where `<colspan>` and `<rowspan>` are integers specifying the number of
    columns and rows to span.
    
    - `<align>` specifies horizontal and vertical cell alignment an is the
      same as in <<X70,column specifiers>>.
    - A `<style>` value is the first letter of <<X71,table style>> name.
    
    For example, the following 'psv' formatted cell will span two columns
    and the text will be centered and emphasized:
    
      `2+^e| Cell text`
    
    [[X71]]
    表格样式
    ~~~~~~~~~~~~
    Table styles can be applied to the entire table (by setting the
    'style' attribute in the table's attribute list) or on a per column
    basis (by specifying the style in the table's <<X69,cols attribute>>).
    Tables come with the following predefined styles:
    
    default::
    The default style: AsciiDoc inline text formatting; blank lines are
    treated as paragraph breaks.
    
    emphasis::
    Like default but all text is emphasised.
    
    monospaced::
    Like default but all text is in a monospaced font.
    
    strong::
    Like default but all text is bold.
    
    asciidoc::
    With this style table cells can contain any of the AsciiDoc elements
    that are allowed inside document sections. This style runs asciidoc(1)
    as a filter to process cell contents. See also <<X83,Docbook table
    limitations>>.
    
    literal::
    No text formatting; monospaced font; all line breaks are retained
    (like AsciiDoc 'LiteralBlock').
    
    verse::
    Text formatting; all line breaks are retained (c.f. AsciiDoc delimited
    block 'verse' style).
    
    [[X72]]
    Markup attributes
    ~~~~~~~~~~~~~~~~~
    AsciiDoc makes a number of attributes available to table markup
    templates and tags. Both absolute and percentage width values are
    available. Column specific attributes are available when substituting
    the 'colspec' cell data tags.
    
    pageunits::
    DocBook backend only. Specifies table column absolute width units.
    Defaults to '*'.
    
    pagewidth::
    DocBook backend only. The nominal output page width in 'pageunit'
    units. Used to calculate CALS tables absolute column and table
    widths. Defaults to '425'.
    
    tableabswidth::
    Integer value calculated from 'width' and 'pagewidth' attributes.
    In 'pageunit' units.
    
    tablepcwidth::
    Table width expressed as a percentage of the available width. Integer
    value (0..100).
    
    colabswidth::
    Integer value calculated from 'cols' column width, 'width' and
    'pagewidth' attributes.  In 'pageunit' units.
    
    colpcwidth::
    Column width expressed as a percentage of the table width. Integer
    value (0..100).
    
    colcount::
    Total number of table columns.
    
    rowcount::
    Total number of table rows.
    
    halign::
    Horizontal cell content alignment: 'left', 'right' or 'center'.
    
    valign::
    Vertical cell content alignment: 'top', 'bottom' or 'middle'.
    
    colnumber, colstart::
    The number of the leftmost column occupied by the cell (1...).
    
    colend::
    The number of the rightmost column occupied by the cell (1...).
    
    colspan::
    Number of columns the cell should span.
    
    rowspan::
    Number of rows the cell should span (1...).
    
    morerows::
    Number of additional rows the cell should span (0...).
    
    表格嵌套
    ~~~~~~~~~~~~~
    An alternative table syntax using a '!' character instead of a '|'
    character is provided to allow a single level of table nesting.
    Columns containing nested tables must use the 'asciidoc' style. An
    example can be found in `./examples/website/newtables.txt`.
    
    [[X83]]
    DocBook table limitations
    ~~~~~~~~~~~~~~~~~~~~~~~~~
    Fully implementing tables is not trivial, some DocBook toolchains do
    better than others.  AsciiDoc HTML table outputs are rendered
    correctly in all the popular browsers -- if your DocBook generated
    tables don't look right compare them with the output generated by the
    AsciiDoc 'xhtml11' backend or try a different DocBook toolchain.  Here
    is a list of things to be aware of:
    
    - Although nested tables are not legal in DocBook 4 the FOP and
      dblatex toolchains will process them correctly.  If you use `a2x(1)`
      you will need to include the `--no-xmllint` option to suppress
      DocBook validation errors.
    +
    NOTE: Technically you can nest DocBook 4 tables one level using the
    'entrytbl' element, but not all toolchains process 'entrytbl'.
    
    - DocBook only allows a subset of block elements inside table cells so
      not all AsciiDoc elements produce valid DocBook inside table cells.
      If you get validation errors running `a2x(1)` try the `--no-xmllint`
      option, toolchains will often process nested block elements such as
      sidebar blocks and floating titles correctly.
    
    - Text formatting in cells using the 'monospaced' table style will
      raise validation errors because the DocBook 'literal' element was
      not designed to support formatted text (using the 'literal' element
      is a kludge on the part of AsciiDoc as there is no easy way to set
      the font style in DocBook.
    
    - Cell alignments are ignored for 'verse', 'literal' or 'asciidoc'
       table styles.
    
    
    [[X1]]
    Manpage Documents
    -----------------
    Sooner or later, if you program for a UNIX environment, you're going
    to have to write a man page.
    
    By observing a couple of additional conventions you can compose
    AsciiDoc files that will translate to a DocBook refentry (man page)
    document.  The resulting DocBook file can then be translated to the
    native roff man page format (or other formats).
    
    For example, the `asciidoc.1.txt` file in the AsciiDoc distribution
    `./doc` directory was used to generate both the
    `asciidoc.1.css-embedded.html` HTML file the `asciidoc.1` roff
    formatted `asciidoc(1)` man page.
    
    .Viewing and printing manpage files
    **********************************************************************
    Use the `man(1)` command to view the manpage file:
    
      $ man -l asciidoc.1
    
    To print a high quality man page to a postscript printer:
    
      $ man -l -Tps asciidoc.1 | lpr
    
    You could also create a PDF version of the man page by converting
    PostScript to PDF using `ps2pdf(1)`:
    
      $ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf
    
    The `ps2pdf(1)` command is included in the Ghostscript distribution.
    
    **********************************************************************
    
    To find out more about man pages view the `man(7)` manpage
    (`man 7 man` and `man man-pages` commands).
    
    
    Document Header
    ~~~~~~~~~~~~~~~
    A document Header is mandatory. The title line contains the man page
    name followed immediately by the manual section number in brackets,
    for example 'ASCIIDOC(1)'. The title name should not contain white
    space and the manual section number is a single digit optionally
    followed by a single character.
    
    The NAME Section
    ~~~~~~~~~~~~~~~~
    The first manpage section is mandatory, must be titled 'NAME' and must
    contain a single paragraph (usually a single line) consisting of a
    list of one or more comma separated command name(s) separated from the
    command purpose by a dash character. The dash must have at least one
    white space character on either side. For example:
    
      printf, fprintf, sprintf - print formatted output
    
    The SYNOPSIS Section
    ~~~~~~~~~~~~~~~~~~~~
    The second manpage section is mandatory and must be titled 'SYNOPSIS'.
    
    refmiscinfo attributes
    ~~~~~~~~~~~~~~~~~~~~~~
    In addition to the automatically created man page <<X60,intrinsic
    attributes>> you can assign DocBook
    http://www.docbook.org/tdg5/en/html/refmiscinfo.html[refmiscinfo]
    element 'source', 'version' and 'manual' values using AsciiDoc
    `{mansource}`, `{manversion}` and `{manmanual}` attributes
    respectively. This example is from the AsciiDoc header of a man page
    source file:
    
      :man source:   AsciiDoc
      :man version:  {revnumber}
      :man manual:   AsciiDoc Manual
    
    
    [[X78]]
    数学公式
    ---------------------
    The 'asciimath' and 'latexmath' <<X77,passthrough macros>> along with
    'asciimath' and 'latexmath'  <<X76,passthrough blocks>> provide a
    (backend dependent) mechanism for rendering mathematical formulas. You
    can use the following math markups:
    
    NOTE: The 'latexmath' macro used to include 'LaTeX Math' in DocBook
    outputs is not the same as the 'latexmath' macro used to include
    'LaTeX MathML' in XHTML outputs.  'LaTeX Math' applies to DocBook
    outputs that are processed by <<X31,dblatex>> and is normally used to
    generate PDF files.  'LaTeXMathML' is very much a subset of 'LaTeX
    Math' and applies to XHTML documents.
    
    LaTeX Math
    ~~~~~~~~~~
    ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf[LaTeX
    math] can be included in documents that are processed by
    <<X31,dblatex(1)>>.  Example inline formula:
    
      latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]
    
    For more examples see the http://www.methods.co.nz/asciidoc/[AsciiDoc
    website] or the distributed `doc/latexmath.txt` file.
    
    ASCIIMathML(ASCII数学标记)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~
    /////////////////////////////////////////////////////////////////////
    The older ASCIIMathML 1.47 version is used instead of version 2
    because:
    
    1. Version 2 doesn't work when embedded.
    2. Version 2 is much larger.
    /////////////////////////////////////////////////////////////////////
    
    http://www1.chapman.edu/~jipsen/mathml/asciimath.html[ASCIIMathML]
    formulas can be included in XHTML documents generated using the
    'xhtml11' backend. To enable ASCIIMathML support you must define the
    'asciimath' attribute, for example using the `-a asciimath`
    command-line option.  Example inline formula:
    
      asciimath:[`x/x={(1,if x!=0),(text{undefined},if x=0):}`]
    
    For more examples see the http://www.methods.co.nz/asciidoc/[AsciiDoc
    website] or the distributed `doc/asciimathml.txt` file.
    
    LaTeXMathML(Latex数学标记)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~
    /////////////////////////////////////////////////////////////////////
    There is an http://math.etsu.edu/LaTeXMathML/[extended LaTeXMathML
    version] by Jeff Knisley, in addition to a JavaScript file it requires
    the inclusion of a CSS file.
    /////////////////////////////////////////////////////////////////////
    
    'LaTeXMathML' allows LaTeX Math style formulas to be included in XHTML
    documents generated using the AsciiDoc 'xhtml11' backend.  AsciiDoc
    uses the
    http://www.maths.nottingham.ac.uk/personal/drw/lm.html[original
    LaTeXMathML] by Douglas Woodall.  'LaTeXMathML' is derived from
    ASCIIMathML and is for users who are more familiar with or prefer
    using LaTeX math formulas (it recognizes a subset of LaTeX Math, the
    differences are documented on the 'LaTeXMathML' web page).  To enable
    LaTeXMathML support you must define the 'latexmath' attribute, for
    example using the `-a latexmath` command-line option.  Example inline
    formula:
    
      latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$]
    
    For more examples see the http://www.methods.co.nz/asciidoc/[AsciiDoc
    website] or the distributed `doc/latexmathml.txt` file.
    
    There are more examples on the
    http://www.methods.co.nz/asciidoc/[AsciiDoc website].
    
    MathML(数学标记语言)
    ~~~~~~~~~~~~~~~~~~~
    http://www.w3.org/Math/[MathML] is a low level XML markup for
    mathematics. AsciiDoc has no macros for MathML but users familiar with
    this markup could use passthrough macros and passthrough blocks to
    include MathML in output documents.
    
    
    [[X7]]
    配置文件
    -------------------
    AsciiDoc source file syntax and output file markup is largely
    controlled by a set of cascading, text based, configuration files.  At
    runtime The AsciiDoc default configuration files are combined with
    optional user and document specific configuration files.
    
    配置文件格式
    ~~~~~~~~~~~~~~~~~~~~~~~~~
    Configuration files contain named sections. Each section begins with a
    section name in square brackets []. The section body consists of the
    lines of text between adjacent section headings.
    
    - Section names consist of one or more alphanumeric, underscore or
      dash characters and cannot begin or end with a dash.
    - Lines starting with a hash character "#" are treated as comments and
      ignored.
    - Same named sections and section entries override previously loaded
      sections and section entries (this is sometimes referred to as
      'cascading').  Consequently, downstream configuration files need
      only contain those sections and section entries that need to be
      overridden.
    
    TIP: When creating custom configuration files you only need to include
    the sections and entries that differ from the default configuration.
    
    TIP: The best way to learn about configuration files is to read the
    default configuration files in the AsciiDoc distribution in
    conjunction with asciidoc(1) output files. You can view configuration
    file load sequence by turning on the asciidoc(1) `-v` (`--verbose`)
    command-line option.
    
    AsciiDoc reserves the following section names for specific purposes:
    
    miscellaneous::
            Configuration options that don't belong anywhere else.
    attributes::
            Attribute name/value entries.
    specialcharacters::
            Special characters reserved by the backend markup.
    tags::
            Backend markup tags.
    quotes::
            Definitions for quoted inline character formatting.
    specialwords::
            Lists of words and phrases singled out for special markup.
    replacements, replacements2::
            Find and replace substitution definitions.
    specialsections::
            Used to single out special section names for specific markup.
    macros::
            Macro syntax definitions.
    titles::
            Heading, section and block title definitions.
    paradef-*::
            Paragraph element definitions.
    blockdef-*::
            DelimitedBlock element definitions.
    listdef-*::
            List element definitions.
    listtags-*::
            List element tag definitions.
    tabledef-*::
            Table element definitions.
    tabletags-*::
            Table element tag definitions.
    
    Each line of text in these sections is a 'section entry'. Section
    entries share the following syntax:
    
    name=value::
            The entry value is set to value.
    name=::
            The entry value is set to a zero length string.
    name!::
            The entry is undefined (deleted from the configuration). This
            syntax only applies to 'attributes' and 'miscellaneous'
            sections.
    
    .Section entry behavior
    - All equals characters inside the `name` must be escaped with a
      backslash character.
    - `name` and `value` are stripped of leading and trailing white space.
    - Attribute names, tag entry names and markup template section names
      consist of one or more alphanumeric, underscore or dash characters.
      Names should not begin or end with a dash.
    - A blank configuration file section (one without any entries) deletes
      any preceding section with the same name (applies to non-markup
      template sections).
    

    Miscellaneous section

    ~~~~~~~~~~~~~~~~~~~~~
    The optional `[miscellaneous]` section specifies the following
    `name=value` options:
    
    newline::
            Output file line termination characters. Can include any
            valid Python string escape sequences. The default value is
            `\r\n` (carriage return, line feed). Should not be quoted or
            contain explicit spaces (use `\x20` instead). For example:
    
            $ asciidoc -a 'newline=\n' -b docbook mydoc.txt
    
    outfilesuffix::
            The default extension for the output file, for example
            `outfilesuffix=.html`. Defaults to backend name.
    tabsize::
            The number of spaces to expand tab characters, for example
            `tabsize=4`. Defaults to 8. A 'tabsize' of zero suppresses tab
            expansion (useful when piping included files through block
            filters). Included files can override this option using the
            'tabsize' attribute.
    pagewidth, pageunits::
            These global table related options are documented in the
            <<X4,Table Configuration File Definitions>> sub-section.
    
    NOTE: `[miscellaneous]` configuration file entries can be set using
    the asciidoc(1) `-a` (`--attribute`) command-line option.
    
    标题部分
    ~~~~~~~~~~~~~~
    sectiontitle::
            Two line section title pattern. The entry value is a Python
            regular expression containing the named group 'title'.
    
    underlines::
            A comma separated list of document and section title underline
            character pairs starting with the section level 0 and ending
            with section level 4 underline. The default setting is:
    
            underlines="==","--","~~","^^","++"
    
    sect0...sect4::
            One line section title patterns. The entry value is a Python
            regular expression containing the named group 'title'.
    
    blocktitle::
            <<X42,BlockTitle element>> pattern.  The entry value is a
            Python regular expression containing the named group 'title'.
    
    subs::
            A comma separated list of substitutions that are performed on
            the document header and section titles. Defaults to 'normal'
            substitution.
    
    标签部分
    ~~~~~~~~~~~~
    The `[tags]` section contains backend tag definitions (one per
    line). Tags are used to translate AsciiDoc elements to backend
    markup.
    
    An AsciiDoc tag definition is formatted like
    `<tagname>=<starttag>|<endtag>`. For example:
    
      emphasis=<em>|</em>
    
    In this example asciidoc(1) replaces the | character with the
    emphasized text from the AsciiDoc input file and writes the result to
    the output file.
    
    Use the `{brvbar}` attribute reference if you need to include a | pipe
    character inside tag text.
    
    属性部分
    ~~~~~~~~~~~~~~~~~~
    The optional `[attributes]` section contains predefined attributes.
    
    If the attribute value requires leading or trailing spaces then the
    text text should be enclosed in quotation mark (") characters.
    
    To delete a attribute insert a `name!` entry in a downstream
    configuration file or use the asciidoc(1) `--attribute name!`
    command-line option (an attribute name suffixed with a `!` character
    deletes the attribute)
    
    Special Characters section
    ~~~~~~~~~~~~~~~~~~~~~~~~~~
    The `[specialcharacters]` section specifies how to escape characters
    reserved by the backend markup. Each translation is specified on a
    single line formatted like:
    
      special_character=translated_characters
    
    Special characters are normally confined to those that resolve
    markup ambiguity (in the case of SGML/XML markups the ampersand, less
    than and greater than characters).  The following example causes all
    occurrences of the `<` character to be replaced by `&lt;`.
    
      <=&lt;
    
    引用文本部分
    ~~~~~~~~~~~~~~~~~~~
    Quoting is used primarily for text formatting.  The `[quotes]` section
    defines AsciiDoc quoting characters and their corresponding backend
    markup tags.  Each section entry value is the name of a of a `[tags]`
    section entry. The entry name is the character (or characters) that
    quote the text.  The following examples are taken from AsciiDoc
    configuration files:
    
      [quotes]
      _=emphasis
    
      [tags]
      emphasis=<em>|</em>
    
    You can specify the left and right quote strings separately by
    separating them with a | character, for example:
    
      ``|''=quoted
    
    Omitting the tag will disable quoting, for example, if you don't want
    superscripts or subscripts put the following in a custom configuration
    file or edit the global `asciidoc.conf` configuration file:
    
      [quotes]
      ^=
      ~=
    
    <<X52,Unconstrained quotes>> are differentiated by prefixing the tag
    name with a hash character, for example:
    
      __=#emphasis
    
    .Quoted text behavior
    - Quote characters must be non-alphanumeric.
    - To minimize quoting ambiguity try not to use the same quote
      characters in different quote types.
    
    Special Words section
    ~~~~~~~~~~~~~~~~~~~~~
    The `[specialwords]` section is used to single out words and phrases
    that you want to consistently format in some way throughout your
    document without having to repeatedly specify the markup. The name of
    each entry corresponds to a markup template section and the entry
    value consists of a list of words and phrases to be marked up. For
    example:
    
      [specialwords]
      strongwords=NOTE: IMPORTANT:
    
      [strongwords]
      <strong>{words}</strong>
    
    The examples specifies that any occurrence of `NOTE:` or `IMPORTANT:`
    should appear in a bold font.
    
    Words and word phrases are treated as Python regular expressions: for
    example, the word `^NOTE:` would only match `NOTE:` if appeared at
    the start of a line.
    
    AsciiDoc comes with three built-in Special Word types:
    'emphasizedwords', 'monospacedwords' and 'strongwords', each has a
    corresponding (backend specific) markup template section. Edit the
    configuration files to customize existing Special Words and to add new
    ones.
    
    .Special word behavior
    - Word list entries must be separated by space characters.
    - Word list entries with embedded spaces should be enclosed in quotation (")
      characters.
    - A `[specialwords]` section entry of the form
      +name=word1{nbsp}[word2...]+ adds words to existing `name` entries.
    - A `[specialwords]` section entry of the form `name` undefines
      (deletes) all existing `name` words.
    - Since word list entries are processed as Python regular expressions
      you need to be careful to escape regular expression special
      characters.
    - By default Special Words are substituted before Inline Macros, this
      may lead to undesirable consequences. For example the special word
      `foobar` would be expanded inside the macro call
      `http://www.foobar.com[]`.  A possible solution is to emphasize
      whole words only by defining the word using regular expression
      characters, for example `\bfoobar\b`.
    - If the first matched character of a special word is a backslash then
      the remaining characters are output without markup i.e. the
      backslash can be used to escape special word markup.  For example
      the special word `\\?\b[Tt]en\b` will mark up the words `Ten` and
      `ten` only if they are not preceded by a backslash.
    
    [[X10]]
    Replacements section
    ~~~~~~~~~~~~~~~~~~~~
    `[replacements]` and `[replacements2]` configuration file entries
    specify find and replace text and are formatted like:
    
      find_pattern=replacement_text
    
    The find text can be a Python regular expression; the replace text can
    contain Python regular expression group references.
    
    Use Replacement shortcuts for often used macro references, for
    example (the second replacement allows us to backslash escape the
    macro name):
    
      NEW!=image:./images/smallnew.png[New!]
      \\NEW!=NEW!
    
    .Replacement behavior
    - The built-in replacements can be escaped with a backslash.
    - If the find or replace text has leading or trailing spaces then the
      text should be enclosed in quotation (") characters.
    - Since the find text is processed as a regular expression you need to
      be careful to escape regular expression special characters.
    - Replacements are performed in the same order they appear in the
      configuration file replacements section.
    
    标记模板段落
    ~~~~~~~~~~~~~~~~~~~~~~~~
    Markup template sections supply backend markup for translating
    AsciiDoc elements.  Since the text is normally backend dependent
    you'll find these sections in the backend specific configuration
    files. Template sections differ from other sections in that they
    contain a single block of text instead of per line 'name=value'
    entries. A markup template section body can contain:
    
    - Attribute references
    - System macro calls.
    - A document content placeholder
    
    The document content placeholder is a single | character and is
    replaced by text from the source element.  Use the `{brvbar}`
    attribute reference if you need a literal | character in the template.
    
    [[X27]]
    配置文件名称和本地化
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Configuration files have a `.conf` file name extension; they are
    loaded implicitly (using predefined file names and locations) or
    explicitly (using the asciidoc(1) `-f` (`--conf-file`) command-line
    option).
    
    Implicit configuration files are loaded from the following directories
    in the following order:
    
    1. The global configuration directory (normally `/etc/asciidoc` or
       `/usr/local/etc/asciidoc`) if it exists.
    2. The directory containing the asciidoc executable.
    3. The user's `$HOME/.asciidoc` directory (if it exists).
    4. The directory containing the AsciiDoc source file.
    
    The following implicit configuration files from each of the above
    locations are loaded in the following order:
    
    1. `asciidoc.conf`
    2. `<backend>.conf`
    3. `<backend>-<doctype>.conf`
    
    Where `<backend>` and `<doctype>` are values specified by the
    asciidoc(1) `-b` (`--backend`) and `-d` (`--doctype`) command-line
    options.
    
    Next, configuration files named like the source file will be
    automatically loaded if they are found in the source file directory.
    For example if the source file is `mydoc.txt` and the
    `--backend=html4` option is used then asciidoc(1) will look for
    `mydoc.conf` and `mydoc-html4.conf` in that order.
    
    Implicit configuration files that don't exist will be silently
    skipped.
    
    The user can explicitly specify additional configuration files using
    the asciidoc(1) `-f` (`--conf-file`) command-line option.  The `-f`
    option can be specified multiple times, in which case configuration
    files will be processed in the order they appear on the command-line.
    
    For example, when we translate our AsciiDoc document `mydoc.txt` with:
    
      $ asciidoc -f extra.conf mydoc.txt
    
    The last configuration file to load is the language configuration file
    `lang-<lang>.conf`. `<lang>` is the value of the AsciiDoc `lang`
    attribute (defaults to `en` (English)). You can set the `lang`
    attribute inside the AsciiDoc source file using an
    <<X18,AttributeEntry>> provided it is the first entry and provided it
    precedes the document header, for example:
    
      :lang: es
    
    Configuration files (if they exist) will be processed in the following
    order:
    
    1. First default global configuration files from the asciidoc program
       directory are loaded:
    
       asciidoc.conf
       xhtml11.conf
    
    2. Then, from the users home `~/.asciidoc` directory.  This is were
       you put customization specific to  your own asciidoc documents:
    
       asciidoc.conf
       xhtml11.conf
       xhtml11-article.conf
    
    3. Next from the source document project directory (the first three
       apply to all documents in the directory, the last two are specific
       to the mydoc.txt document):
    
       asciidoc.conf
       xhtml11.conf
       xhtml11-article.conf
       mydoc.conf
       mydoc-xhtml11.conf
    
    4. Finally the file specified by the `-f` command-line option is
       loaded:
    
       extra.conf
    
    TIP: Use the asciidoc(1) `-v` (`--verbose`) command-line option to see
    which configuration files are loaded and the order in which they are
    loaded.
    
    
    文件属性
    -------------------
    A document attribute is comprised of a 'name' and a textual 'value'
    and is used for textual substitution in AsciiDoc documents and
    configuration files. An attribute reference (an attribute name
    enclosed in braces) is replaced by its corresponding attribute
    value.
    
    There are four sources of document attributes (from highest to lowest
    precedence):
    
    - Command-line attributes.
    - AttributeEntry, AttributeList, Macro and BlockId elements.
    - Configuration file `[attributes]` sections.
    - Intrinsic attributes.
    
    Within each of these divisions the last processed entry takes
    precedence.
    
    IMPORTANT: If an attribute is not defined then the line containing the
    attribute reference is dropped. This property is used extensively in
    AsciiDoc configuration files to facilitate conditional markup
    generation.
    
    
    [[X18]]
    属性项
    -----------------
    The `AttributeEntry` block element allows document attributes to be
    assigned within an AsciiDoc document. Attribute entries are added to
    the global document attributes dictionary. The attribute name/value
    syntax is a single line like:
    
      :<name>: <value>
    
    For example:
    
      :Author Initials: JB
    
    This will set an attribute reference `{authorinitials}` to the value
    'JB' in the current document.
    
    To delete (undefine) an attribute use the following syntax:
    
      :<name>!:
    
    .AttributeEntry behavior
    - The attribute entry line begins with colon -- no white space allowed
      in left margin.
    - AsciiDoc converts the `<name>` to a legal attribute name (lower
      case, alphanumeric and dash characters only -- all other characters
      deleted). This allows more reader friendly text to be used.
    - Leading and trailing white space is stripped from the `<value>`.
    - If the `<value>` is blank then the corresponding attribute value is
      set to an empty string.
    - Attribute references contained in the entry `<value>` will be
      expanded.
    - By default AttributeEntry values are substituted for
      `specialcharacters` and `attributes` (see above), if you want to
      change or disable AttributeEntry substitution use the <<X77,pass:[]
      inline macro>> syntax.
    - Attribute entries in the document Header are available for header
      markup template substitution.
    - Attribute elements override configuration file and intrinsic
      attributes but do not override command-line attributes.
    
    Here are some more attribute entry examples:
    
    ---------------------------------------------------------------------
    AsciiDoc 用户手册
    ====================
    :author:    Stuart Rackham
    :email:     srackham@gmail.com
    :revdate:   April 23, 2004
    :revnumber: 5.1.1
    :keywords: linux, ralink, debian, wireless
    ---------------------------------------------------------------------
    
    Which creates these attributes:
    
      {author}, {firstname}, {lastname}, {authorinitials}, {email},
      {revdate}, {revnumber}, {keywords}
    
    The preceding example is equivalent to the standard AsciiDoc two line
    document header (actually it's a little bit different because of the
    addition of the `{keywords}` attribute).
    
    设置配置项
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    A variant of the Attribute Entry syntax allows configuration file
    entries to be set from within an AsciiDoc document:
    
      :<section_name>.<entry_name>: <entry_value>
    
    Where `<section_name>` is the configuration section name,
    `<entry_name>` is the name of the entry and `<entry_value>` is the
    optional entry value. This example sets the default labeled list style
    to 'horizontal':
    
      :listdef-labeled.style: horizontal
    
    It is exactly equivalent to a configuration file containing:
    
      [listdef-labeled]
      style=horizontal
    
    No substitution is performed on configuration file attribute entries.
    
    [[X62]]
    .Attribute entries promote clarity and eliminate repetition
    *********************************************************************
    URLs and file names in AsciiDoc macros are often quite long -- they
    break paragraph flow and readability suffers.  The problem is
    compounded by redundancy if the same name is used repeatedly.
    Attribute entries can be used to make your documents easier to read
    and write, here are some examples:
    
      :1:         http://freshmeat.net/projects/asciidoc/
      :homepage:  http://hg.sharesource.org/asciidoc/[AsciiDoc home page]
      :new:       image:./images/smallnew.png[]
      :footnote1: footnote:[A meaningless latin term]
    
      Using previously defined attributes: See the {1}[Freshmeat summary]
      or the {homepage} for something new {new}. Lorem ispum {footnote1}.
    
    .Note
    - The attribute entry definition must precede it's usage.
    - You are not limited to URLs or file names, entire macro calls or
      arbitrary lines of text can be abbreviated.
    - Shared attributes entries could be grouped into a separate file and
      <<X63,included>> in multiple documents.
    
    *********************************************************************
    
    
    [[X21]]
    属性列表
    ---------------
    An attribute list is a comma separated list of attribute values. The
    entire list is enclosed in square brackets.  Attribute lists are used
    to pass parameters to macros, blocks and inline quotes:
    
    - The list consists of zero or more positional attribute values
      followed by zero or more named attribute values.
    - Attribute values are enclosed in quotation mark (") characters.
    - If the attribute list only contains positional attribute values and
      the values contain no commas then quoting is unnecessary.
    
    Here are three examples (a single unquoted positional attribute; three
    unquoted attribute values; one positional attribute followed by two
    named attributes):
    
      [Hello]
      [quote, Bertrand Russell, The World of Mathematics (1956)]
      ["22 times", backcolor="#0e0e0e", options="noborders,wide"]
    
    .Attribute list behavior
    - If one or more attribute values contains a comma the all string
      values must be quoted (enclosed in quotation characters).
    - If the list contains any named or quoted attributes then all string
      attribute values must be quoted.
    - To include a quotation mark (") character in a quoted attribute
      value the the quotation mark must be escaped with a backslash.
    - List attributes take precedence over existing attributes.
    - List attributes can only be referenced in configuration file markup
      templates and tags, they are not available inside the document.
    - Attribute references are allowed inside attribute lists -- this is
      the only substitution performed on attribute lists.
    - Setting a named attribute to `None` undefines the attribute.
    - Positional attributes are referred to as `{1}`,`{2}`,`{3}`,...
    - Attribute `{0}` refers to the entire list (excluding the enclosing
      square brackets).
    - Attribute lists are evaluated as a list of Python function
      arguments.  If this fails or any of the items do not evaluate to a
      string, a number or None then all list items are treated as string
      literals.
    
    [[X75]]
    选项属性
    ~~~~~~~~~~~~~~~~~
    If the attribute list contains an attribute named `options` it is
    processed as a comma separated list of option names:
    
    - Each name generates an attribute named like `<option>-option` (where
      `<option>` is the option name) with an empty string value.  For
      example `[options="opt1,opt2,opt3"]` is equivalent to setting the
      following three attributes
      `[opt1-option="",opt2-option="",opt2-option=""]`.
    - If you define a an option attribute globally (for example with an
      <<X18,attribute entry>>) then it will apply to all elements in the
      document.
    - AsciiDoc implements a number of predefined options which are listed
      in the <<X74,Attribute Options 附录>>.
    
    宏属性列表
    ~~~~~~~~~~~~~~~~~~~~~
    Macros calls are suffixed with an attribute list. The list may be
    empty but it cannot be omitted. List entries are used to pass
    attribute values to macro markup templates.
    
    
    属性引用
    --------------------
    An attribute references is an attribute name (possibly followed by an
    additional parameters) enclosed in braces.  When an attribute
    reference is encountered it is evaluated and replaced by its
    corresponding text value.  If the attribute is undefined the line
    containing the attribute is dropped.
    
    There are three types of attribute reference: 'Simple', 'Conditional'
    and 'System'.
    
    .Attribute reference evaluation
    - You can suppress attribute reference expansion by placing a
      backslash character immediately in front of the opening brace
      character.
    - By default attribute references are not expanded in
      'LiteralParagraphs', 'ListingBlocks' or 'LiteralBlocks'.
    - Attribute substitution proceeds line by line in reverse line order.
    - Attribute reference evaluation is performed in the following order:
      'Simple' then 'Conditional' and finally 'System'.
    
    简单属性引用
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Simple attribute references take the form `{<name>}`. If the
    attribute name is defined its text value is substituted otherwise the
    line containing the reference is dropped from the output.
    
    条件属性引用
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Additional parameters are used in conjunction with the attribute name
    to calculate a substitution value. Conditional attribute references
    take the following forms:
    
    `{<name>=<value>}`::
            `<value>` is substituted if the attribute `<name>` is
            undefined otherwise its value is substituted. `<value>` can
            contain simple attribute references.
    
    `{<name>?<value>}`::
            `<value>` is substituted if the attribute `<name>` is defined
            otherwise an empty string is substituted.  `<value>` can
            contain simple attribute references.
    
    `{<name>!<value>}`::
            `<value>` is substituted if the attribute `<name>` is
            undefined otherwise an empty string is substituted.  `<value>`
            can contain simple attribute references.
    
    `{<name>#<value>}`::
            `<value>` is substituted if the attribute `<name>` is defined
            otherwise the undefined attribute entry causes the containing
            line to be dropped.  `<value>` can contain simple attribute
            references.
    
    `{<name>%<value>}`::
            `<value>` is substituted if the attribute `<name>` is not
            defined otherwise the containing line is dropped.  `<value>`
            can contain simple attribute references.
    
    `{<name>@<regexp>:<value1>[:<value2>]}`::
            `<value1>` is substituted if the value of attribute `<name>`
            matches the regular expression `<regexp>` otherwise `<value2>`
            is substituted. If attribute `<name>` is not defined the
            containing line is dropped. If `<value2>` is omitted an empty
            string is assumed. The values and the regular expression can
            contain simple attribute references.  To embed colons in the
            values or the regular expression escape them with backslashes.
    
    `{<name>$<regexp>:<value1>[:<value2>]}`::
            Same behavior as the previous ternary attribute except for
            the following cases:
    
            `{<name>$<regexp>:<value>}`;;
                    Substitutes `<value>` if `<name>` matches `<regexp>`
                    otherwise the result is undefined and the containing
                    line is dropped.
    
            `{<name>$<regexp>::<value>}`;;
                    Substitutes `<value>` if `<name>` does not match
                    `<regexp>` otherwise the result is undefined and the
                    containing line is dropped.
    
    条件属性的例子
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    Conditional attributes are mainly used in AsciiDoc configuration
    files -- see the distribution `.conf` files for examples.
    
    Attribute equality test::
      If `{backend}` is `docbook` or `xhtml11` the example evaluates to
      ``DocBook or XHTML backend'' otherwise it evaluates to ``some other
      backend'':
    
      {backend@docbook|xhtml11:DocBook or XHTML backend:some other backend}
    
    Attribute value map::
      This example maps the `frame` attribute values [`topbot`, `all`,
      `none`, `sides`] to [`hsides`, `border`, `void`, `vsides`]:
    
      {frame@topbot:hsides}{frame@all:border}{frame@none:void}{frame@sides:vsides}
    
    
    [[X24]]
    系统属性引用
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    System attribute references generate the attribute text value by
    executing a predefined action that is parametrized by a single
    argument. The syntax is `{<action>:<argument>}`.
    
    `{counter:<attrname>[:<seed>]}`::
            Increments the document attribute (if the attribute is
            undefined it is set to `1`). Returns the new attribute value.
    
            - Counters generate global (document wide) attributes.
            - The optional `<seed>` specifies the counter's initial value;
              it can be a number or a single letter; defaults to '1'.
            - `<seed>` can contain simple and conditional attribute
              references.
            - The 'counter' system attribute will not be executed if the
              containing line is dropped by the prior evaluation of an
              undefined attribute.
    
    `{eval:<expression>}`::
            Substitutes the result of the Python `<expression>`.
    
            - If `<expression>` evaluates to `None` or `False` the
              reference is deemed undefined and the line containing the
              reference is dropped from the output.
            - If the expression evaluates to `True` the attribute
              evaluates to an empty string.
            - `<expression>` can contain simple and conditional attribute
              references.
    
    `{eval3:<command>}`::
            Passthrough version of `{eval:<expression>}` -- the generated
            output is written directly to the output without any further
            substitutions.
    
    `{include:<filename>}`::
            Substitutes contents of the file named `<filename>`.
    
            - The included file is read at the time of attribute
              substitution.
            - If the file does not exist a warning is emitted and the line
              containing the reference is dropped from the output file.
            - Tabs are expanded based on the current 'tabsize' attribute
              value.
    
    `{set:<attrname>[!][:<value>]}`::
            Sets or unsets document attribute. Normally only used in
            configuration file markup templates (use
            <<X18,AttributeEntries>> in AsciiDoc documents).
    
            - If the attribute name is followed by an exclamation mark
              the attribute becomes undefined.
            - If `<value>` is omitted the attribute is set to a blank
              string.
            - `<value>` can contain simple and conditional attribute
              references.
            - Returns a blank string unless the attribute is undefined in
              which case the return value is undefined and the enclosing
              line will be dropped.
    
    `{sys:<command>}`::
            Substitutes the stdout generated by the execution of the shell
            `<command>`.
    
    `{sys2:<command>}`::
            Substitutes the stdout and stderr generated by the execution
            of the shell `<command>`.
    
    `{sys3:<command>}`::
            Passthrough version of `{sys:<command>}` -- the generated
            output is written directly to the output without any further
            substitutions.
    
    .System reference behavior
    - System attribute arguments can contain non-system attribute
      references.
    - Closing brace characters inside system attribute arguments must be
      escaped them with a backslash.
    
    [[X60]]
    内置的属性
    --------------------
    Intrinsic attributes are simple attributes that are created
    automatically from AsciiDoc document header parameters, asciidoc(1)
    command-line arguments, execution parameters along with attributes
    defined in the default configuration files.  Here's the list of
    predefined intrinsic attributes:
    
      {amp}                 ampersand (&) character
      {asciidoc-dir}        the asciidoc(1) application directory
      {asciidoc-file}       the full path name of the asciidoc(1) script
      {asciidoc-version}    the version of asciidoc(1)
      {author}              author's full name
      {authored}            empty string '' if {author} or {email} defined,
      {authorinitials}      author initials (from document header)
      {backend-<backend>}   empty string ''
      {<backend>-<doctype>} empty string ''
      {backend}             document backend specified by `-b` option
      {backslash}           backslash character
      {basebackend-<base>}  empty string ''
      {basebackend}         html or docbook
      {brvbar}              broken vertical bar (|) character
      {revdate}             document revision date (from document header)
      {docdate}             document last modified date
      {doctime}             document last modified time
      {docname}             document file name without extension
      {docfile}             document file name  (note 5)
      {docdir}              document input directory name  (note 5)
      {doctitle}            document title (from document header)
      {doctype-<doctype>}   empty string ''
      {doctype}             document type specified by `-d` option
      {email}               author's email address (from document header)
      {empty}               empty string ''
      {encoding}            specifies input and output encoding
      {filetype-<fileext>}  empty string ''
      {filetype}            output file name file extension
      {firstname}           author first name (from document header)
      {gt}                  greater than (>) character
      {id}                  running block id generated by BlockId elements
      {indir}               input file directory name (note 2,5)
      {infile}              input file name (note 2,5)
      {lastname}            author last name (from document header)
      {level}               title level 1..4 (in section titles)
      {listindex}           the list index (1..) of the most recent list item
      {localdate}           the current date
      {localtime}           the current time
      {lt}                  less than (<) character
      {manname}             manpage name (defined in NAME section)
      {manpurpose}          manpage (defined in NAME section)
      {mantitle}            document title minus the manpage volume number
      {manvolnum}           manpage volume number (1..8) (from document header)
      {middlename}          author middle name (from document header)
      {nbsp}                Non-breaking space entity
      {outdir}              document output directory name (note 2)
      {outfile}             output file name (note 2)
      {reftext}             running block xreflabel generated by BlockId elements
      {revnumber}           document revision number (from document header)
      {sectnum}             formatted section number (in section titles)
      {showcomments}        send comment lines to the output
      {title}               section title (in titled elements)
      {two_colons}          Two colon characters
      {two_semicolons}      Two semicolon characters
      {user-dir}            the ~/.asciidoc directory (if it exists)
      {verbose}             defined as '' if --verbose command option specified
    
    .NOTES
    1. Intrinsic attributes are global so avoid defining custom attributes
       with the same names.
    
    2. `{outfile}`, `{outdir}`, `{infile}`, `{indir}` attributes are
       effectively read-only (you can set them but it won't affect the
       input or output file paths).
    
    3. See also the <<X33,xhtml11>> subsection for attributes that relate
       to AsciiDoc XHTML file generation.
    
    4. The entries that translate to blank strings are designed to be used
       for conditional text inclusion. You can also use the `ifdef`,
       `ifndef` and `endif` System macros for conditional inclusion.
       footnote:[Conditional inclusion using `ifdef` and `ifndef` macros
       differs from attribute conditional inclusion in that the former
       occurs when the file is read while the latter occurs when the
       contents are written.]
    
    5. `{docfile}` and `{docdir}` refer to root document specified on
       the asciidoc(1) command-line; `{infile}` and `{indir}` refer to
       the current input file which may be the root document or an
       included file. While the input is being read from the standard
       input (`stdin`) these attributes are undefined.
    
    [[X73]]
    块元素定义
    -------------------------
    The syntax and behavior of Paragraph, DelimitedBlock, List and Table
    block elements is determined by block definitions contained in
    <<X7,AsciiDoc configuration file>> sections.
    
    Each definition consists of a section title followed by one or more
    section entries. Each entry defines a block parameter controlling some
    aspect of the block's behavior. Here's an example:
    
    ---------------------------------------------------------------------
    [blockdef-listing]
    delimiter=^-{4,}$
    template=listingblock
    presubs=specialcharacters,callouts
    ---------------------------------------------------------------------
    
    AsciiDoc Paragraph, DelimitedBlock, List and Table block elements
    share a common subset of configuration file parameters:
    
    delimiter::
      A Python regular expression that matches the first line of a block
      element -- in the case of DelimitedBlocks it also matches the last
      line. Table elements don't have an explicit delimiter -- they
      synthesize their delimiters at runtime.
    
    template::
      The name of the configuration file markup template section that will
      envelope the block contents. The pipe | character is substituted for
      the block contents. List elements use a set of (list specific) tag
      parameters instead of a single template.
    
    options::
      A comma delimited list of element specific option names. In addition
      to being used internally, options are available during markup tag
      and template substitution as attributes with an empty string value
      named like `<option>-option` (where `<option>` is the option name).
    
    subs, presubs, postsubs::
      * 'presubs' and 'postsubs' are lists of comma separated substitutions that are
        performed on the block contents. 'presubs' is applied first,
        'postsubs' (if specified) second.
    
      * 'subs' is an alias for 'presubs'.
    
      * If a 'filter' is allowed (Paragraphs, DelimitedBlocks and Tables)
        and has been specified then 'presubs' and 'postsubs' substitutions
        are performed before and after the filter is run respectively.
    
      * Allowed values: 'specialcharacters', 'quotes', 'specialwords',
        'replacements', 'macros', 'attributes', 'callouts'.
    
      * The following composite values are also allowed:
    
        'none';;
            No substitutions.
        'normal';;
            The following substitutions:
            'specialcharacters','quotes','attributes','specialwords',
            'replacements','macros'.
        'verbatim';;
            'specialcharacters' and 'callouts' substitutions.
    
      * 'normal' and 'verbatim' substitutions can be redefined by with
        `subsnormal` and `subsverbatim` entries in a configuration file
        `[miscellaneous]` section.
    
      * The substitutions are processed in the order in which they are
        listed and can appear more than once.
    
    filter::
      This optional entry specifies an executable shell command for
      processing block content (Paragraphs, DelimitedBlocks and Tables).
      The filter command can contain attribute references.
    
    posattrs::
      Optional comma separated list of positional attribute names. This
      list maps positional attributes (in the block's <<X21,attribute
      list>>) to named block attributes. The following example, from the
      QuoteBlock definition, maps the first and section positional
      attributes:
    
      posattrs=attribution,citetitle
    
    style::
      This optional parameter specifies the default style name.
    
    
    <stylename>-style::
      Optional style definition (see <<X23,Styles>> below).
    
    The following block parameters behave like document attributes and can
    be set in block attribute lists and style definitions: 'template',
    'options', 'subs', 'presubs', 'postsubs', 'filter'.
    
    [[X23]]
    样式
    ~~~~~~
    A style is a set of block attributes bundled as a single named
    attribute. The following example defines a style named 'verbatim':
    
      verbatim-style=template="literalblock",subs="verbatim"
    
    - All style parameter names must be suffixed with `-style` and the
      style parameter value is in the form of a list of <<X21,named
      attributes>>.
    - Multi-item style attributes ('subs','presubs','postsubs','posattrs')
      must be specified using Python tuple syntax rather than a simple
      list of values as they in separate entries e.g.
      `postsubs=("callouts",)` not `postsubs="callouts"`.
    
    段落
    ~~~~~~~~~~
    Paragraph translation is controlled by `[paradef*]` configuration file
    section entries. Users can define new types of paragraphs and modify
    the behavior of existing types by editing AsciiDoc configuration
    files.
    
    Here is the shipped Default paragraph definition:
    
    --------------------------------------------------------------------
    [paradef-default]
    delimiter=(?P<text>\S.*)
    template=paragraph
    --------------------------------------------------------------------
    
    The Default paragraph definition has a couple of special properties:
    
    1. It must exist and be defined in a configuration file section named
       `[paradef-default]`.
    2. Irrespective of its position in the configuration files default
       paragraph document matches are attempted only after trying all
       other paragraph types.
    
    Paragraph specific block parameter notes:
    
    delimiter::
      This regular expression must contain the named group 'text' which
      matches the text on the first line.  Paragraphs are terminated by a
      blank line, the end of file, or the start of a DelimitedBlock.
    
    options::
      The 'listelement' option specifies that paragraphs of this type will
      automatically be considered part of immediately preceding list
      items.
    
    .Paragraph processing proceeds as follows:
    1. The paragraph text is aligned to the left margin.
    2. Optional 'presubs' inline substitutions are performed on the
       paragraph text.
    3. If a filter command is specified it is executed and the paragraph
       text piped to its standard input; the filter output replaces the
       paragraph text.
    4. Optional 'postsubs' inline substitutions are performed on the
       paragraph text.
    5. The paragraph text is enveloped by the paragraph's markup template
       and written to the output file.
    
    独立的块
    ~~~~~~~~~~~~~~~~
    DelimitedBlock 'options' values are:
    
    sectionbody::
        The block contents are processed as a SectionBody.
    
    skip::
        The block is treated as a comment (see <<X26,CommentBlocks>>).
    
    'presubs', 'postsubs' and 'filter' entries are meaningless when
    'sectionbody' or 'skip' options are set.
    
    DelimitedBlock processing proceeds as follows:
    
    1. Optional 'presubs' substitutions are performed on the block
       contents.
    2. If a filter is specified it is executed and the block's contents
       piped to its standard input. The filter output replaces the block
       contents.
    3. Optional 'postsubs' substitutions are performed on the block
       contents.
    4. The block contents is enveloped by the block's markup template and
       written to the output file.
    
    TIP: Attribute expansion is performed on the block filter command
    before it is executed, this is useful for passing arguments to the
    filter.
    
    列表
    ~~~~~
    List behavior and syntax is determined by `[listdef*]` configuration
    file sections. The user can change existing list behavior and add new
    list types by editing configuration files.
    
    List specific block definition notes:
    
    type::
      This is either 'bulleted','numbered','labeled' or 'callout'.
    
    delimiter::
      A Python regular expression that matches the first line of a
      list element entry. This expression can contain the named groups
      'text' (bulleted groups), 'index' and 'text' (numbered lists),
      'label' and 'text' (labeled lists).
    
    tags::
      The `<name>` of the `[listtags-<name>]` configuration file section
      containing list markup tag definitions.  The tag entries ('list',
      'entry', 'label', 'term', 'text') map the AsciiDoc list structure to
      backend markup; see the 'listtags' sections in the AsciiDoc
      distributed backend `.conf` configuration files for examples.
    
    表格
    ~~~~~~
    Table behavior and syntax is determined by `[tabledef*]` and
    `[tabletags*]` configuration file sections. The user can change
    existing table behavior and add new table types by editing
    configuration files.  The following `[tabledef*]` section entries
    generate table output markup elements:
    
    comspec::
      The table 'comspec' tag definition.
    
    headrow, footrow, bodyrow::
      Table header, footer and body row tag definitions. 'headrow' and
      'footrow' table definition entries default to 'bodyrow' if
      they are undefined.
    
    headdata, footdata, bodydata::
      Table header, footer and body data tag definitions. 'headdata' and
      'footdata' table definition entries default to 'bodydata' if they
      are undefined.
    
    paragraph::
      If the 'paragraph' tag is specified then blank lines in the cell
      data are treated as paragraph delimiters and marked up using this
      tag.
    
    [[X4]]
    Table behavior is also influenced by the following `[miscellaneous]`
    configuration file entries:
    
    pagewidth::
      This integer value is the printable width of the output media. See
      <<X69,table attributes>>.
    
    pageunits::
      The units of width in output markup width attribute values.
    
    .Table definition behavior
    - The output markup generation is specifically designed to work with
      the HTML and CALS (DocBook) table models, but should be adaptable to
      most XML table schema.
    - Table definitions can be ``mixed in'' from multiple cascading
      configuration files.
    - New table definitions inherit the default table and table tags
      definitions (`[tabledef-default]` and `[tabletags-default]`) so you
      only need to override those conf file entries that require
      modification.
    
    
    [[X59]]
    过滤器
    -------
    Filters are external shell commands used to process Paragraph and
    DelimitedBlock content; they are specified in configuration file
    Paragraph and DelimitedBlock definitions.
    
    There's nothing special about the filters, they're just standard UNIX
    filters: they read text from the standard input, process it, and write
    to the standard output.
    
    Attribute substitution is performed on the filter command prior to
    execution -- attributes can be used to pass parameters from the
    AsciiDoc source document to the filter.
    
    WARNING: Filters can potentially generate unsafe output. Before
    installing a filter you should verify that it can't be coerced into
    generating malicious output or exposing sensitive information.
    
    过滤器搜索路径
    ~~~~~~~~~~~~~~~~~~~
    If the filter command does not specify a directory path then
    asciidoc(1) searches for the command:
    
    - First it looks in the user's `$HOME/.asciidoc/filters` directory.
    - Next the `/etc/asciidoc/filters` directory is searched.
    - Then it looks in the asciidoc(1) `./filters` directory.
    - Finally it relies on the executing shell to search the environment
      search path (`$PATH`).
    
    Sub-directories are also included in the searches -- standard practice
    is to install each filter in it's own sub-directory with the same name
    as the filter's style definition. For example the music filter's style
    name is 'music' so it's configuration and filter files are stored in
    the `filters/music` directory.
    
    过滤器配置文件
    ~~~~~~~~~~~~~~~~~~~~~~~~~~
    Filters are normally accompanied by a configuration file containing a
    Paragraph or DelimitedBlock definition along with corresponding markup
    templates.
    
    While it is possible to create new Paragraph or DelimitedBlock
    definitions the preferred way to implement a filter is to add a
    <<X23,style>> to the existing Paragraph and ListingBlock definitions
    (all filters shipped with AsciiDoc use this technique). The filter is
    applied to the paragraph or delimited block by preceding it with an
    attribute list: the first positional attribute is the style name,
    remaining attributes are normally filter specific parameters.
    
    asciidoc(1) auto-loads all `.conf` files found in the filter search
    paths (see previous section).
    
    [[X56]]
    代码过滤
    ~~~~~~~~~~~
    AsciiDoc comes with a toy filter for highlighting source code keywords
    and comments.  See also the `./filters/code/code-filter-readme.txt`
    file.
    
    NOTE: This filter primarily to demonstrate how to write a filter --
    it's much to simplistic to be passed off as a code syntax highlighter.
    If you want a full featured multi-language highlighter use the
    <<X57,Source Code Highlighter Filter>>.
    
    [listing]
    .....................................................................
    .Code filter example
    [code,python]
    ----------------------------------------------
    ''' A multi-line
        comment.'''
    def sub_word(mo):
        ''' Single line comment.'''
        word = mo.group('word')   # Inline comment
        if word in keywords[language]:
            return quote + word + quote
        else:
            return word
    ----------------------------------------------
    .....................................................................
    
    Outputs:
    
    .Code filter example
    [code,python]
    ----------------------------------------------
    ''' A multi-line
        comment.'''
    def sub_word(mo):
        ''' Single line comment.'''
        word = mo.group('word')   # Inline comment
        if word in keywords[language]:
            return quote + word + quote
        else:
            return word
    ----------------------------------------------
    
    [[X57]]
    源码高亮过滤器
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    A
    http://www.methods.co.nz/asciidoc/source-highlight-filter.html[source
    code highlighter filter] can be found in the AsciiDoc distribution
    `./filters` directory.
    
    [[X58]]
    音乐过滤器
    ~~~~~~~~~~~~
    A http://www.methods.co.nz/asciidoc/music-filter.html[music filter] is
    included in the distribution `./filters` directory. It translates
    music in http://lilypond.org/[LilyPond] or
    http://abcnotation.org.uk/[ABC] notation to standard Western classical
    notation in the form of a trimmed PNG image which is automatically
    inserted into the output document.
    
    
    [[X12]]
    转换 DocBook 到其他文件格式
    ----------------------------------------
    DocBook files are validated, parsed and translated by a combination of
    applications collectively called a DocBook 'tool chain'. The function
    of a tool chain is to read the DocBook markup (produced by AsciiDoc)
    and transform it to a presentation format (for example HTML, PDF, HTML
    Help, DVI, PostScript, LaTeX).
    
    A wide range of user output format requirements coupled with a choice
    of available tools and stylesheets results in many valid tool chain
    combinations.
    
    [[X43]]
    a2x 工具链封装
    ~~~~~~~~~~~~~~~~~~~~~
    One of the biggest hurdles for new users is installing, configuring
    and using a DocBook XML toolchain. `a2x(1)` can help -- it's a
    toolchain wrapper command that will generate XHTML (chunked and
    unchunked), PDF, DVI, PS, LaTeX, man page, HTML Help and text file
    outputs from an AsciiDoc text file.  a2x(1) does all the grunt work
    associated with generating and sequencing the toolchain commands and
    managing intermediate and output files.  a2x(1) also optionally
    deploys admonition and navigation icons and a CSS stylesheet. See the
    `a2x(1)` man page for more details. All you need is
    <<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and optionally:
    <<X31,dblatex>> or <<X14,FOP>> (if you want PDF); `w3m(1)` or
    `lynx(1)` (if you want text).
    
    The following examples generate `doc/source-highlight-filter.pdf` from
    the AsciiDoc `doc/source-highlight-filter.txt` source file. The first
    example uses `dblatex(1)` (the default PDF generator) the second
    example forces FOP to be used:
    
      $ a2x -f pdf doc/source-highlight-filter.txt
      $ a2x -f pdf --fop doc/source-highlight-filter.txt
    
    See the `a2x(1)` man page for details.
    
    TIP: Use the `--verbose` command-line option to view executed
    toolchain commands.
    
    HTML 生成
    ~~~~~~~~~~~~~~~
    AsciiDoc produces nicely styled HTML directly without requiring a
    DocBook toolchain but there are also advantages in going the DocBook
    route:
    
    - HTML from DocBook includes automatically generated indexes, tables
      of contents, footnotes, lists of figures and tables.
    - DocBook toolchains can also (optionally) generate separate (chunked)
      linked HTML pages for each document section.
    - Toolchain processing performs link and document validity checks.
    - If the DocBook 'lang' attribute is set then things like table of
      contents, figure and table captions and admonition captions will be
      output in the specified language (setting the AsciiDoc 'lang'
      attribute sets the DocBook 'lang' attribute).
    
    On the other hand, HTML output directly from AsciiDoc is much faster,
    is easily customized and can be used in situations where there is no
    suitable DocBook toolchain (see the
    http://www.methods.co.nz/asciidoc/[AsciiDoc website] for example).
    
    PDF 生成
    ~~~~~~~~~~~~~~
    There are two commonly used tools to generate PDFs from DocBook,
    <<X31,dblatex>> and <<X14,FOP>>.
    
    .dblatex or FOP?
    - 'dblatex' is easier to install, there's zero configuration
      required and no Java VM to install -- it just works out of the box.
    - 'dblatex' source code highlighting and numbering is superb.
    - 'dblatex' is easier to use as it converts DocBook directly to PDF
      whereas before using 'FOP' you have to convert DocBook to XML-FO
      using <<X13,DocBook XSL Stylesheets>>.
    - 'FOP' is more feature complete (for example, callouts are processed
      inside literal layouts) and arguably produces nicer looking output.
    
    HTML Help 生成
    ~~~~~~~~~~~~~~~~~~~~
    . Convert DocBook XML documents to HTML Help compiler source files
      using <<X13,DocBook XSL Stylesheets>> and <<X40,xsltproc(1)>>.
    . Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help
      (`.chm`) files using the <<X67,Microsoft HTML Help Compiler>>.
    

    工具链组件摘要

    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    AsciiDoc::
        Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files.
    
    [[X13]]http://docbook.sourceforge.net/projects/xsl/[DocBook XSL Stylesheets]::
      These are a set of XSL stylesheets containing rules for converting
      DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
      The stylesheets are used in conjunction with an XML parser such as
      <<X40,xsltproc(1)>>.
    
    [[X40]]http://www.xmlsoft.org[xsltproc]::
      An XML parser for applying XSLT stylesheets (in our case the
      <<X13,DocBook XSL Stylesheets>>) to XML documents.
    
    [[X31]]http://dblatex.sourceforge.net/[dblatex]::
      Generates PDF, DVI, PostScript and LaTeX formats directly from
      DocBook source via the intermediate LaTeX typesetting language --
      uses <<X13,DocBook XSL Stylesheets>>, <<X40,xsltproc(1)>> and
      `latex(1)`.
    
    [[X14]]http://xml.apache.org/fop/[FOP]::
      The Apache Formatting Objects Processor converts XSL-FO (`.fo`)
      files to PDF files.  The XSL-FO files are generated from DocBook
      source files using <<X13,DocBook XSL Stylesheets>> and
      <<X40,xsltproc(1)>>.
    
    [[X67]]Microsoft Help Compiler::
      The Microsoft HTML Help Compiler (`hhc.exe`) is a command-line tool
      that converts HTML Help source files to a single HTML Help (`.chm`)
      file. It runs on MS Windows platforms and can be downloaded from
      http://www.microsoft.com.
    
    AsciiDoc dblatex 配置文件
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    The AsciiDoc distribution `./dblatex` directory contains
    `asciidoc-dblatex.xsl` (customized XSL parameter settings) and
    `asciidoc-dblatex.sty` (customized LaTeX settings). These are examples
    of optional <<X31,dblatex>> output customization and are used by
    <<X43,a2x(1)>>.
    
    AsciiDoc DocBook XSL 样式表驱动
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    You will have noticed that the distributed HTML and HTML Help
    documentation files (for example `./doc/asciidoc.html`) are not the
    plain outputs produced using the default 'DocBook XSL Stylesheets'
    configuration.  This is because they have been processed using
    customized DocBook XSL Stylesheets along with (in the case of HTML
    outputs) the custom `./stylesheets/docbook.css` CSS stylesheet.
    
    You'll find the customized DocBook XSL drivers along with additional
    documentation in the distribution `./docbook-xsl` directory. The
    examples that follow are executed from the distribution documentation
    (`./doc`) directory.
    
    `common.xsl`::
        Shared driver parameters.  This file is not used directly but is
        included in all the following drivers.
    
    `chunked.xsl`::
        Generate chunked XHTML (separate HTML pages for each document
        section) in the `./doc/chunked` directory. For example:
    
        $ python ../asciidoc.py -b docbook asciidoc.txt
        $ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml
    
    `fo.xsl`::
        Generate XSL Formatting Object (`.fo`) files for subsequent PDF
        file generation using FOP. For example:
    
        $ python ../asciidoc.py -b docbook article.txt
        $ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
        $ fop.sh article.fo article.pdf
    
    `htmlhelp.xsl`::
        Generate Microsoft HTML Help source files for the MS HTML Help
        Compiler in the `./doc/htmlhelp` directory. This example is run on
        MS Windows from a Cygwin shell prompt:
    
        $ python ../asciidoc.py -b docbook asciidoc.txt
        $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
        $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
    
    `manpage.xsl`::
        Generate a `roff(1)` format UNIX man page from a DocBook XML
        'refentry' document. This example generates an `asciidoc.1` man
        page file:
    
        $ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
        $ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml
    
    `xhtml.xsl`::
        Convert a DocBook XML file to a single XHTML file. For example:
    
        $ python ../asciidoc.py -b docbook asciidoc.txt
        $ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html
    
    If you want to see how the complete documentation set is processed
    take a look at the A-A-P script `./doc/main.aap`.
    
    
    生成纯文本文件
    ---------------------------
    AsciiDoc does not have a text backend (for most purposes AsciiDoc
    source text is fine), however you can convert AsciiDoc text files to
    formatted text using the AsciiDoc <<X43,a2x(1)>> toolchain wrapper
    utility.
    
    
    XML 和字符设定
    ----------------------
    The default XML character set `UTF-8` is used when AsciiDoc generates
    DocBook files but this can be changed by setting the `xmldecl` entry
    in the `[attributes]` section of the `docbook.conf` file or by
    composing your own configuration file `[header]` section).
    
    TIP: If you get an 'undefined entity' error when processing DocBook
    files you'll may find that you've used an undefined HTML character
    entity.  An easy (although inelegant) fix is to use the character's
    character code instead of its symbolic name (for example use `&#160;`
    instead of `&nbsp;`).
    
    If your system has been configured with an XML catalog you may find a
    number of entity sets are already automatically included.
    
    PDF 字体
    ~~~~~~~~~
    The Adobe PDF Specification states that the following 14 fonts should
    be available to every PDF reader: Helvetica (normal, bold, italic,
    bold italic), Times (normal, bold, italic, bold italic), Courier
    (normal, bold, italic, bold italic), Symbol and ZapfDingbats.
    Non-standard fonts should be embedded in the distributed document.
    
    
    [[X36]]
    帮助命令
    -------------
    The asciidoc(1) command has a `--help` option which prints help topics
    to stdout. The default topic summarizes asciidoc(1) usage:
    
      $ asciidoc --help
    
    To print a list of help topics:
    
      $ asciidoc --help=topics
    
    To print a help topic specify the topic name as a command argument.
    Help topic names can be shortened so long as they are not ambiguous.
    Examples:
    
      $ asciidoc --help=manpage
      $ asciidoc -hm              # Short version of previous example.
      $ asciidoc --help=syntax
      $ asciidoc -hs              # Short version of previous example.
    
    自定义帮助
    ~~~~~~~~~~~~~~~~
    To change, delete or add your own help topics edit a help
    configuration file.  The help file name `help-<lang>.conf` is based on
    the setting of the `lang` attribute, it defaults to `help.conf`
    (English).  The <<X27,help file location>> will depend on whether you
    want the topics to apply to all users or just the current user.
    
    The help topic files have the same named section format as other
    <<X7,configuration files>>. The `help.conf` files are stored in the
    same locations and loaded in the same order as other configuration
    files.
    
    When the `--help` command-line option is specified AsciiDoc loads the
    appropriate help files and then prints the contents of the section
    whose name matches the help topic name.  If a topic name is not
    specified `default` is used. You don't need to specify the whole help
    topic name on the command-line, just enough letters to ensure it's not
    ambiguous. If a matching help file section is not found a list of
    available topics is printed.
    
    
    提示和技巧
    ---------------
    
    认识你的编辑器
    ~~~~~~~~~~~~~~~~
    Writing AsciiDoc documents will be a whole lot more pleasant if you
    know your favorite text editor. Learn how to indent and reformat text
    blocks, paragraphs, lists and sentences. <<X20,Tips for 'vim' users>>
    follow.
    
    [[X20]]
    Vim 命令行方式编辑 AsciiDoc
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Text Wrap Paragraphs
    ^^^^^^^^^^^^^^^^^^^^
    Use the vim `:gq` command to reformat paragraphs. Setting the
    'textwidth' sets the right text wrap margin; for example:
    
      :set textwidth=70
    
    To reformat a paragraph:
    
    1. Position the cursor at the start of the paragraph.
    2. Type `gq}`.
    
    Execute `:help gq` command to read about the vim gq command.
    
    [TIP]
    =====================================================================
    - Assign the `gq}` command to the Q key with the `nnoremap Q gq}`
      command or put it in your `~/.vimrc` file to so it's always
      available (see the <<X61, Example `~/.vimrc` file>>).
    - Put `set` commands in your `~/.vimrc` file so you don't have to
      enter them manually.
    - The Vim website (http://www.vim.org) has a wealth of resources,
      including scripts for automated spell checking and ASCII Art
      drawing.
    
    =====================================================================
    
    格式列表
    ^^^^^^^^^^^^
    The `gq` command can also be used to format bulleted, numbered and
    callout lists. First you need to set the `comments`, `formatoptions`
    and `formatlistpat` (see the <<X61, Example `~/.vimrc` file>>).
    
    Now you can format simple lists that use dash, asterisk, period and
    plus bullets along with numbered ordered lists:
    
    1. Position the cursor at the start of the list.
    2. Type `gq}`.
    
    段落缩进
    ^^^^^^^^^^^^^^^^^
    Indent whole paragraphs by indenting the fist line with the desired
    indent and then executing the `gq}` command.
    
    [[X61]]
    Example `~/.vimrc` File
    ^^^^^^^^^^^^^^^^^^^^^^^
    ---------------------------------------------------------------------
    " Show tabs and trailing characters.
    set listchars=tab:»·,trail:·
    set list
    
    " Don't highlight searched text.
    highlight clear Search
    
    " Don't move to matched text while search pattern is being entered.
    set noincsearch
    
    " Reformat paragraphs and list.
    nnoremap R gq}
    
    " Delete trailing white space and Dos-returns and to expand tabs to spaces.
    nnoremap S :set et<CR>:retab!<CR>:%s/[\r \t]\+$//<CR>
    
    autocmd BufRead,BufNewFile *.txt,README,TODO,CHANGELOG,NOTES
            \ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2 filetype=asciidoc
            \ textwidth=70 wrap formatoptions=tcqn
            \ formatlistpat=^\\s*\\d\\+\\.\\s\\+\\\\|^\\s*<\\d\\+>\\s\\+\\\\|^\\s*[a-zA-Z.]\\.\\s\\+\\\\|^\\s*[ivxIVX]\\+\\.\\s\\+
            \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:>
    ---------------------------------------------------------------------
    
    疑难解答
    ~~~~~~~~~~~~~~~
    - The asciidoc(1) `-v` (`--verbose`) command-line option displays the
      order of configuration file loading and warns of potential
      configuration file problems.
    - Not all valid AsciiDoc documents produce valid backend markup. Read
      the <<X5,AsciiDoc Backends>> section if AsciiDoc output is rejected
      as non-conformant by a backend processor.
    
    误区
    ~~~~~~~
    Incorrect character encoding::
        If you get an error message like `'UTF-8' codec can't decode ...`
        then you source file contains invalid UTF-8 characters -- set the
        AsciiDoc <<X54,encoding attribute>> for the correct character set
        (typically ISO-8859-1 (Latin-1) for European languages).
    
    Invalid output::
        AsciiDoc attempts to validate the input AsciiDoc source but makes
        no attempt to validate the output markup, it leaves that to
        external tools such as `xmllint(1)` (integrated into `a2x(1)`).
        Backend validation cannot be hardcoded into AsciiDoc because
        backends are dynamically configured. The following example
        generates valid HTML but invalid DocBook (the DocBook `literal`
        element cannot contain an `emphasis` element):
    
        +monospaced text with an _emphasized_ word+
    
    Misinterpreted text formatting::
        You can suppress markup expansion by placing a backslash character
        immediately in front of the element. The following example
        suppresses inline monospaced formatting:
    
        \+1 for C++.
    
    Overlapping text formatting::
        Overlapping text formatting will generate illegal overlapping
        markup tags which will result in downstream XML parsing errors.
        Here's an example:
    
        Some *strong markup _that overlaps* emphasized markup_.
    
    Ambiguous underlines::
        A DelimitedBlock can immediately follow paragraph without an
        intervening blank line, but be careful, a single line paragraph
        underline may be misinterpreted as a section title underline
        resulting in a ``closing block delimiter expected'' error.
    
    Ambiguous ordered list items::
        Lines beginning with numbers at the end of sentences will be
        interpreted as ordered list items.  The following example
        (incorrectly) begins a new list with item number 1999:
    
        He was last sighted in
        1999. Since then things have moved on.
    +
    The 'list item out of sequence' warning makes it unlikely that this
    problem will go unnoticed.
    
    Special characters in attribute values::
        Special character substitution precedes attribute substitution so
        if attribute values contain special characters you may, depending
        on the substitution context, need to escape the special characters
        yourself. For example:
    
        $ asciidoc -a 'corpname=Bill &amp; Ben Inc.' mydoc.txt
    
    Macro attribute lists::
        If named attribute list entries are present then all string
        attribute values must be quoted.  For example:
    
        ["Desktop screenshot",width=32]
    
    组合独立的文件
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    You have a number of stand-alone AsciiDoc documents that you want to
    process as a single document. Simply processing them with a series of
    `include` macros won't work because the documents contain (level 0)
    document titles.  The solution is to create a top level wrapper
    document that redefines the document underlines, pushing them down one
    level.  For example `combined.txt`:
    
    ---------------------------------------------------------------------
    :titles.underlines: "__","==","--","~~","^^"
    
    Combined Document Title
    _______________________
    
    \include::document1.txt[]
    
    \include::document2.txt[]
    
    \include::document3.txt[]
    ---------------------------------------------------------------------
    
    The document titles in the included documents will now be processed as
    level 1 section titles.
    
    - Put a blank line between the `include` macro lines to ensure the
      title of the included document is not seen as part of the last
      paragraph of the previous document.
    - You won't want document Headers (Author and Revision lines) in the
      included files -- conditionally exclude them if they are necessary
      for stand-alone processing.
    
    分别处理文件章节
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    You have divided your AsciiDoc document into separate files (one per
    top level section) which are combined and processed with the following
    top level document:
    
    ---------------------------------------------------------------------
    联合文件标题
    =======================
    Joe Bloggs
    v1.0, 12-Aug-03
    
    \include::section1.txt[]
    
    \include::section2.txt[]
    
    \include::section3.txt[]
    ---------------------------------------------------------------------
    
    You also want to process the section files as separate documents.
    This is easy because asciidoc(1) will quite happily process
    `section1.txt`, `section2.txt` and `section3.txt` separately -- the
    resulting output documents contain the section but have no document
    title.
    
    Use the `-s` (`--no-header-footer`) command-line option to suppress
    header and footer output, this is useful if the processed output is to
    be included in another file. For example:
    
      $ asciidoc -s -b docbook section1.txt
    
    处理文件摘录
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    asciidoc(1) can be used as a filter, so you can pipe chunks of text
    through it. For example:
    
      $ echo 'Hello *World!*' | asciidoc -s -
      <div class="paragraph"><p>Hello <strong>World!</strong></p></div>
    
    标记 HTML 页脚
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    See the `[footer]` section in the AsciiDoc distribution `xhtml11.conf`
    configuration file.
    
    打印优美的 AsciiDoc 输出
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    If the indentation and layout of the asciidoc(1) output is not to your
    liking you can:
    
    1. Change the indentation and layout of configuration file markup
       template sections. The `{empty}` glossary entry is useful for
       outputting trailing blank lines in markup templates.
    
    2. Use Dave Raggett's http://tidy.sourceforge.net/[HTML Tidy] program
       to tidy asciidoc(1) output. Example:
    
       $ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml
    
    3. Use the `xmllint(1)` format option. Example:
    
       $ xmllint --format mydoc.xml
    
    Supporting minor DocBook DTD variations
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    The conditional inclusion of DocBook SGML markup at the end of the
    distribution `docbook.conf` file illustrates how to support minor DTD
    variations. The included sections override corresponding entries from
    preceding sections.
    
    Shipping stand-alone AsciiDoc source
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Reproducing presentation documents from someone else's source has one
    major problem: unless your configuration files are the same as the
    creator's you won't get the same output.
    
    The solution is to create a single backend specific configuration file
    using the asciidoc(1) `-c` (`--dump-conf`) command-line option. You
    then ship this file along with the AsciiDoc source document plus the
    `asciidoc.py` script. The only end user requirement is that they have
    Python installed (and of course that they consider you a trusted
    source). This example creates a composite HTML configuration
    file for `mydoc.txt`:
    
      $ asciidoc -cb xhtml11 mydoc.txt > mydoc-xhtml11.conf
    
    Ship `mydoc.txt`, `mydoc-html.conf`, and `asciidoc.py`. With
    these three files (and a Python interpreter) the recipient can
    regenerate the HMTL output:
    
      $ ./asciidoc.py -eb xhtml11 mydoc.txt
    
    The `-e` (`--no-conf`) option excludes the use of implicit
    configuration files, ensuring that only entries from the
    `mydoc-html.conf` configuration are used.
    
    插入空白
    ~~~~~~~~~~~~~~~~~~~~~
    Adjust your style sheets to add the correct separation between block
    elements. Inserting blank paragraphs containing a single non-breaking
    space character `{nbsp}` works but is an ad hoc solution compared
    to using style sheets.
    
    闭合开放的段落
    ~~~~~~~~~~~~~~~~~~~~~
    You can close off section tags up to level `N` by calling the
    `eval::[Section.setlevel(N)]` system macro. This is useful if you
    want to include a section composed of raw markup. The following
    example includes a DocBook glossary division at the top section level
    (level 0):
    
    ---------------------------------------------------------------------
    \ifdef::backend-docbook[]
    
    \eval::[Section.setlevel(0)]
    
    +++++++++++++++++++++++++++++++
    <glossary>
      <title>Glossary</title>
      <glossdiv>
      ...
      </glossdiv>
    </glossary>
    +++++++++++++++++++++++++++++++
    \endif::backend-docbook[]
    ---------------------------------------------------------------------
    
    Validating output files
    ~~~~~~~~~~~~~~~~~~~~~~~
    Use `xmllint(1)` to check the AsciiDoc generated markup is both well
    formed and valid. Here are some examples:
    
      $ xmllint --nonet --noout --valid docbook-file.xml
      $ xmllint --nonet --noout --valid xhtml11-file.html
      $ xmllint --nonet --noout --valid --html html4-file.html
    
    The `--valid` option checks the file is valid against the document
    type's DTD, if the DTD is not installed in your system's catalog then
    it will be fetched from its Internet location. If you omit the
    `--valid` option the document will only be checked that it is well
    formed.
    
    
    专业术语
    --------
    [glossary]
    [[X8]] Block element::
        An AsciiDoc block element is a document entity composed of one or
        more whole lines of text.
    
    [[X34]] Inline element::
        AsciiDoc inline elements occur within block element textual
        content, they perform formatting and substitution tasks.
    
    Formal element::
        An AsciiDoc block element that has a BlockTitle. Formal elements
        are normally listed in front or back matter, for example lists of
        tables, examples and figures.
    
    Verbatim element::
        The word verbatim indicates that white space and line breaks in
        the source document are to be preserved in the output document.
    
    
    附录 A: 迁移说明
    ---------------------------
    [[X53]]
    版本 7 到版本 8
    ~~~~~~~~~~~~~~~~~~~~~~
    - A new set of quotes has been introduced which may match inline text
      in existing documents -- if they do you'll need to escape the
      matched text with backslashes.
    - The index entry inline macro syntax has changed -- if your documents
      include indexes you may need to edit them.
    - Replaced a2x(1) `--no-icons` and `--no-copy` options with their
      negated equivalents: `--icons` and `--copy` respectively. The
      default behavior has also changed -- the use of icons and copying of
      icon and CSS files must be specified explicitly with the `--icons`
      and `--copy` options.
    
    The rationale for the changes can be found in the AsciiDoc
    `CHANGELOG`.
    
    NOTE: If you want to disable unconstrained quotes, the new alternative
    constrained quotes syntax and the new index entry syntax then you can
    define the attribute `asciidoc7compatible` (for example by using the
    `-a asciidoc7compatible` command-line option).
    
    [[X38]]
    附录 B: 打包说明
    ---------------------------
    Read the `README` and `INSTALL` files (in the distribution root
    directory) for install prerequisites and procedures.  The distribution
    `Makefile.in` (used by `configure` to generate the `Makefile`) is the
    canonical installation procedure.
    
    
    [[X39]]
    附录 C: AsciiDoc 安全模式
    ------------------------------
    AsciiDoc 'safe mode' skips potentially dangerous scripted sections in
    AsciiDoc source files by inhibiting the execution of arbitrary code or
    the inclusion of arbitrary files.
    
    The safe mode is disabled by default, it can be enabled with the
    asciidoc(1) `--safe` command-line option.
    
    .Safe mode constraints
    - `eval`, `sys` and `sys2` executable attributes and block macros are
      not executed.
    - `include::<filename>[]` and `include1::<filename>[]` block macro
      files must reside inside the parent file's directory.
    - `{include:<filename>}` executable attribute files must reside
      inside the source document directory.
    - Passthrough Blocks are dropped.
    
    [警告]
    =====================================================================
    The safe mode is not designed to protect against unsafe AsciiDoc
    configuration files. Be especially careful when:
    
    1. Implementing filters.
    2. Implementing elements that don't escape special characters.
    3. Accepting configuration files from untrusted sources.
    =====================================================================
    
    
    附录 D: 在非英语情况下下使用 AsciiDoc 
    ----------------------------------
    AsciiDoc can process UTF-8 character sets but there are some things
    you need to be aware of:
    
    - If you are generating output documents using a DocBook toolchain
      then you should set the AsciiDoc `lang` attribute to the appropriate
      language (it defaults to `en` (English)). This will ensure things
      like table of contents, figure and table captions and admonition
      captions are output in the specified language.  For example:
    
      $ a2x -a lang=es doc/article.txt
    
    - If you are outputting HTML directly from asciidoc(1) you'll
      need to set the various `*_caption` attributes to match your target
      language (see the list of captions and titles in the `[attributes]`
      section of the default `asciidoc.conf` file). The easiest way is to
      create a language `.conf` file (see the AsciiDoc's `lang-en.conf`
      file).
    +
    NOTE: You still use the 'NOTE', 'CAUTION', 'TIP', 'WARNING',
    'IMPORTANT' captions in the AsciiDoc source, they get translated in
    the HTML output file.
    
    - asciidoc(1) automatically loads configuration files named like
      `lang-<lang>.conf` where `<lang>` is a two letter language code that
      matches the current AsciiDoc `lang` attribute. See also
      <<X27,Configuration File Names and Locations>>.
    
    - Some character sets display double-width characters (for example
      Japanese). As far as <<X17,title underlines>> are concerned they
      should be treated as single character.  If you think this looks
      untidy so you may prefer to use the <<X46,single line title>>
      format.
    
    
    附录 E: Vim 语法高亮
    ----------------------------------
    The AsciiDoc `./vim/` distribution directory contains Vim syntax
    highlighter and filetype detection scripts for AsciiDoc.  Syntax
    highlighting makes it much easier to spot AsciiDoc syntax errors.
    
    If Vim is installed on your system the AsciiDoc installer
    (`install.sh`) will automatically install the vim scripts in the Vim
    global configuration directory (`/etc/vim`).
    
    You can also turn on syntax highlighting by adding the following line
    to the end of you AsciiDoc source files:
    
      // vim: set syntax=asciidoc:
    
    NOTE: Dag Wieers has implemented an alternative Vim syntax file for
    AsciiDoc which can be found here
    http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/.
    
    NOTE: Emacs users: The http://xpt.sourceforge.net/[*Nix Power Tools
    project] has released an
    http://xpt.sourceforge.net/tools/doc-mode/[AsciiDoc syntax highlighter
    for emacs].
    
    限制
    ~~~~~~~~~~~
    The current implementation does a reasonable job but on occasions gets
    things wrong. This list of limitations also discusses how to work
    around the problems:
    
    - Indented lists with preceding blank lines are sometimes mistaken
      for literal (indented) paragraphs. You can work around this by
      deleting the preceding blank line, or inserting a space in the
      preceding blank lines, or putting a list continuation character
      (`+`) in the preceding blank line.
    
    - Nested quoted text formatting is highlighted according to the outer
      format.
    
    - If a closing block delimiter is not preceded by a blank line it is
      sometimes mistaken for a title underline. A workaround is to insert
      a blank line before the closing delimiter.
    
    - If a list block delimiter is mistaken for a title underline precede
      it with a blank line.
    
    - Lines within a paragraph beginning with a period will be highlighted
      as block titles. For example:
    
      .chm file.
    +
    To work around this restriction move the last word of the previous
    line to the start of the current (although words starting with a
    period should probably be quoted monospace which would also get around
    the problem).
    
    TIP: Sometimes incorrect highlighting is caused by preceding lines
    that appear blank but contain white space characters -- setting your
    editor options so that white space characters are visible is a good
    idea.
    
    
    [[X74]]
    附录 F: 属性设置
    -----------------------------
    这里是 <<X75,属性选项列表>> 的预设列表:
    
    
    [cols="2e,2,2,5",frame="topbot",options="header"]
    |====================================================================
    |Option|Backends|AsciiDoc Elements|Description
    
    |autowidth |xhtml11,html4 |table|
    The column widths are determined by the browser, not the AsciiDoc
    'cols' attribute. If there is no 'width' attribute the table width is
    also left up to the browser.
    
    |breakable, unbreakable |docbook (XSL/FO) |table, example, block image|
    The 'breakable' options allows block elements to break across page
    boundaries; 'unbreakable' attempts to keep the block element together
    on a single page. If neither option is specified the default XSL
    stylesheet behavior prevails.
    
    |compact |docbook, xhtml11 |bulleted list, numbered list|
    Minimizes vertical space in the list
    
    |footer |docbook, xhtml11, html4 |table|
    The last row of the table is rendered as a footer.
    
    |header |docbook, xhtml11, html4 |table|
    The first row of the table is rendered as a header.
    
    |pgwide |docbook (XSL/FO) |table, block image, horizontal labeled list|
    Specifies that the element should be rendered across the full text
    width of the page irrespective of the current indentation.
    
    |strong |xhtml11,html4 |labeled lists|
    Emboldens label text.
    
    |====================================================================
    
    
    [[X82]]
    附录 G: 诊断
    -----------------------
    The `asciidoc(1)` `--verbose` command-line option prints additional
    information to stderr: files processed, filters processed, warnings,
    system attribute evaluation.
    
    A special attribute named 'trace' controls the output of diagnostic
    information. If the 'trace' attribute is defined then
    element-by-element diagnostic messages detailing output markup
    generation are printed to stderr. The 'trace' attribute can be set on
    the command-line or from within the document using <<X18,Attribute
    Entries>> (the latter allows tracing to be confined to specific
    portions of the document).
    
    - Trace messages consist of a descriptive name followed by the related
      markup.
    - The trace message is only printed if the 'trace' attribute value
      matches the start of the trace name. The 'trace' attribute value can
      be any Python regular expression.
    - A blank trace value matches all trace names and all trace messages
      will be printed (this can result in large amounts of output if
      applied to the whole document).
    - In the case of inline substitutions:
      * The text before and after the substitution are printed delineated
        by `<<<` and `>>>` delimiters.
      * The message is only printed if a substitution is made.
      * The 'subs' trace value is an alias for all inline substitutions.
    
    命令行例子:
    
    . Trace the entire document.
    
      $ asciidoc -a trace mydoc.txt
    
    . Trace messages whose names start with `quotes` or `macros`:
    
      $ asciidoc -a 'trace=quotes|macros'  mydoc.txt
    
    . Print the first line of all trace messages:
    
      $ asciidoc -a trace mydoc.txt 2>&1 | grep ^TRACE:
    
    Attribute Entry examples:
    
    . Begin printing all trace messages:
    
      :trace:
    
    . Print only matched trace messages:
    
      :trace: quotes|macros
    
    . Turn trace messages off:
    
      :trace!:
    
    
    [[X88]]
    附录 H:输出属性
    ------------------------------
    下表显示影响输出的参数设置。
    
    [cols="1e,1,5a",frame="topbot",options="header"]
    |====================================================================
    |Name |Backends |Description
    
    |badges |xhtml11 |
    Link badges ('XHTML 1.1', 'CSS' and 'Get Firefox!') in document
    footers. By default badges are omitted ('badges' is undefined).
    
    NOTE: The path names of images, icons and scripts are relative path
    names to the output document not the source document.
    
    |data-uri |xhtml11 |
    Embed images using the <<X66,data: uri scheme>>.
    
    |docinfo |docbook |
    The <<X87,document information file>> will be included in the DocBook
    output if the `docinfo` attribute is defined.
    
    |[[X54]]encoding |html4, xhtml11, docbook |
    Set the input and output document character set encoding. For example
    the `--attribute encoding=ISO-8859-1` command-line option will set the
    character set encoding to `ISO-8859-1`.
    
    - The default encoding is UTF-8.
    - This attribute specifies the character set in the output document.
    - The encoding name must correspond to a Python codec name or alias.
    - The 'encoding' attribute can be set using an AttributeEntry inside
      the document header but it must come at the start of the document
      before the document title. For example:
    
      :encoding: ISO-8859-1
    
    |[[X45]]icons |xhtml11 |
    Link admonition paragraph and admonition block icon images and badge
    images. By default 'icons' is undefined and text is used in place of
    icon images.
    
    |[[X44]]iconsdir |html4, xhtml11, docbook |
    The name of the directory containing linked admonition and navigation
    icons. Defaults to `./images/icons`.
    
    |imagesdir |html4, xhtml11, docbook |
    If this attribute is defined it is prepended to the target image file
    name paths in inline and block image macros.
    
    |linkcss |xhtml11 |
    Link CSS stylesheets and JavaScripts (see the 'stylesdir' and
    'scriptsdir' attributes below). By default 'linkcss' is undefined in
    which case stylesheets and scripts are automatically embedded in the
    output document.
    
    |max-width |xhtml11 |
    Set the document maximum display width (sets the 'body' element CSS
    'max-width' property). 'max-width' definition must precede the
    document header.
    
    |numbered |html4, xhtml11, docbook (XSL Stylesheets) |
    Adds section numbers to section titles.
    
    |quirks |xhtml11 |
    Use the `xhtml11-quirks.css` stylesheet to work around IE6 browser
    incompatibilities (this is the default behavior).
    
    |revremark |docbook |
    A short summary of changes in this document revision. Must be defined
    prior to the first document section. The document also needs to be
    dated to output this attribute.
    
    |scriptsdir |xhtml11 |
    The name of the directory containing linked JavaScripts. Defaults to
    `.` (the same directory as the linking document).
    
    |sgml |docbook |
    The `--backend=docbook` command-line option produces DocBook XML.  You
    can produce the older DocBook SGML format using the `--attribute sgml`
    command-line option.
    
    |stylesdir |xhtml11 |
    The name of the directory containing linked stylesheets. Defaults to
    `.` (the same directory as the linking document).
    
    |stylesheet |xhtml11 |
    The file name of an optional additional CSS stylesheet. If you are
    embedding the stylesheet specify the actual file name; if you are
    linking CSS specify the file name relative to the directory specified
    by the 'stylesdir' attribute.
    
    |theme |xhtml11 |
    Use alternative stylesheets (see <<X35,Stylesheets>>).
    
    |toc |xhtml11, docbook (XSL Stylesheets) |
    Adds a table of contents to the start of an article or book document.
    
    NOTE: The `toc` attribute must be specified using the `--attribute`
    command-line option. If you define the `toc` attribute in a custom
    configuration file it won't be recognized because the conditionally
    included header code will have already been processed.
    
    *xhtml11 backend*
    
    - JavaScript needs to be enabled in your browser for this to work.
    - By default AsciiDoc automatically embeds the required `toc.js`
      JavaScript in the output document -- use the 'linkcss' attribute to
      link the script.
    - The following example generates a numbered table of contents by
      embedding the `toc.js` script in the `mydoc.html` output document
      (to link the script to the output document use the 'linkcss' and
      'scriptsdir' attributes):
    
      $ asciidoc -a toc -a numbered mydoc.txt
    
    |toc_title |xhtml11 |
    Sets the table of contents title (defaults to 'Table of Contents').
    
    |toclevels |xhtml11 |
    Sets the number of title levels (1..4) reported in the table of
    contents (see the 'toc' attribute above). Defaults to 2 and must be
    used with the 'toc' attribute. Example usage:
    
      $ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt
    
    |====================================================================