AsciiDoc
编写复杂技术文档时，AsciiDoc 比 Markdown 提供了更完善的功能， 比 LaTeX 安装和使用方便，它的优点包括：
-
方便的 live preview: 用文本编辑器编写一个扩展名为 adoc 或者 asc 的文本文件， 在浏览器里安装一个插件asciidoctor-browser-extension， 然后在浏览器里以打开本地文件方式打开这个文本文件就可以实时预览了， 不需要专门的IDE（插件），也不需要文件监控和定时刷新工具； 这个插件目前只支持单个 asciidoc 文档的预览，不支持嵌入其他文档：
include， 例如如果文档 book.adoc 中嵌入了另一个文档 hardware_os.adoc (include::hardware_os.adoc[leveloffset=+1]) 使用这个插件打开 book.adoc 后显示 Unresolved directive in book.adoc； -
内置 nested ordered list 支持: 不需要像 Markdown 那样借助于 pandoc 或者 RMarkdown 这种扩展：
. step 1 ... substep 1 ... substep 2 . step 2 -
强大的自定义表格功能，能够合并单元格和定义对齐样式等，见下面的样例中的说明；
-
内置 MathJax 支持：在章标题（
= Chapter Title）后面（在前面写无效） 加上:stem:，默认使用 AsciiMath 语法，比 Latex 更简洁，语法见 http://asciimath.org/#syntax 行内公式例如stem:[sqrt(4) = 2]，独立公式例如：[stem] ++++ sqrt(4) = 2 ++++ -
方便地生成流程图：支持生成 SVG 图，浏览器里可以直接预览；
-
方便地生成 PDF 文件：在浏览器里打印为 PDF 就可以了；
AsciiDoc 目前最活跃的分支是使用 Ruby 实现的 Asciidoctor， 它实现并拓展了 AsciiDoc 规范（二者区别见 Differences between Asciidoctor and AsciiDoc）， 另外还有 JavaScript, JRuby, Java 等实现。
Python 社区有官方(?)的 asciidoc-py3 以及个人项目 AsciiDoc3， 但整体来说 Python 社区的开发已经非常不活跃了，许多开发者 转向了 Asciidoctor.
安装和使用
gem install asciidoctor
将 asciidoc 文档转换为 HTML 文档：asciidoctor -a data-uri book.adoc
实时预览
In Console
cat << EOF > live_preview
#!/usr/bin/env python
import platform
import webbrowser
import subprocess
from livereload import Server, shell
COMPILE_CMD = 'asciidoctor -a data-uri book.adoc'
compile_html = subprocess.run(COMPILE_CMD.split(' '))
if platform.system() == 'Linux':
webbrowser.register("xdg-open", None, webbrowser.BackgroundBrowser(
"xdg-open"), preferred=True)
webbrowser.open('http://localhost:5500/book.html', new=2, autoraise=True)
server = Server()
server.watch('*.adoc', shell(COMPILE_CMD, cwd='.'))
server.serve(root='.', host='0.0.0.0', port=5500)
EOF
解决 Tmux 中频繁 alert 问题：
每次文档变化时 livereload 服务都会在控制台打印日志， 运行 livereload 服务的标题会不断被高亮，很烦人。
解决方法是在此 window 的 tmux 命令提示符后运行：
set-window-option -t:0 monitor-activity on
GUI Solution
VS Code + Asciidoc language pack
一个复杂表格样例
表格定义中比较复杂的部分在于列定义和单元格定义，
其中列定义格式为：
单元格定义格式为：[<span>*|+][<align>][<style>]，
例如下面的示例中 1.4+^.^ 是一个合并了4行的单元格，
1.4+ 中的 + 表示合并单元格（而不是 * 代表的复制单元格），1.4 表示占据1列4行，
^.^ 定义对齐样式 [<horizontal>][.<vertical>]，表示左右、上下都是居中，
还可以是 < 表示左对齐，> 表示右对齐，
| 后面是单元格里的文字。
详细格式参考 Tables in AsciiDoc User Guide
.IEC61400-1 第3版中对风力发电机组的分级
[width="100%",cols="^3,^2,^2,^2,^3",options="header"]
|========================
|WTGS 等级 |I |II |III |S
|$V_{ref}$(m/s) |50 |42.5 |37.5
1.4+^.^|由WTGS制造商规定各参数
|A $I_{15}$[-] 3.1+|0.16
|B $I_{15}$[-] 3.1+^.^|0.14
|C $I_{15}$[-] 3.1+^.^|0.12
|========================
with VS Code
VS Code 有完善的 Asciidoc 插件，能够输出为 PDF 文件。 配合 VS Code 的 vim 模式在 normal-insert 切换时自动打开/关系输入法，使用体验很好。 Windows 和 Ubuntu 上体验都不错。
reSturcturedText
Python 社区更多使用 reSturcturedText (RST) 格式， 有人用 vim, RST 和 Sphinx 写书， Google "restructuredtext write book" 可以找到一些文章，
RST 语法似乎不如 AsciiDoc 简洁，但考虑到 sphinx 包已经被集成到了 Anaconda 里，
且有一个 ReText 编辑器
（使用 apt install retext 安装）可以实现 live preview，
后续实现复杂需求时的成本估计会小于 AsciiDoc.
相关工具见 reStructuredText tool support，
以及一个简单的 Sphinx 教程：Sphinx Tutorial.
几个在线工具：
由于 Markdown, AsciiDoc 和 RST 之间可以通过 Pandoc 或者在线工具互相转换， 对于复杂文档的编写，可以先用 AsciiDoc 上手，如果遇到难以解决的问题再转为RST。