0001-writing-in-asciidoc.adoc

Writing in AsciiDoc

---

文章更新历史：

• 2017/11/19 文章发布

---

Table of Contents

• 1. 一切皆代码
• 2. AsciiDoc
  • 2.1. Why AsciiDoc
  • 2.2. AsciiDoctor
  • 2.3. 编辑与渲染
    • 2.3.1. 编辑器
    • 2.3.2. GitHub
• 3. 基本用法
  • 3.1. 标题
    • 3.1.1. 文章标题
    • 3.1.2. 章节标题
    • 3.1.3. 块标题
  • 3.2. 段落
  • 3.3. 列表
    • 3.3.1. 无序号列表
    • 3.3.2. 序号列表
    • 3.3.3. 标签列表
    • 3.3.4. 复杂情形
  • 3.4. 表格
    • 3.4.1. 表1
    • 3.4.2. 表2
    • 3.4.3. 表3
    • 3.4.4. 表4
    • 3.4.5. 表5 (CVS)
  • 3.5. URI链接
    • 3.5.1. 外部链接
    • 3.5.2. 相对路径
  • 3.6. 图片
  • 3.7. 块
    • 3.7.1. 代码块
    • 3.7.2. Example块
    • 3.7.3. 引用
    • 3.7.4. 列举块
    • 3.7.5. 提示、警告等
• 4. 高级用法

1. 一切皆代码

随着代码越写越多，软件开发经验的不断积累，程序员会变得越来越“谨小慎微”。 做任何一个代码提交前，都会仔细地确认所做的修改。而这需要版本管理系统的支持才可做到。 如果所做的工作没有版本管理，那么可能会是一件很不痛快的事情。

在程序员的日常工作中，除了要编写软件的源代码，还经常需要撰写一些技术文档（包括一些架构设计图等）。 而在部分程序员眼中，“一切皆代码”是一件应当努力追求的事情，不论是技术文档还是设计图。

以自己为例，会把所有的代码、文字存于GitHub（公开信息）或者Bitbucket（非公开信息）。

2. AsciiDoc

2.1. Why AsciiDoc

在软件开发社区中，Markdown是被大家广泛接受的一个文档写作工具，其语法简单、支持工具众多。 但正因为其语法简单，支持的特性相对贫乏，无法满足稍微复杂一点的写作诉求。 于是产生了很多第三方衍生版本，其中最有名的衍生版本应该是GFM（GitHub Flavored Markdown）。 尽管有了特性更丰富的众多衍生版本，但依然有一些写作需求得不到满足。 例如，无法在节标题中添加编号，无法为代码块添加解读说明，等等。

这世界上还有很多写作工具，其目标用户和使用场景各不相同。AscciDoc就是其中一个，语法相对简单却又功能丰富。 既可以像Markdown那样简单使用，也可以用上更多特性，解决我们的绝大多数写作诉求。 幸运的是，GitHub除了支持自家的GFM，同时也还支持AsciiDoc。

2.2. AsciiDoctor

那AsciiDoctor又是什么？用其官方网站的一句话解释：

A fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more.

— AsciiDoctor

2.3. 编辑与渲染

AsciiDoc文档的文件后缀一般用 adoc 或者 asc，在常见编辑器及GitHub中都支持。

2.3.1. 编辑器

支持AsciiDoc文档编辑与渲染（预览）的工具很多，个人推荐Atom（同样适用于Markdown），只需要安装如下插件即可:

• language-asciidoc

• asciidoc-preview

2.3.2. GitHub

如果想测试AsciiDoc在GitHub上的渲染效果，建议在你的GitHubGist帐户中创建一个测试文件（xxx.adoc）， 可以反复修复文件，查看效果。

GitHub虽然支持AsciiDoc文档的渲染，但效果比起上面的Atom插件就差多了，不过将就看就行。

为了让你的AsciiDoc文档在GitHub上更好看一点，可以做一些配置:

1. 提示、警告块的图标

   在AsciiDoc文档header中添加如下设置项，即可在GitHub上为『提示』、『警告』块加上图标（默认为文字）：

   ifdef::env-github[]
   :note-caption: :paperclip:
   :tip-caption: :bulb:
   :important-caption: :exclamation:
   :caution-caption: :fire:
   :warning-caption: :warning:
   endif::[]

   💡	参见本文档header部分。

3. 基本用法

3.1. 标题

在AsciiDoc中，有三类标题：

• 文章标题

• 章节标题

• 块标题

所有标题都是可选的。

3.1.1. 文章标题

见本文第一行就是，也请关注下其下的header信息。

在AsciiDoc中，文章标题用 = 来标识，但也可以用Markdown中的 # 来标识。

💡	在文章标题和第一个章节标题之间的内容是序文，可有可无。

3.1.2. 章节标题

其标识符同『文章标题』，共支持5级（2个~6个标识符）。

💡	第一级章节标题（2个 ##）对应HTML中的<h2>。

3.1.3. 块标题

