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 的主題。
大功告成！
總結
參考前人的經驗，總好過自己的一意孤行。