引言
点开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 asciidoctorPassword:
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-pdfasciidoctor-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的主题。
大功告成！
总结
参考前人的经验，总好过自己的一意孤行。