ADOC Guide

引言

点开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的主题。

大功告成！

总结

参考前人的经验，总好过自己的一意孤行。