ADOC Guide

引言

点开spring-boot的官方仓库,README却不是我们熟知的markdown格式,而是adoc

clipboard.png

ADOC Guide_第1张图片

adoc的官网也明确列出了它的优势,可以装换为HTML5DocBook及更多格式。

测试了一下,装换为网页后,效果还不错。

ADOC Guide_第2张图片

使用

安装

官网有好多种安装方法,APTHomebrewChocolatey

挺喜欢Mac下的Homebrew的,十分方便,但是看了好多篇博客,都是用的Gem安装,心里想着,第一次接触这个,还是在借鉴前人的好,万一碰到问题也可以查阅资料,遂选择了Gem

GemRuby的包管理器,我这里直接可以用,可能是系统自带的?

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里,一样可以用。

ADOC Guide_第3张图片

一路顺利,安装成功。

语法

撰写基本没什么问题,就是原来markdown中这么写,然后切换到adoc中改了一下格式。

官网有语法参考,和Bootstrap差不多,文档写得特别好。

ADOC Guide_第4张图片

会有示例的demo,点击右上角的view result,下面会弹出来这段文字最终显示的效果。

生成HTML

生成HTML一点毛病都没有,很简单。

asciidoctor README.adoc

直接在后面写上文档名即可,即可生成同名的HTML文档。

ADOC Guide_第5张图片

用浏览器打开,效果还不错。

ADOC Guide_第6张图片

生成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也生成出来了,就是有问题。

ADOC Guide_第7张图片

ADOC Guide_第8张图片

大家应该也看出问题了,少字!

后来发现是字体的原理,字体没有这个字,就显示不出来。

安装字体

sudo asciidoctor-pdf-cjk-kai_gen_gothic-install

这里应该是网络的问题,我下了好多次,一直是网络超时。

ADOC Guide_第9张图片

最终放弃,去官方仓库手动下载字体

下字体,也不知道哪个有用哪个没用,干脆就把一共20个字体都下下来了。

ADOC Guide_第10张图片

gem environment

ADOC Guide_第11张图片

找到INSTALLATION DIRECTORY一项,这就是Gem软件包安装目录。

/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/fonts

把下载的字体移动到该目录中。

ADOC Guide_第12张图片

asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=KaiGenGothicCN README.adoc

再次执行命令,执行时指定生成PDF的主题。

ADOC Guide_第13张图片

ADOC Guide_第14张图片

大功告成!

总结

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

你可能感兴趣的:(guide,doc,文档)