Asciidoctor 入門與 pdf 中文測試

上一篇文章提到，asciidoctor-pdf 必須搭配 CJK 套件，否則在處理文字斷行的時候會有問題。在這篇筆記裡，我會進一步說明如何安裝 CJK 套件，以及如何指定欲使用的中文字型。

安裝

• Ruby 2.3.3 for Windows
  
• Bundler
  
  gem install bundler
  
  
• asciidoctor
  
  gem install asciidoctor
  
  
• asciidoctor-pdf
  
  gem install asciidoctor-pdf --pre
  
  
• asciidoctor-epub3
  
  gem install asciidoctor-epub3 --pre
  
  
• 為了讓程式碼有語法顏色，還要安裝其他套件。我裝過的有 CodeRay、Pygments、和 Rouge。其中 Pygments 無法正常運行，CodeRay 不支援 C# 語法，Rouge 支援 C# 語法而且顏色豐富，所以我安裝了 CodeRay 和 Rouge 。指令：

gem install rouge
gem install coderay


• 文字圖形套件： asciidoctor-diagram （選用）
  
  gem install asciidoctor-diagram
  
  

注意：若 Ruby 版本是 2.4，會在安裝 asciidoctor-epub3 時發生錯誤而導致安裝失敗，因為相依套件 nokogiri 需要 Ruby 2.4 以前的版本。

Hello, Asciidoctor

先看一個很簡單的範例，如下圖：

左邊是 AsciiDoc 文件，右邊是利用 asciidoctor-pdf 轉換成 PDF 檔案的結果。這個簡單的範例展示了：

• 檔頭屬性：前四行以冒號開頭的都是例如 :doctype: book。
• 章節標題： “==” 代表第二層標題。
• 段落內嵌程式碼
• 獨立程式碼區塊的樣式（語法顏色）：[source,c#]
• 程式碼連結外部說明（callout） : <1> 和 <2>
• 提示區塊：大寫的「WARNING:」會自動變成帶有警告圖示的文字方塊。

順便提一下，[source,c#] 裡面的 “c#” 必須是小寫字母 “c”。有一次我沒注意用了大寫，結果產生出來的文件沒有語法顏色。

如果要在每一行程式碼前面加上行號，可加上 “numbered” 或 “linenums” 屬性：

[source,c#,numbered]

此外，我們可以加入檔頭屬性 “source-language” 來指定全域（預設）的程式語言。如此一來，就不需要在每一個 [source] 區塊指定程式語言了。範例如下：

:source-language: c#

下一個範例會再複雜一點點，而且要測試中文字元。

實例演練

以下範例是修改自 Asciidoctor 的說明文件。

= 快快樂樂學 AsciiDoc
蔡煥麟 <author-email@gmail.com>
:doctype: book
:source-highlighter: rouge
:listing-caption: Listing
:icons: font
// Uncomment next line to set page size (default is etter)
//:pdf-page-size: A4
:sectnums:
:sectnumlevels: 2

A simple http://asciidoc.org[AsciiDoc] document.

== 簡介

A **paragraph** followed by a _simple_ list with #square bullets#.

[square]
* 測試**中文粗體字**
* 測試__中文斜體字__
* 測試 [underline]#文字加底線#
* 測試 [line-through]#刪除線#

IMPORTANT: `[underline]` 和 `[line-through]` 前面必須有一個空格，否則無效。

=== Hello, World!

底下是一個以 C# 撰寫的 ``Hello, World!`` 函式：

.Create a basic PDF document using Prawn
[source,c#]
----
public void Hello()   <1>
{
    Console.WriteLine("Hello, World!");   <2>
}
----
<1> 函式宣告
<2> 輸出文字

NOTE: 這只是一個簡單範例。點一下 btn:[OK] 按鈕結束。 icon:[heart]

WARNING: 版權沒有，藏私必究。

---

將上列文字存成檔案 test.adoc，然後用以下指令來產生 PDF 檔案：

asciidoctor-pdf test.adoc

產生出來的 PDF 會有章節目錄：

下圖所示為 Chapter 1 的內文：

注意有中文字的那行，「撰寫」的「寫」這個字，在產生 PDF 的時候消失了。最後一行「版權沒有」的「沒」也沒有了。

按照官方文件的解釋，在產生 PDF 檔案時，必須使用含有中文字型的主題（theme），否則某些中文字會無法正確顯示。

步驟一：安裝 CJK 主題

gem install asciidoctor-pdf-cjk-kai_gen_gothic

步驟二：下載字型

asciidoctor-pdf-cjk-kai_gen_gothic-install

步驟三：產生 PDF 時指定主題

asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=KaiGenGothicTW test.adoc

這次產生的 PDF 就沒有掉中文字的問題了：

更改字型

步驟三使用的指令當中，KaiGenGothicTW 就是主題名稱。這個主題的設定檔案位在 asciidoctor-pdf-cjk-kai_gen_gothic 套件的安裝目錄下的 data\themes\ 子目錄。在我的 Windows 環境裡，完整的路徑是： c:\Ruby24-x64\lib\ruby\gems\2.4.0\gems\asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1\data\themes\

在此路徑下，我看到四個主題的設定檔：

• KaiGenGothicCN-theme.yml 
• KaiGenGothicJP-theme.yml 
• KaiGenGothicKR-theme.yml 
• KaiGenGothicTW-theme.yml

從檔名就能看出來，它們分別是給四種語言使用的，依序是：簡體中文、日文、韓文、繁體中文（台灣）。

用文字編輯器開啟 KaiGenGothicTW-theme.yml，可以看到裡面有字型設定：

font:
  catalog:
    KaiGen Gothic TW:
      normal: KaiGenGothicTW-Regular.ttf
      bold: KaiGenGothicTW-Bold.ttf
      italic: KaiGenGothicTW-Regular-Italic.ttf
      bold_italic: KaiGenGothicTW-Bold-Italic.ttf
    Roboto Mono:
      normal: RobotoMono-Regular.ttf
      bold: RobotoMono-Bold.ttf
      italic: RobotoMono-Italic.ttf
      bold_italic: RobotoMono-BoldItalic.ttf
  fallbacks:
    - KaiGen Gothic TW

其中的幾個副檔名為 .ttf 的字型檔，是位在 asciidoctor-pdf-cjk-kai_gen_gothic 套件的安裝目錄下的 data\fonts\ 子目錄。

如果要讓 pdf 文件使用其他中文字型，只要把字型檔案複製到 data\fonts\ 目錄下，然後把 KaiGenGothicTW-theme.yml 裡面的 .ttf 字型檔案改成新加入的字型檔案名稱就行了。如下圖：

最後，再用一張圖來補充說明前面的 AsciiDoc 範例所用到的文件標頭屬性：

延伸閱讀：

• AsciiDoc 語法快速參考
• Asciidoctor PDF Theming Guide