共计 1888 个字符，预计需要花费 5 分钟才能阅读完成。
引言
点开 spring-boot 的官方仓库，README 却不是我们熟知的 markdown 格式，而是 adoc。
adoc 的官网也明确列出了它的优势，可以装换为 HTML5、DocBook 及更多格式。
测试了一下，装换为网页后，效果还不错。
使用
安装
官网有好多种安装方法，APT、Homebrew、Chocolatey。
挺喜欢 Mac 下的 Homebrew 的，十分方便，但是看了好多篇博客，都是用的 Gem 安装，心里想着，第一次接触这个，还是在借鉴前人的好，万一碰到问题也可以查阅资料，遂选择了 Gem。
Gem 是 Ruby 的包管理器，我这里直接可以用，可能是系统自带的？
gem install asciidoctor
话不多说，进入 shell 就是敲。
Fetching: asciidoctor-1.5.8.gem (100%)
ERROR: While executing gem … (Gem::FilePermissionError)
You don’t have write permissions for the /Library/Ruby/Gems/2.3.0 directory.
错了，你没有写入 /Library/Ruby/Gems/2.3.0 的权限，上 sudo。
sudo gem install asciidoctor
Password:
Fetching: asciidoctor-1.5.8.gem (100%)
ERROR: While executing gem … (Gem::FilePermissionError)
You don’t have write permissions for the /usr/bin directory.
还是没有权限，你没有 /usr/bin 的权限，查阅了一下，在 MacOS 中，/usr/bin 是受系统保护的目录，即便是 root 也无权操作。
sudo gem install -n /usr/local/bin asciidoctor
解决方案，换一个目录：猜想可能是创建软链接的时候出现错误，/usr/bin 没有权限，那就把软链接放在 /usr/local/bin 里，一样可以用。
一路顺利，安装成功。
语法
撰写基本没什么问题，就是原来 markdown 中这么写，然后切换到 adoc 中改了一下格式。
官网有语法参考，和 Bootstrap 差不多，文档写得特别好。
会有示例的 demo，点击右上角的 view result，下面会弹出来这段文字最终显示的效果。
生成 HTML
生成 HTML 一点毛病都没有，很简单。
asciidoctor README.adoc
直接在后面写上文档名即可，即可生成同名的 HTML 文档。
用浏览器打开，效果还不错。
生成 PDF
生成 PDF 就没有那么顺利了。
安装 PDF 生成工具：
sudo gem install -n /usr/local/bin –pre asciidoctor-pdf
asciidoctor-pdf README.adoc
网上好多的解决方案虽然能解决，但是容易让人看懵圈，其实很简单的东西，就一直打这个命令，它提示什么，就安装什么。
asciidoctor: WARNING: gem ‘concurrent-ruby’ is not installed. This gem is recommended when registering custom converters.
提示少 concurrent-ruby，装。
sudo gem install -n /usr/local/bin concurrent-ruby
再执行，不报错了，PDF 也生成出来了，就是有问题。
大家应该也看出问题了，少字！
后来发现是字体的原理，字体没有这个字，就显示不出来。
安装字体
sudo asciidoctor-pdf-cjk-kai_gen_gothic-install
这里应该是网络的问题，我下了好多次，一直是网络超时。
最终放弃，去官方仓库手动下载字体。
下字体，也不知道哪个有用哪个没用，干脆就把一共 20 个字体都下下来了。
gem environment
找到 INSTALLATION DIRECTORY 一项，这就是 Gem 软件包安装目录。
/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/fonts
把下载的字体移动到该目录中。
asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=KaiGenGothicCN README.adoc
再次执行命令，执行时指定生成 PDF 的主题。
大功告成！
总结
参考前人的经验，总好过自己的一意孤行。
