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