在AsciiDoc中，很多元素都可以带一个『块标题』，举例如下。

这是一段文字的标题

这是一段文字，写的什么不重要，重要的是，它有一个标题。 这是一段文字，写的什么不重要，重要的是，它有一个标题。 这是一段文字，写的什么不重要，重要的是，它有一个标题。

这是一个列表的标题

• 列表项

• 列表项

• 列表项

这是一个代码块的标题

cout << "Hello, world" << endl;

💡	还有很多，当不确定时，加个标题试试看。

3.2. 段落

在段落中，有时，不想分段，但想强制换行，可以这样：
用一个 + 就可以了。

3.3. 列表

3.3.1. 无序号列表

下面是一个无序号列表：

这是一个列表（可选）

• 列表项

• 列表项

• 列表项

下面是一个嵌套殂：

这是一个嵌套列表（可选）

• 列表项

  • 嵌套列表项

  • 嵌套列表项

    • 嵌套列表项

• 列表项

• 列表项

3.3.2. 序号列表

这是一个列表（可选）

1. 列表项

2. 列表项

3. 列表项

这是另外一个列表

0. 列表项

1. 列表项，这行内容有长， 需要换行

2. 列表项

这是一个嵌套列表

1. 列表项

2. 列表项

   1. 嵌套列表项， 太长，需要换行

   2. 嵌套列表项

3. 列表项

3.3.3. 标签列表

这是一个标签列表

标签1

标签的相关解释

标签2

标签的相关解释

这是另一个标签列表（水平）

标签1	标签的相关解释
标签2	标签的相关解释

这是一个有嵌套的标签列表

标签1

标签的相关解释

标签2

标签的相关解释：

1. 列表项

2. 列表项

3.3.4. 复杂情形

这是一个比较复杂的列表

1. 列表项

   看一段代码：

   executeTask(a -> a * 2, 10);

   多来几个段落

   📎

   这是一个说明

2. 列表项

   这儿有一些东西需要框起来

   📎

   这是另外一个说明

3.4. 表格

表格的文档见： http://asciidoc.org/userguide.html#_tables

3.4.1. 表1

Table 1. 这是表名（可选）

列名1	列名2	列名3
row 1, column 1	row 1, column 2	row 1, column 3
row 2, column 1	row 2, column 2	row 2, column 3

3.4.2. 表2

列名1	列名2	列名3
row 1, column 1	row 1, column 2	row 1, column 3
row 2, column 1	row 2, column 2	row 2, column 3

3.4.3. 表3

Table 2. 这是表名

row 1, column 1	row 1, column 2	row 1, column 3, 这行有点长，需要换行哦
row 2, column 1	row 2, column 2	row 2, column 3

3.4.4. 表4

Table 3. 这是表名

列名1	列名2	列名3
row 1, column 1	row 1, column 2	这儿有一个内嵌的列表： 列表项1 列表项2 列表项3
row 2, column 1	row 2, column 2	row 2, column 3
footer1	footer2	footer3

3.4.5. 表5 (CVS)

Table 4. 这是表名

ID	Nickname	Email
xxx	Tom	[email protected]
yyy	Cat	[email protected]

3.5. URI链接

3.5.1. 外部链接

在文字中有一个链接 https://github.com/yongce ，会被自动识别。

如果不想显示URI的scheme，可以在文档的header中添加如下选项：

:hide-uri-scheme:

如果想用文字来代替显示URL，可以这样做 Yongce@GitHub。

3.5.2. 相对路径

跳转到本仓库的README文档：README

3.6. 图片

1. 最简版本：

   

2. 可以给图片加上标题，还可以为其指定跳转连接：

   

   Figure 1. 这是图片标题

3. 在文字中嵌入图片 ，看到了么

3.7. 块

3.7.1. 代码块

当我们需要显示代码，或者希望像显示代码一样去显示内容时，就应该用『代码块』来解决。 『代码块』由两行4个或者更多 - 来限定其中的内容。

这是一段代码

@FunctionalInterface (1)
interface OperatorTypeOne {
    int operate(int value); (2)
}

1. 代码解释1

2. 代码解释2

3.7.2. Example块

Example 1. 标题

这是Xxx的说明

该这样使用，示例如下

3.7.3. 引用

这是某某曾经说过的话

这是某位名人说过的话。。。

具体内容是什么不知道。。。

— 小二
2017年11月XXX村

3.7.4. 列举块

$ adb root
$ adb remount

3.7.5. 提示、警告等

支持的所有提示、警告类别如下（并示例其简单写法，如 TIP: xxxx）：

1. NOTE

   📎

   这是一段说明

2. TIP

   💡

   这是一段说明

3. IMPORTANT

   ❗

   这是一段说明

4. CAUTION

   🔥

   这是一段说明

5. WARNING

   ⚠️

   这是一段说明

还可以有另外一种形式，用块来处理更复杂的情况：

💡	这是一段示例代码： interface OperatorTypeTwoLong { long operate(long lhs, long rhg); }

4. 高级用法

TODO…​