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的主題。

大功告成！

總結

參考前人的經驗，總好過本身的獨斷獨行。