===================
AsciiDoc 是一种文本文件书写格式，文章，手册，书籍和UNIX手册。AsciiDoc 文件可以 asciidoc(1) 命令转换成 HTML 和 DocBook 标记。AsciiDoc 是一种先进的结构：AsciiDoc 语法和输出标记（几乎可以转换成任意的 SGML/XML 标记）都可以有用户自己定义和扩展。
简介
------------
**********************************************************************
这是一个很大的文档，它可能需要做成一本手册，快速参考或正式资料。
如果你是一个 AsciiDoc 新手请阅读本节和 <<X6,起步>> 一节 或看看代码文件夹 `doc` 中的例子 AsciiDoc `.txt` 。
**********************************************************************
纯文本是最通用的电子文档格式，无论你使用那种计算机环境都可以读写纯文本文件。不过纯文本不是使用最多的文档格式。HTML, PDF and roff (roff 用于手册页) 是使用最广泛的 UNIX 文档格式。 DocBook 是一种流行的 UNIX 文件标记格式，可转换为 HTML，PDF 和其他文稿格式。
AsciiDoc 是一种人们方便读写的纯文本格式，可以使用 asciidoc(1) 转换成 DocBook 或 HTML 。你可以使用 asciidoc(1) 直接生成 HTML 或运行 asciidoc(1) 通过你喜欢的 DocBook 工具链输出 DocBook ，使用 AsciiDoc a2x(1) 工具链输出产品 PDF, EPUB, DVI, LaTeX, PostScript, man page, HTML 和其他文本格式。
AsciiDoc 格式本身的特性决定他的易用性：AsciiDoc 文件容易标记，方便查看、校对和编辑。
AsciiDoc 是一个轻量级软件：只有一个 Python 脚本文件和一些配置文件。除了 asciidoc(1) 和一个 Python 程序，AsciiDoc 文件转换成 DocBook 或 HTML 不需要其他的软件。看下面的 <<X11, AsciiDoc 文档例子>>
你可以像写普通文本文件一样写一个 AsciiDoc 文档，暂时没有标签和陌生的符号。AsciiDoc 语法规则已经尽量少并且易懂。
通用的文本标记可能你并不喜欢（经常遇到）：如果默认的语法你不喜欢，你可以通过修改文本格式 asciidoc(1) 配置文件定义自己的语法。你可以通过创建自己的配置文件可以把 AsciiDoc 文档转换成任何 SGML/XML 标记。
asciidoc(1) 根据配置文件的设置把 AsciiDoc 的文章，图书，手册页 转换成 HTML 或 DocBook 格式。
.我对 AsciiDoc 的期望
**********************************************************************
DocBook 已经成为开源文档事实上的标准格式。但是 DocBook 是一种复杂的语言，直接书写比较困难，写成的文本也难于阅读。-- 我发现自己花太多的时间写标签，查手册和修改语法错误，然后才能写内容。
**********************************************************************
[[X6]]
起步
---------------
安装 AsciiDoc
~~~~~~~~~~~~~~~~~~~
查看 `README` 和 `INSTALL` 文件了解安装要求和步骤，打包格式查看 <<X38,附录 B: 打包说明>>。
[[X11]]
AsciiDoc 文档例子
~~~~~~~~~~~~~~~~~~~~~~~~~~
尽快感受 AsciiDoc 的方法是访问 AsciiDoc 网站或现有例子。
- 看看 AsciiDoc 网站 http://www.methods.co.nz/asciidoc/ 首页的样例链接。点击左边菜单项目 'Page Source' 可以看到相应的 AsciiDoc 代码。
- 阅读 `./doc` 文件夹中的 `.txt` 代码文件和相应的 HTML 和 DocBook XML 文件。
AsciiDoc 文档类型
-----------------------
AsciiDoc 文档有三种类型：article（文章）, book（图书），和 manpage（手册页）。所有文件类型使用相同 AsciiDoc 格式除了少量细微的差别。
使用 asciidoc(1) `-d` (`--doctype`) 参数设置 AsciiDoc 文档类型 -- 默认文档类型是 'article（文章）'
AsciiDoc 文档代码使用 `.txt` 文件扩展名。
article（文章）
~~~~~~~~~~~~~
主要用于短文，文章和一般内容。参见 AsciiDoc 下载目录中 `./doc/article.txt` 例子
book（图书）
~~~~~~~~~~
图书除了使用文章的格式，增加了级别为0的图书段落部分。
图书文档通常用于生产DocBook的输出，因为
DocBook的处理器可以自动生成脚注，表格内容，表格的列表，数字清单，清单和例子和索引。
AsciiDoc标记支持标准的DocBook文前内容和文后内容 <<X16,特殊段落>>（贡献，序言，书目，词汇，
索引，版权页）加脚注和索引项。
.图书文档例子
图书::
The `./doc/book.txt` file in the AsciiDoc distribution.
多部分图书::
The `./doc/book-multi.txt` file in the AsciiDoc distribution.
手册页
~~~~~~~
用于生成 UNIX 手册页。 AsciiDoc 控制文档遵循专有的头标题和段落命名规则 -- 详情参见 <<X1,手册页文档>> 。
也可以AsciiDoc目录查看asciidoc(1)手册页代码 (`./doc/asciidoc.1.txt`)。
[[X5]]
AsciiDoc 输出
-----------------
asciidoc(1) 命令转换一个AsciiDoc格式文件到其他格式使用 `-b` (`--backend`) 命令行参数。asciidoc(1)本身内置了很少文件格式信息，所有转换规则包含在可定制的配置文件里面。输出专有单数列在了<<X88,附录 H>>。
AsciiDoc 支持一下输出格式：
docbook
~~~~~~~
AsciiDoc可以生成一下DocBook文档格式：article, book 和 refentry (对应 AsciiDoc 'article', 'book' 和 'manpage' 文档类型)
DocBook文档不能直接预览。多数Linux发行版使用转换工具（一个工具集）见 <<X12,转换 DocBook 文件>> 转换到其他格式如 Postscript, HTML, PDF, DVI, PostScript, LaTeX, roff (原生联机手册格式), HTMLHelp, JavaHelp and text。
AsciiDoc <<X86,前言>> 部分转换成 DocBook book '前言' 部分虽然他通常是 'Preface' 独立段落 (参见 `./doc/book.txt` 图书样例)。
[[X33]]
xhtml11
~~~~~~~
asciidoc(1) 默认输出为 `xhtml11` ，用于生成 XHTML 1.1 并使用 CSS2。默认输出文件使用 `.html` 扩展名。'xhtml11' 文档生成受以下参数影响（默认行为生成的 XHTML 没有段落编号，嵌入式CSS，也没有警告图标）：
[[X35]]
样式表
^^^^^^^^^^^
AsciiDoc 输出 XHTML 使用的 CSS2 样式在安装目录中 `./stylesheets/` 文件夹里面。
[重要]
=====================================================================
所有浏览器都有 CSS 问题，但是微软的 IE6 有太多的漏洞和错误，`xhtml11-quirks.css` 样式和 `xhtml11-quirks.conf` 配置文件在处理的时候对 IE6 进行优化。如果你不使用 IE6 ，那么样式文件和配置文件可以使用 `--attribute quirks!` 命令行参数忽略。
=====================================================================
默认 'xhtml11' 样式表:
`./stylesheets/xhtml11.css`::
主样式表。
`./stylesheets/xhtml11-manpage.css`::
用于手册页文档转换。
`./stylesheets/xhtml11-quirks.css`::
调整 IE6 兼容性的样式表。
使用 'theme' 参数可以定义样式表。例如，命令行参数 `-a theme=foo` 会使用 `foo.css`, `foo-manpage.css` and `foo-quirks.css` 代替默认的样式表。
使用 'stylesheet' 参数可以在 XHTML 文档中包含一个附加样式表。例如，命令行参数 `-a
stylesheet=newsletter.css` 会使用 `newsletter.css` 。
html4
~~~~~
用于生成纯（无样式）的 HTML 4.01 转换标记
文档结构
------------------
一个 AsciiDoc 文档由一个 <<X8,基本区块>> 序列组成，由可选的文档头部开始，后面是可选的序言，再后面是0或多个文档段落。
几乎所有的零或多个基本结构组合起来都是有效的 AsciiDoc 文档：文档范围涵盖单个句子和多部分的图书。
基本区块
~~~~~~~~~~~~~~
基本区块由一行或多行文本，也可以包括其他的基本区块。
AsciiDoc 区块概括如下[这是一个大概的结构指南，不是严格的语法定义]：
文档 ::= (头部?,前言?,章节*)
头部 ::= (标题,(作者,修订?)?)
作者 ::= (名字,(中间名?,姓氏)?,Email地址?)
修订 ::= (版本?,日期)
前言 ::= (段落)
章节 ::= (标题,段落?,(章节)*)
段落 ::= ((块标题?,块)|宏块)+
块 ::= (自然段|独立块|列表|表格)
列表 ::= (无序列表|有序列表|定义列表|标注列表)
无序列表| ::= (项目)+
有序列表 ::= (项目)+
标注列表 ::= (项目)+
定义列表 ::= (条目)+
条目 ::= (标签,项目)
标签 ::= (项目+)
项目 ::= (项目文本,(列表|段落列表|列表后续)*)
注释:
- '?' 表示0或1个, '+' 表示0或多个, '*' 表示1或多个.
- 所有的基本块有独立的界线分开.
- `BlockId`, `AttributeEntry` and `AttributeList` block elements (not
shown) can occur almost anywhere.
- There are a number of document type and backend specific
restrictions imposed on the block syntax.
- 下面的基本部分不能包含空行: 头部, 标题, 自然段, 项目文本.
- 段落列表为有 '列表元素' 项目的段落.
- 列表后续参见 <<X15,列表后续内容>>.
头部
~~~~~~
头部包含文档标题加上作者和版本信息。头部是可选的但是必须在文档的开始 <<X17,标题>>. 头部可以在注释和<<X18,属性项目>> 前面. 标题后面的作者和修订信息可选。头部可以包含在属性条目行。该文件标题是隔开的一个或多个空行从文档的其余部分. 下面是一个 AsciiDoc 文档头部的例子:
使用 AsciiDoc 编写文档
====================================
Joe Bloggs <[email protected]>
v2.0, February 2003:
Rewritten for version 2 release.
作者行包括作者姓名和作者的Email地址。作者姓名包括名字和可选的使用空格隔开的中间名和姓氏。多个单词的名字，中间名，姓氏使用下划线链接。email必须使用尖括号<>包含。作者名称不能包含尖括号<>. 下面是一些作者行的例子:
Joe Bloggs <[email protected]>
Joe Bloggs
Vincent Willem van_Gogh
修订行在作者后面可选。版本行可以使用下面的格式:
. 文档修订版本号后跟可选的修订日期后跟可选的修订注释:
* 制定了版本号后面必须跟一个逗号。
* 版本号是一个以上的数字.
* 版本号前面的非数字字符会被忽略掉.
* 版本注释前面必须有冒号。版本注释从冒号到下一个空行或属性标志由普通文本替换
* 版本号和注释设置后如果日期没有设置系统会使用 'docdate' 参数输出。
. 使用 RCS/CSV/SVN $Id$ 标记 (如果使用 $Id$ 作为版本标记则作者行会被忽略).
下面是一些版本行的例子:
v2.0, February 2003
February 2003
v2.0,
v2.0, February 2003: Rewritten for version 2 release.
February 2003: Rewritten for version 2 release.
v2.0,: Rewritten for version 2 release.
:Rewritten for version 2 release.
你可以使用asciidoc(1) `-a` (`--attribute`) 设置头部内容通过参数 'revnumber', 'revremark', 'revdate', 'email', 'author', 'authorinitials', 'firstname' and 'lastname' . 例子:
$ asciidoc -a revdate=2004/07/27 article.txt
'revnumber' 参数可以使用 RCS/CSV/SVN $Id$ 标签.Attributes can also be added to the header for substitution in the header template with <<X18,Attribute Entry>> elements.
[[X87]]
文档头部附加信息
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
DocBook 定义了很多元素，例如：版权，文档历史和原作者信息。AsciiDoc 头部提供基本的修订和作者信息 -- 附加信息像版权信息和文档历史会作为可选包含从独立的包含 DocBook 项目 文档信息文件那些包含在 DocBook '文章信息' 和 '图书信息' 项目：
- 文档信息文件必须和文档再同一个目录下面，文件名称类似 `<docname>-docinfo.xml` 。例如，如果源文件为 `mydoc.txt` 那么文档信息文件应该为`mydoc-docinfo.xml` 。
- 文档信息文件将被包含进 DocBook 输出，如果指定 `docinfo` 参数，例如：
$ asciidoc -a docinfo -b docbook mydoc.txt
参见 AsciiDoc 文件夹中的 `./doc/article-docinfo.xml` 例子
[[X86]]
前言
~~~~~~~~
前言是可选没有标题的段落，位于头部和第一章节之间。
章节
~~~~~~~~
AsciiDoc 支持0-4共5个章节级别（虽然只有图书允许包含0级别的章节）。章节级别的说明见 <<X17,标题>> 。
章节使用配置文件转换标记模板。章节模板使用下列方式制定（按优先权重排序）：
1. 通过设置名称的第一个位置属性或 'template' 属性的配置文件的模板的名称。以下三个章节标题功能相当：
+
.....................................................................
[[terms]]
[glossary]
List of Terms
-------------
["glossary",id="terms"]
List of Terms
-------------
[template="glossary",id="terms"]
List of Terms
-------------
.....................................................................
2. 标题符合配置文件中的 <<X16,specialsections>> （特殊章节） 部分.
3. 其他不属于上面的使用 `sect<level>` 模板名称的。
使用 `-n` (`--section-numbers`) 命令行参数设置 HTML 输出的自动编号 (DocBook 行号由 DocBook toolchain 命令自动生成) 。
章节编号根据章节标题自动生成如果应用 `sectids` 参数(默认设置)。这个特征主要是为了保证内容链接表的效果：错误的章节编号被 JavaScript TOC 脚本动态生成的 *after* 页面载入，例如，如果你访问的标签是动态生成的 TOC 地址并载入了页面但是浏览器会忽略(因为没有生成) 章节编号。
章节编号按照下面的算法生成：
- 为所有非字母数字加上下划线。
- Strip leading or trailing underscores.
- 转换成小写字母。
- 预设 `idprefix` 参数（所以没有与现有文件的ID名称冲突的可能性）。如果 `idprefix `属性没有定义会加上一个下划线
- 如果自动生成的章节编号存在则在名称后添加编号后缀（`_2`，`_3`...）。
例如标题 'Jim's House' 将生成编号为 `_jim_s_house`。
[[X16]]
特殊章节
^^^^^^^^^^^^^^^^
附加 DocBook 正文前和正文后的章节到正常章节 -- 例如：前言，参考书目，目录，索引。
AsciiDoc 配置文件中有 `[specialsections]` 部分；他们会映射具体的章节到标记模板。格式如下：
<title>=<template>
`<title>` 是Python规则 `<template>` 是配置文件标记模板章节名称。如果 `<title>` 是一个 AsciiDoc 文档的章节标题则输出使用 `<template>` 标记模板（替代默认的 `sect<level>` 章节模板）。如果 'title' 组合 `{title}` 默认的 AsciiDoc 章节标题， `{title}` 参数设置为符合 'title' 规则的组合。如果 `<template>` 为空则所有符合 `<title>` 的标题被删除。
AsciiDoc 使用下面的特殊章节标题进行重构：
前言 (图书专用)
摘要 (文章专用)
贡献者 (图书专用)
术语表
参考文献|参考书目
版权标志 (图书专用)
索引
附录 [A-Z][:.] <title>
内置元素
~~~~~~~~~~~~~~~
<<X34,内置文档元素>> 用来标记字符的格式和不同类型的替换。内置项目和内置项目语法在 asciidoc(1) 配置文件中定义。
这里是 AsciiDoc 内置元素处理命令列表：
特殊字符::
这些字符转义特殊字符使用后端标记（一般是 "<", ">", 和 "&"），
参阅配置文件 `[specialcharacters]` 部分
引用::
标记单词和短语的字符，通常是字符格式。参阅配置文件的 `[quotes]` 部分。
专用词语::
词或短语根据标签选出不用进一步注释。参阅配置文件 `[specialwords]` 部分。
替换::
每替换定义一个字或词短语的模式去搜索相应的替换文本。参阅配置文件 `[replacements]` 部分
参数::
使用相应的参数值替换大括号封闭（属性引用）的文档参数名称。
内置宏::
内置宏被替换使用配置文件中设置的内容。
文档处理
-------------------
AsciiDoc 代码文档像下面读取和处理：
1. 分析文档头部，使用头部参数替换配置文件中 `[header]` 模板部分等待输出。
2. 分析文档所有 '章节' 和组成元素转换后等待输出。
3. 替换配置文件 `[footer]` 部分并且写入输出文件
asciidoc(1) 安装下面顺序确定块类型（从先到后）：（章节），标题，宏，列表，分割块，表格，属性项，属性列表，块标题，段落。
默认段落定义 `[paradef-default]` 最后检查。
知道分析顺序可以帮助你设计明确的宏，列表，块的样式规则。
内置替换再块内按下面顺序执行。
1. 特殊字符
2. 引用
3. 特殊词
4. 替换
5. 属性
6. 内置宏
7. 替换
替换或替换顺序在执行于标题，段落和分割块的时候由配置文件参数决定。
格式化文本
---------------
[[X51]]
文本描述
~~~~~~~~~~~
使用描述字符封闭的词语和句子会被格式化：
_强调_::
使用 \'单引号' 或 \_下划线_ 封闭的词句表示强调。
*粗体*::
使用 \*星号* 封闭的词句表示粗体。
[[X81]]+等宽字体+::
短语 \+使用加号封闭的字符+ 显示为等宽字体。 \`使用重音符号封闭的字符`（重音符号）也会
显示为等宽字符，但是这种情况下，封闭的文本显示不受进一步定义 (参阅 <<X80,内置文字>>)。
`单引号引用'::
使用 \`一个重音符号（译注：不是单引号，一般在键盘的左上部）到一个单引号之间' 的字句
表示单引号引用。
``双引号引用''::
使用 \\``两个重音符号（译注：不是单引号，一般在键盘的左上部）到两个单引号之间'' 的字句
表示双引号引用。
#无引用文本#::
\#井号包围的文本# 没有效果，这是一种允许应用内置属性到其他无格式文本的机制（见下例）
引用文字的前缀可以是 <<X21,属性列表>>。目前只适用于指定字体颜色，背景颜色和大小（只用于XHTML/HTML，不能用于 DocBook）使用的前三个位置的属性参数。第一个参数是文本的颜色，第二个背景颜色;第三是字体的大小。颜色是有效的CSS颜色和字体的大小是数字以em为单位。下面是一些例子：
引用文本会被加上前缀使用 <<X21,属性列表>>。
---------------------------------------------------------------------
[red]#红色文本#.
[,yellow]*加粗文本黄色背景*.
[blue,#b0e0e6]+等宽的蓝色文本浅蓝色背景+
[,,2]#2倍大小文本#.
---------------------------------------------------------------------
新的引用可以通过修改配置文件定义。参阅 <<X7,配置文件>> 相关部分。
.引用文本文件
- 引用不能交叉。
- 不同类型的引用可以嵌套
- 为了防止使用引用格式，可以在引号前面放一个反斜杠。不清楚是否引用你需要在前后都添加转义符，
多字符引用你需要转义单个字符。
- 配置文件 `[quotes]` 部分可以是设置为空。
[[X52]]
限制引用和非限制引用
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
这是引用的两种类型：
限制引用
++++++++++++++++++
引用的文字，必须由空格或常用毗邻标点符号分割。这些是最常用的引用类型。
非限制引用
++++++++++++++++++++
非限制引用没有边界的限制，可放置在任何地方内置文本。为了保持一致，并使其更容易记住非限制引用是双重的`_`，`*`，`+'和`＃`限制引用
__非限制强调文本__
**非限制加粗文本**
++非限制等宽文本++
##非限制加引号的文本##
下面例子加粗字母F：
**F**ile Open...
上标和下标
~~~~~~~~~~~~~~~~~~~~~~~~~~~
\^中间的字符^ 为上标, \~中间的字符~ 为下标. 例如:
e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~
效果:
e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~
上边和下标执行 <<X52,非限制引用>> 所以可以使用反斜杠转义和使用属性列表。
换行
~~~~~~~~~~~
加号后面跟一个空格为强制换行。转换到 HTML 后为换行标签 (`br`) ，转换到 DocBook 时为自定义的 XML `asciidoc-br` 处理命令。 `asciidoc-br` 处理命令参阅 <<X43,a2x(1)>>。
分页
~~~~~~~~~~~
一行只有三个或更多小于号 (`<<<`) 将会生成硬换页在输出到 DocBook 和 打印格式的 HTML，使用 CSS `page-break-after` 属性用于 HTML 输出和自定义的 XML 处理指令 `asciidoc-pagebreak` 用于 DocBook输出。`asciidoc-pagebreak` 处理指令参见 <<X43,a2x(1)>> 。硬分页符有时方便，但作为一般规则，你应该让你的网页处理器，为您产生分页符。
分割行
~~~~~~
一行只有三个或更多省略号将会生成一个分割行。输出 HTML 时生成分割线 (`hr`) 标签，输出 DocBook 时生成 `asciidoc-hr` 的 XML 处理指令，`asciidoc-hr` 指令参阅 <<X43,a2x(1)>> 。
制表符
~~~~~
默认情况下输入制表符的文件将转换为8位。 Tab扩展与'tabsize'的配置项文件中设置 `[miscellaneous]` 部分，可在覆盖包括通过设置 `include` 包括宏的属性列表 'tabsize' 属性的文件。例如：
include::addendum.txt[tabsize=2]
该选项卡的大小也可以使用属性设置命令行选项，
例如 `--attribute tabsize=4`
替换
~~~~~~~~~~~~
AsciiDoc 默认定义了下列替换：
(C) 版权, (TM) 商标, (R) 注册商标, -- 破折号, ... 省略号, -> 右箭头, <- 左箭头, => 右双箭头, <= 左双箭头.
效果如下:
(C) 版权, (TM) 商标, (R) 注册商标, -- 破折号, ... 省略号, -> 右箭头, <- 左箭头, => 右双箭头, <= 左双箭头.
你可以包含任何内码引用于 AsciiDoc 代码中。例如:
➊ ¶
效果:
➊ ¶
To render a replacement literally escape it with a leading back-slash.
<<X7,配置文件>> 段落说明了如何配置你自己替换项目.
特殊词语
~~~~~~~~~~~~~
词语在配置文件中 `[specialwords]` 部分定义会自动标记，而不必到明确标记。
<<X7,配置文件>> 说明如何添加和替换特殊词语。
[[X17]]
标题
------
文档和段落标题会使用下面两种格式中的一种：
双行标题
~~~~~~~~~~~~~~~
双行标题由一个标题行，一个硬回车和一个下划线组成。下划线由重复字符组成和上面标题等宽：
不同级别的标题默认的下划线如下：
0级 (顶级): ======================
1级: ----------------------
2级: ~~~~~~~~~~~~~~~~~~~~~~
3级: ^^^^^^^^^^^^^^^^^^^^^^
4级 (最低级): ++++++++++++++++++++++
样例:
一级段落标题
-----------
二级子段落标题
~~~~~~~~~~~~
[[X46]]
单行标题
~~~~~~~~~~~~~~~
单行标题由等号封闭的文字构成（等号的个数表示段落级别）。下面是一些样例：
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
= 文档标题 (0级) =
== 段落标题 (1级) ==
=== 段落标题 (2级) ===
==== 段落标题 (3级) ====
===== 段落标题 (4级) =====
.注意
- 标题和标记之间必须有一个或多个空格.
- 标题的界定符是可选的.
- 改变单行标题语法可以编辑 configuration 文件 `[titles]` section `sect0`...`sect4` 项.
浮动标题
~~~~~~~~~~~~~~~
设置标题的首位属性或 'style' 属性为 'float' 可以实现自由浮动标题。自由浮动标题看上去像普通标题，但是没有普通的文本结构，没有普通段落的层次，不使用普通的规则。浮动标题可以在上下文使用特殊的标题：例如侧边栏和警告框。样例:
[float]
第二天
~~~~~~~~~~~~~~
[[X42]]
块标题
------------
'块标题' 元素是一个句点开始的文本行。块标题应用到紧跟在后面的段落，列表，表格或区块。例如：
........................
.Notes
- Note 1.
- Note 2.
........................
显示效果:
.Notes
- Note 1.
- Note 2.
[[X41]]
块标志元素
---------------
A 'BlockId' is a single line block element containing a unique
identifier enclosed in double square brackets. It is used to assign an
identifier to the ensuing block element for use by referring links.
For example:
[[chapter-titles]]
Chapter titles can be ...
The preceding example identifies the following paragraph so it can be
linked from other location, for example with
`<<chapter-titles,chapter titles>>`.
'BlockId' elements can be applied to Title, Paragraph, List,
DelimitedBlock, Table and BlockMacro elements. The BlockId element
sets the `{id}` attribute for substitution in the subsequent block's
markup template. If a second argument is supplied it sets the
`{reftext}` attribute which is used to set the DocBook `xreflabel`
attribute.
The 'BlockId' element has the same syntax and serves a similar
function to the <<X30,anchor inline macro>>.
[[X79]]
属性列表元素
---------------------
An 'AttributeList' block element is an <<X21,attribute list>> on a
line by itself. 'AttributeList' attributes are only applied to the
following block element -- the attributes are available for markup
template substitution. Often the first attribute in the list is used
to specify the following element's <<X23,style>>.
By default only attribute references are substituted within attribute
values, this is because not all attributes are destined to be marked
up and rendered as text (for example the table 'cols' attribute). To
perform normal inline text substitutions (special characters, quotes,
macros, replacements) on an attribute value you need to enclose it in
single quotes. In the following quote block the second attribute value
in the AttributeList is quoted to ensure the 'http' macro is expanded
to a hyperlink.
---------------------------------------------------------------------
[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']
_____________________________________________________________________
Sir, a woman's preaching is like a dog's walking on his hind legs. It
is not done well; but you are surprised to find it done at all.
_____________________________________________________________________
---------------------------------------------------------------------
公共属性
~~~~~~~~~~~~~~~~~
大多数的文本块支持下列属性：
[cols="1e,1,5a",frame="topbot",options="header"]
|====================================================================
|Name |Backends |Description
|id |html4, xhtml11, docbook |
Unique identifier typically serve as link targets.
Can also be set by the 'BlockId' element.
|role |docbook |
Role contains a string used to classify or subclassify an element.
Used to add the 'role' attribute to DocBook block elements.
|reftext |docbook |
'reftext' is used to set the DocBook 'xreflabel' attribute.
Can also be set by the 'BlockId' element.
|====================================================================
[cols="1e,1,5a",frame="topbot",options="header"]
|====================================================================
|名称 |Backends |说明
|id |html4, xhtml11, docbook |
唯一标识符通常作为链接目标。也可以由 'BlockId' 元素设置。
|role |docbook |
Role 包含可用于分类或子类元素一个字符串。用于添加 'role' 属性到 DocBook 的块元素。
|reftext |docbook |
'reftext'是用来设置DocBook的'xreflabel'属性。也可以由 'BlockId' 元素设置。
|====================================================================
段落
----------
Paragraphs are blocks of text terminated by a blank line, the end of
file, or the start of a DelimitedBlock. Paragraph markup is specified
by configuration file `[paradef*]` sections.
Normal paragraphs consist of one or more non-blank lines of text. The
first line must start hard against the left margin (no intervening
white space). The default processing expectation is that of a normal
paragraph of text. 'literal' and 'verse' paragraph styles are
available (in addition to the 'default' paragraph style).
[[X85]]
文字段落样式
~~~~~~~~~~~~~~~~~~~~~~~~
Literal paragraphs are rendered verbatim in a monospaced font without
any distinguishing background or border. By default there is no text
formatting or substitutions within Literal paragraphs apart from
Special Characters and Callouts. For example:
---------------------------------------------------------------------
[literal]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
---------------------------------------------------------------------
效果：
[literal]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
verse paragraph style
~~~~~~~~~~~~~~~~~~~~~
The 'verse' paragraph <<X23,style>> preserves line boundaries and is
useful for lyrics and poems. For example:
---------------------------------------------------------------------
[verse]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
---------------------------------------------------------------------
效果：
[verse]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
段落缩进
~~~~~~~~~~~~~~~~~~~
Indented paragraphs (the first line indented by one or more space or
tab characters) are rendered using the <<X85,literal paragraph
style>>. For example:
---------------------------------------------------------------------
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
---------------------------------------------------------------------
效果：
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
NOTE: Because <<X64,lists>> can be indented it's possible for your
indented paragraph to be misinterpreted as a list -- in situations
like this apply the 'literal' style to a normal paragraph.
[[X28]] 提醒段落
~~~~~~~~~~~~~~~~~~~~~
'Tip', 'Note', 'Important', 'Warning' and 'Caution' paragraph
definitions support the corresponding DocBook admonishment elements --
just write a normal paragraph but place `NOTE:`, `TIP:`, `IMPORTANT:`,
`WARNING:` or `CAUTION:` as the first word of the paragraph. For
example:
NOTE: This is an example note.
or the alternative syntax:
[NOTE]
This is an example note.
Renders:
NOTE: This is an example note.
TIP: If your admonition is more than a single paragraph use an
<<X22,admonition block>> instead.
[[X47]]
提醒图标和标题
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
NOTE: 定制警告图标 `icons`, `iconsdir`, `icon` 和 `caption` 属性不能用于生成 DocBook。如果你确定使用 DocBook 则 <<X43,a2x(1)>> `--no-icons` 和 `--icons-dir` 选项可以用于设置适当的XSL样式表参数。
By default the asciidoc(1) `xhtml11` and `html4` backends generate
text captions instead of icon image links. To generate links to icon
images define the <<X45,`icons`>> attribute, for example using the `-a
icons` command-line option.
The <<X44,`iconsdir`>> attribute sets the location of linked icon
images.
You can override the default icon image using the `icon` attribute to
specify the path of the linked image. For example:
[icon="./images/icons/wink.png"]
NOTE: What lovely war.
Use the `caption` attribute to customize the admonition captions (not
applicable to `docbook` backend). The following example suppresses the
icon image and customizes the caption of a NOTE admonition (undefining
the `icons` attribute with `icons=None` is only necessary if
<<X45,admonition icons>> have been enabled):
[icons=None, caption="My Special Note"]
NOTE: This is my special note.
This subsection also applies to <<X22,Admonition Blocks>>.
分隔的块
----------------
Delimited blocks are blocks of text enveloped by leading and trailing
delimiter lines (normally a series of four or more repeated
characters). The behavior of Delimited Blocks is specified by entries
in configuration file `[blockdef*]` sections.
预定义的分隔块
~~~~~~~~~~~~~~~~~~~~~~~~~~~
AsciiDoc ships with a number of predefined DelimitedBlocks (see the
`asciidoc.conf` configuration file in the asciidoc(1) program
directory):
Predefined delimited block underlines:
CommentBlock: //////////////////////////
PassthroughBlock: ++++++++++++++++++++++++++
ListingBlock: --------------------------
LiteralBlock: ..........................
SidebarBlock: **************************
QuoteBlock: __________________________
ExampleBlock: ==========================
OpenBlock: --
The <<X56,code>>, <<X57,source>> and <<X58,music>> filter blocks are
detailed in the <<X59,Filters>> section.
<<X56,代码>>, <<X57,来源>> 和 <<X58,音乐>> 过滤器块在 <<X59,过滤器>> 段落有详细介绍。
.Default DelimitedBlock substitutions
[cols="2e,7*^",frame="topbot",options="header,autowidth"]
|=====================================================
| |Attributes |Callouts |Macros | Quotes |Replacements
|Special chars |Special words
|PassthroughBlock |Yes |No |Yes |No |No |No |No
|ListingBlock |No |Yes |No |No |No |Yes |No
|LiteralBlock |No |Yes |No |No |No |Yes |No
|SidebarBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
|QuoteBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
|ExampleBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
|OpenBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
|=====================================================
清单块
~~~~~~~~~~~~~~
'ListingBlocks' are rendered verbatim in a monospaced font, they
retain line and whitespace formatting and are often distinguished by a
background or border. There is no text formatting or substitutions
within Listing blocks apart from Special Characters and Callouts.
Listing blocks are often used for computer output and file listings.
Here's an example:
[listing]
......................................
--------------------------------------
#include <stdio.h>
int main() {
printf("Hello World!\n");
exit(0);
}
--------------------------------------
......................................
Which will be rendered like:
--------------------------------------
#include <stdio.h>
int main() {
printf("Hello World!\n");
exit(0);
}
--------------------------------------
By convention <<X59,filter blocks>> use the listing block syntax and
are implemented as listing block styles.
[[X65]]
文字块
~~~~~~~~~~~~~~
'文字块' 就像文字段落，只是不用内容缩进.
如果文字块应用了 'listing' 样式就会表现为一个清单块 (这样方便了你使用一个列表包含一个清单块).
---------------------------------------------------------------------
...................................
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
...................................
---------------------------------------------------------------------
效果：
...................................
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
...................................
侧边栏
~~~~~~~~~~~~~~
侧边栏是一小段推荐的文字漂浮于主文本的外侧。侧边栏由一个边框包围着独立于主文本。
侧边栏内容就像正常的段落
下面是例子:
---------------------------------------------------------------------
.侧边栏例子
************************************************
Any AsciiDoc SectionBody element (apart from
SidebarBlocks) can be placed inside a sidebar.
************************************************
---------------------------------------------------------------------
效果如下:
.侧边栏例子
************************************************
Any AsciiDoc SectionBody element (apart from
SidebarBlocks) can be placed inside a sidebar.
************************************************
应用 'abstract' 样式转换摘要，例如：
---------------------------------------------------------------------
[abstract]
************************************************
In this paper we will attempt to...
************************************************
---------------------------------------------------------------------
[[X26]]
注释块
~~~~~~~~~~~~~~
The contents of CommentBlocks are not processed; they are useful for
annotations and for excluding new or outdated content that you don't
want displayed. CommentBlocks are never written to output files.
Example:
---------------------------------------------------------------------
//////////////////////////////////////////
CommentBlock contents are not processed by
asciidoc(1).
//////////////////////////////////////////
---------------------------------------------------------------------
参见 <<X25,行注释>>。
NOTE: System macros are executed inside comment blocks.
[[X76]]
Passthrough Blocks
~~~~~~~~~~~~~~~~~~
By default the block contents is subject to attribute and macro
substitution, no other markup is generated. PassthroughBlock content
will often be backend specific. Here's an example:
---------------------------------------------------------------------
++++++++++++++++++++++++++++++++++++++
<table border="1"><tr>
<td>Cell 1</td>
<td>Cell 2</td>
</tr></table>
++++++++++++++++++++++++++++++++++++++
---------------------------------------------------------------------
Use and explicit 'subs' attribute to control substitution. The
following styles can be applied to passthrough blocks:
pass::
By default no substitutions are performed.
asciimath, latexmath::
By default no substitutions are performed, the contents are rendered
as <<X78,mathematical formulas>>.
引用块
~~~~~~~~~~~~
'QuoteBlocks' are used for quoted passages of text. There are two
styles: 'quote' and 'verse'. The style is set by the first positional
attribute, if no style attribute is specified the 'quote' style. The
optional 'attribution' and 'citetitle' attributes (positional
attributes 2 and 3) specify the quote's author and source.
The 'quote' style treats the content like a SectionBody, for example:
---------------------------------------------------------------------
[quote, Bertrand Russell, The World of Mathematics (1956)]
____________________________________________________________________
A good notation has subtlety and suggestiveness which at times makes
it almost seem like a live teacher.
____________________________________________________________________
---------------------------------------------------------------------
Which is rendered as:
[quote, Bertrand Russell, The World of Mathematics (1956)]
____________________________________________________________________
A good notation has subtlety and suggestiveness which at times makes
it almost seem like a live teacher.
____________________________________________________________________
The 'verse' style
retains the content's line breaks, for example:
---------------------------------------------------------------------
[verse, William Blake, from Auguries of Innocence]
__________________________________________________
To see a world in a grain of sand,
And a heaven in a wild flower,
Hold infinity in the palm of your hand,
And eternity in an hour.
__________________________________________________
---------------------------------------------------------------------
Which is rendered as:
[verse, William Blake, from Auguries of Innocence]
__________________________________________________
To see a world in a grain of sand,
And a heaven in a wild flower,
Hold infinity in the palm of your hand,
And eternity in an hour.
__________________________________________________
[[X48]]
样例块
~~~~~~~~~~~~~~
'ExampleBlocks' encapsulate the DocBook Example element and are used
for, well, examples. Example blocks can be titled by preceding them
with a 'BlockTitle'. DocBook toolchains normally number examples and
generate a 'List of Examples' backmatter section.
Example blocks are delimited by lines of equals characters and you can
put any block elements apart from Titles, BlockTitles and Sidebars)
inside an example block. For example:
---------------------------------------------------------------------
.An example
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
=====================================================================
---------------------------------------------------------------------
Renders:
.An example
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
=====================================================================
A title prefix that can be inserted with the `caption` attribute
(`xhtml11` and `html4` backends). For example:
---------------------------------------------------------------------
[caption="Example 1: "]
.An example with a custom caption
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
=====================================================================
---------------------------------------------------------------------
[[X22]]
警告块
~~~~~~~~~~~~~~~~~
The 'ExampleBlock' definition includes a set of admonition
<<X23,styles>> (NOTE, TIP, IMPORTANT, WARNING, CAUTION) for generating
admonition blocks (admonitions containing more than just a
<<X28,simple paragraph>>). Just precede the ExampleBlock with an
attribute list containing the admonition style name. For example:
---------------------------------------------------------------------
[NOTE]
.A NOTE block
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
.. Fusce euismod commodo velit.
.. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum
nunc consequat lobortis.
=====================================================================
---------------------------------------------------------------------
Renders:
[NOTE]
.A NOTE block
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
.. Fusce euismod commodo velit.
.. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum
nunc consequat lobortis.
=====================================================================
See also <<X47,Admonition Icons and Captions>>.
[[X29]]
开放块
~~~~~~~~~~~
An 'OpenBlock' renders the block contents without any opening or
closing tags. The open block start and end delimiter is a single line
containing two dashes. Enclosed elements are rendered just as they
would inside a section body. Open blocks are used for <<X15,list item
continuation>>.
[[X64]]
列表
-----
.列表类型
- 项目符号列表。也称为分项或无序列表。
- 编号列表。又称为有序列表。
- 标记列表。有时被称为变量或定义列表。
- 标注名单（名单标注说明）。
.List behavior
- List item indentation is optional and does not determine nesting,
indentation does however make the source more readable.
- Another list or a literal paragraph immediately following a list
item will be implicitly included in the list item; use <<X15, list
item continuation>> to explicitly append other block elements to a
list item.
- A comment block or a comment line block macro element will terminate
a list -- use inline comment lines to put comments inside lists.
- The `listindex` <<X60,intrinsic attribute>> is the current list item
index (1..). If this attribute is not inside a list then it's value
is the number of items in the most recently closed list. Useful for
displaying the number of items in a list.
.List behavior
- 列表项的缩进是可选的，并不决定嵌套，但可以使源文件更具可读性。
- 另一份清单或文字段落紧跟一个列表项目将包含进改列表项目；使用<<X15,列表项连续性>>标明追加其他块元素列表项。
- A comment block or a comment line block macro element will terminate
a list -- use inline comment lines to put comments inside lists.
- The `listindex` <<X60,intrinsic attribute>> is the current list item
index (1..). If this attribute is not inside a list then it's value
is the number of items in the most recently closed list. Useful for
displaying the number of items in a list.
项目符号列表
~~~~~~~~~~~~~~
Bulleted list items start with a single dash or one to five asterisks
followed by some white space then some text. Bulleted list syntaxes
are:
...................
- List item.
* List item.
** List item.
*** List item.
**** List item.
***** List item.
...................
编号列表
~~~~~~~~~~~~~~
List item numbers are explicit or implicit.
.Explicit numbering
List items begin with a number followed by some white space then the
item text. The numbers can be decimal (arabic), roman (upper or lower
case) or alpha (upper or lower case). Decimal and alpha numbers are
terminated with a period, roman numbers are terminated with a closing
parenthesis. The different terminators are necessary to ensure 'i',
'v' and 'x' roman numbers are are distinguishable from 'x', 'v' and
'x' alpha numbers. Examples:
.....................................................................
1. Arabic (decimal) numbered list item.
a. Lower case alpha (letter) numbered list item.
F. Upper case alpha (letter) numbered list item.
iii) Lower case roman numbered list item.
IX) Upper case roman numbered list item.
.....................................................................
.Implicit numbering
List items begin one to five period characters, followed by some white
space then the item text. Examples:
.....................................................................
. Arabic (decimal) numbered list item.
.. Lower case alpha (letter) numbered list item.
... Lower case roman numbered list item.
.... Upper case alpha (letter) numbered list item.
..... Upper case roman numbered list item.
.....................................................................
You can use the 'style' attribute to specify an alternative numbering
style. The numbered list style can be one of the following values:
'arabic', 'loweralpha', 'upperalpha', 'lowerroman', 'upperroman'.
Here are some examples of bulleted and numbered lists:
---------------------------------------------------------------------
- Praesent eget purus quis magna eleifend eleifend.
1. Fusce euismod commodo velit.
a. Fusce euismod commodo velit.
b. Vivamus fringilla mi eu lacus.
c. Donec eget arcu bibendum nunc consequat lobortis.
2. Vivamus fringilla mi eu lacus.
i) Fusce euismod commodo velit.
ii) Vivamus fringilla mi eu lacus.
3. Donec eget arcu bibendum nunc consequat lobortis.
4. Nam fermentum mattis ante.
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
* Fusce euismod commodo velit.
** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
vel.
** Vivamus fringilla mi eu lacus.
* Donec eget arcu bibendum nunc consequat lobortis.
- Nulla porttitor vulputate libero.
. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
[upperroman]
.. Fusce euismod commodo velit.
.. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum nunc consequat lobortis.
---------------------------------------------------------------------
Which render as:
- Praesent eget purus quis magna eleifend eleifend.
1. Fusce euismod commodo velit.
a. Fusce euismod commodo velit.
b. Vivamus fringilla mi eu lacus.
c. Donec eget arcu bibendum nunc consequat lobortis.
2. Vivamus fringilla mi eu lacus.
i) Fusce euismod commodo velit.
ii) Vivamus fringilla mi eu lacus.
3. Donec eget arcu bibendum nunc consequat lobortis.
4. Nam fermentum mattis ante.
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
* Fusce euismod commodo velit.
** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
vel.
** Vivamus fringilla mi eu lacus.
* Donec eget arcu bibendum nunc consequat lobortis.
- Nulla porttitor vulputate libero.
. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
[upperroman]
.. Fusce euismod commodo velit.
.. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum nunc consequat lobortis.
A predefined 'compact' option is available to bulleted and numbered
lists -- this translates to the DocBook 'spacing="compact"' lists
attribute which may or may not be processed by the DocBook toolchain.
Example:
[options="compact"]
- Compact list item.
- Another compact list item.
TIP: To apply the 'compact' option globally define a document-wide
'compact-option' attribute, e.g. using the `-a compact-option`
command-line option.
标记列表
~~~~~~~~~~~~~
Labeled list items consist of one or more text labels followed the
text of the list item.
An item label begins a line with an alphanumeric character hard
against the left margin and ends with one to four colons or two
semi-colons. A list item can have multiple labels, one per line.
The list item text consists of one or more lines of text starting
after the last label (either on the same line or a new line) and can
be followed by nested List or ListParagraph elements. Item text can be
optionally indented.
Here are some examples:
---------------------------------------------------------------------
In::
Lorem::
Fusce euismod commodo velit.
Fusce euismod commodo velit.
Ipsum:: Vivamus fringilla mi eu lacus.
* Vivamus fringilla mi eu lacus.
* Donec eget arcu bibendum nunc consequat lobortis.
Dolor::
Donec eget arcu bibendum nunc consequat lobortis.
Suspendisse;;
A massa id sem aliquam auctor.
Morbi;;
Pretium nulla vel lorem.
In;;
Dictum mauris in urna.
Vivamus::: Fringilla mi eu lacus.
Donec::: Eget arcu bibendum nunc consequat lobortis.
---------------------------------------------------------------------
Which render as:
In::
Lorem::
Fusce euismod commodo velit.
Fusce euismod commodo velit.
Ipsum:: Vivamus fringilla mi eu lacus.
* Vivamus fringilla mi eu lacus.
* Donec eget arcu bibendum nunc consequat lobortis.
Dolor::
Donec eget arcu bibendum nunc consequat lobortis.
Suspendisse;;
A massa id sem aliquam auctor.
Morbi;;
Pretium nulla vel lorem.
In;;
Dictum mauris in urna.
Vivamus::: Fringilla mi eu lacus.
Donec::: Eget arcu bibendum nunc consequat lobortis.
Horizontal labeled list style
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The 'horizontal' labeled list style places the list text side-by-side
with the label instead of under the label. Here is an example:
---------------------------------------------------------------------
[horizontal]
*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
labitur dolorum an. Est ne magna primis adolescens.
Fusce euismod commodo velit.
*Ipsum*:: Vivamus fringilla mi eu lacus.
- Vivamus fringilla mi eu lacus.
- Donec eget arcu bibendum nunc consequat lobortis.
*Dolor*::
- Vivamus fringilla mi eu lacus.
- Donec eget arcu bibendum nunc consequat lobortis.
---------------------------------------------------------------------
Which render as:
[horizontal]
*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
labitur dolorum an. Est ne magna primis adolescens.
Fusce euismod commodo velit.
*Ipsum*:: Vivamus fringilla mi eu lacus.
- Vivamus fringilla mi eu lacus.
- Donec eget arcu bibendum nunc consequat lobortis.
*Dolor*::
- Vivamus fringilla mi eu lacus.
- Donec eget arcu bibendum nunc consequat lobortis.
[NOTE]
=====================================================================
- Current PDF toolchains do not make a good job of determining
the relative column widths for horizontal labeled lists.
- If you are generating DocBook markup then horizontal labeled lists
should not be nested because the 'DocBook XML V4.2' DTD does not
permit nested informal tables (although <<X13,DocBook XSL
Stylesheets>> and <<X31,dblatex>> process them correctly).
- The label width can be set as a percentage of the total width by
setting the 'width' attribute e.g. `width="10%"`
=====================================================================
答问列表
~~~~~~~~~~~~~~~~~~~~~~~~~
AsciiDoc comes pre-configured with a 'qanda' style labeled list for generating
DocBook question and answer (Q&A) lists. Example:
---------------------------------------------------------------------
[qanda]
Question one::
Answer one.
Question two::
Answer two.
---------------------------------------------------------------------
Renders:
[qanda]
Question one::
Answer one.
Question two::
Answer two.
专业术语列表
~~~~~~~~~~~~~~
AsciiDoc comes pre-configured with a 'glossary' style labeled list for
generating DocBook glossary lists. Example:
---------------------------------------------------------------------
[glossary]
A glossary term::
The corresponding definition.
A second glossary term::
The corresponding definition.
---------------------------------------------------------------------
For working examples see the `article.txt` and `book.txt` documents in
the AsciiDoc `./doc` distribution directory.
NOTE: To generate valid DocBook output glossary lists must be located
in a glossary section.
参考书目列表
~~~~~~~~~~~~~~~~~~
AsciiDoc comes with a predefined 'bibliography' bulleted list style
generating DocBook bibliography entries. Example:
---------------------------------------------------------------------
[bibliography]
- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
Programming'. Addison-Wesley. ISBN 0-13-142901-9.
- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
'DocBook - The Definitive Guide'. O'Reilly & Associates.
1999. ISBN 1-56592-580-7.
---------------------------------------------------------------------
The `[[[<reference>]]]` syntax is a bibliography entry anchor, it
generates an anchor named `<reference>` and additionally displays
`[<reference>]` at the anchor position. For example `[\[[taoup]]]`
generates an anchor named `taoup` that displays `[taoup]` at the
anchor position. Cite the reference from elsewhere your document using
`<<taoup>>`, this displays a hyperlink (`[taoup]`) to the
corresponding bibliography entry anchor.
For working examples see the `article.txt` and `book.txt` documents in
the AsciiDoc `./doc` distribution directory.
NOTE: To generate valid DocBook output bibliography lists must be
located in a bibliography section.
[[X15]]
列表项连续
~~~~~~~~~~~~~~~~~~~~~~
Another list or a literal paragraph immediately following a list item
is implicitly appended to the list item; to append other block
elements to a list item you need to explicitly join them to the list
item with a 'list continuation' (a separator line containing a single
plus character). Multiple block elements can be appended to a list
item using list continuations (provided they are legal list item
children in the backend markup).
Here are some examples of list item continuations: list item one
contains multiple continuations; list item two is continued with an
<<X29,OpenBlock>> containing multiple elements:
---------------------------------------------------------------------
1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.
2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.
a. This list is nested and does not require explicit item continuation.
+
This paragraph is part of the preceding list item.
b. List item b.
This paragraph belongs to item two of the outer list.
--
---------------------------------------------------------------------
Renders:
1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.
2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.
a. This list is nested and does not require explicit item continuation.
+
This paragraph is part of the preceding list item.
b. List item b.
This paragraph belongs to item two of the outer list.
--
脚注
---------
The shipped AsciiDoc configuration includes the `footnote:[<text>]`
and `footnoteref:[<id>,<text>]` inline macros for generating
footnotes:
- The `footnote` macro generates a footnote.
- The `footnoteref` macro has two forms: if the text is supplied a
foot note with an ID is generated; if the text is omitted a
reference to the footnote with the specified ID is generated.
- The footnote text can span multiple lines.
Example footnote:
A footnote footnote:[An example footnote.];
a second footnote with a reference ID footnoteref:[note2,Second footnote.];
finally a reference to the second footnote footnoteref:[note2].
Which renders:
A footnote footnote:[An example footnote.];
a second footnote with a reference ID footnoteref:[note2,Second footnote];
finally a reference to the second footnote footnoteref:[note2].
Footnotes are primarily useful when generating DocBook output --
DocBook conversion programs render footnote outside the primary text
flow.
索引
-------
The shipped AsciiDoc configuration includes the inline macros for
generating document index entries.
`indexterm:[<primary>,<secondary>,<tertiary>]`::
`(((<primary>,<secondary>,<tertiary>)))`::
This inline macro generates an index term (the <secondary> and
<tertiary> attributes are optional). For example
`indexterm:[Tigers,Big cats]` (or, using the alternative syntax
`(((Tigers,Big cats)))`. Index terms that have secondary and
tertiary entries also generate separate index terms for the
secondary and tertiary entries. The index terms appear in the
index, not the primary text flow.
`indexterm2:[<primary>]`::
`((<primary>))`::
This inline macro generates an index term that appears in both the
index and the primary text flow. The `<primary>` should not be
padded to the left or right with white space characters.
For working examples see the `article.txt` and `book.txt` documents in
the AsciiDoc `./doc` distribution directory.
NOTE: Index entries only really make sense if you are generating
DocBook markup -- DocBook conversion programs automatically generate
an index at the point an 'Index' section appears in source document.
执行输出
--------
Callouts are a mechanism for annotating verbatim text (source code,
computer output and user input for example). Callout markers are
placed inside the annotated text while the actual annotations are
presented in a callout list after the annotated text. Here's an
example:
---------------------------------------------------------------------
.MS-DOS directory listing
-----------------------------------------------------
10/17/97 9:04 <DIR> bin
10/16/97 14:11 <DIR> DOS \<1>
10/16/97 14:40 <DIR> Program Files
10/16/97 14:46 <DIR> TEMP
10/17/97 9:04 <DIR> tmp
10/16/97 14:37 <DIR> WINNT
10/16/97 14:25 119 AUTOEXEC.BAT \<2>
2/13/94 6:21 54,619 COMMAND.COM \<2>
10/16/97 14:25 115 CONFIG.SYS \<2>
11/16/97 17:17 61,865,984 pagefile.sys
2/13/94 6:21 9,349 WINA20.386 \<3>
-----------------------------------------------------
\<1> This directory holds MS-DOS.
\<2> System startup code for DOS.
\<3> Some sort of Windows 3.1 hack.
---------------------------------------------------------------------
Which renders:
.MS-DOS directory listing
-----------------------------------------------------
10/17/97 9:04 <DIR> bin
10/16/97 14:11 <DIR> DOS <1>
10/16/97 14:40 <DIR> Program Files
10/16/97 14:46 <DIR> TEMP
10/17/97 9:04 <DIR> tmp
10/16/97 14:37 <DIR> WINNT
10/16/97 14:25 119 AUTOEXEC.BAT <2>
2/13/94 6:21 54,619 COMMAND.COM <2>
10/16/97 14:25 115 CONFIG.SYS <2>
11/16/97 17:17 61,865,984 pagefile.sys
2/13/94 6:21 9,349 WINA20.386 <3>
-----------------------------------------------------
<1> This directory holds MS-DOS.
<2> System startup code for DOS.
<3> Some sort of Windows 3.1 hack.
.Explanation
- The callout marks are whole numbers enclosed in angle brackets that
refer to an item index in the following callout list.
- By default callout marks are confined to LiteralParagraphs,
LiteralBlocks and ListingBlocks (although this is a configuration
file option and can be changed).
- Callout list item numbering is fairly relaxed -- list items can
start with `<n>`, `n>` or `>` where `n` is the optional list item
number (in the latter case list items starting with a single `>`
character are implicitly numbered starting at one).
- Callout lists should not be nested -- start list items hard against
the left margin.
- If you want to present a number inside angle brackets you'll need to
escape it with a backslash to prevent it being interpreted as a
callout mark.
NOTE: To include callout icons in PDF files generated by
<<X43,a2x(1)>> you need to use the `--icons` command-line option.
运行记录
~~~~~~~~~~~~~~~~~~~~
Callout marks are generated by the 'callout' inline macro while
callout lists are generated using the 'callout' list definition. The
'callout' macro and 'callout' list are special in that they work
together. The 'callout' inline macro is not enabled by the normal
'macros' substitutions option, instead it has its own 'callouts'
substitution option.
The following attributes are available during inline callout macro
substitution:
`{index}`::
The callout list item index inside the angle brackets.
`{coid}`::
An identifier formatted like `CO<listnumber>-<index>` that
uniquely identifies the callout mark. For example `CO2-4`
identifies the fourth callout mark in the second set of callout
marks.
The `{coids}` attribute can be used during callout list item
substitution -- it is a space delimited list of callout IDs that refer
to the explanatory list item.
包含运行输出到包含代码
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can annotate working code examples with callouts -- just remember
to put the callouts inside source code comments. This example displays
the `test.py` source file (containing a single callout) using the
<<X57,Source Code Highlighter Filter>>:
.AsciiDoc source
---------------------------------------------------------------------
[source,python]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\include::test.py[]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
\<1> Print statement.
---------------------------------------------------------------------
.Included `test.py` source
---------------------------------------------------------------------
print 'Hello World!' # \<1>
---------------------------------------------------------------------
宏
------
Macros are a mechanism for substituting parametrized text into output
documents.
Macros have a 'name', a single 'target' argument and an 'attribute
list'. The usual syntax is `<name>:<target>[<attrlist>]` (for
inline macros) and `<name>::<target>[<attrlist>]` (for block
macros). Here are some examples:
http://www.methods.co.nz/asciidoc/index.html[Asciidoc home page]
include::chapt1.txt[tabsize=2]
mailto:[email protected][]
.Macro behavior
- `<name>` is the macro name. It can only contain letters, digits or
dash characters and cannot start with a dash.
- The optional `<target>` cannot contain white space characters.
- `<attrlist>` is a <<X21,list of attributes>> enclosed in square
brackets.
- `]` characters in attribute lists that are enclosed in `[]` brackets
must be escaped with a backslash.
- Expansion of non-system macro references can normally be escaped by
prefixing a backslash character (see the AsciiDoc 'FAQ' for examples
of exceptions to this rule).
- System macros cannot be escaped.
- Attribute references in block macros are expanded.
- The substitutions performed prior to Inline macro macro expansion
are determined by the inline context.
- Macros are processed in the order they appear in the configuration
file(s).
- Calls to inline macros can be nested inside different inline macros
(an inline macro call cannot contain a nested call to itself).
- In addition to `<name>`, `<target>` and `<attrlist>` the
`<passtext>` and `<subslist>` named groups are available to
<<X77,passthrough macros>>. A macro is a passthrough macro if the
definition includes a `<passtext>` named group.
内置宏
~~~~~~~~~~~~~
Inline Macros occur in an inline element context. Predefined Inline
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:[email protected][email Joe Bloggs]
[email protected]
Which are rendered:
http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]
http://www.methods.co.nz/asciidoc/
mailto:[email protected][email Joe Bloggs]
[email protected]
- 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 `<`.
<=<
引用文本部分
~~~~~~~~~~~~~~~~~~~
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: [email protected]
: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 ` `
instead of ` `).
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 & 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
|====================================================================