上一篇文章提到,asciidoctor-pdf 必須搭配 CJK 套件,否則在處理文字斷行的時候會有問題。在這篇筆記裡,我會進一步說明如何安裝 CJK 套件,以及如何指定欲使用的中文字型。
先看一個很簡單的範例,如下圖:
左邊是 AsciiDoc 文件,右邊是利用 asciidoctor-pdf 轉換成 PDF 檔案的結果。這個簡單的範例展示了:
順便提一下,[source,c#] 裡面的 “c#” 必須是小寫字母 “c”。有一次我沒注意用了大寫,結果產生出來的文件沒有語法顏色。
如果要在每一行程式碼前面加上行號,可加上 “numbered” 或 “linenums” 屬性:
[source,c#,numbered]
此外,我們可以加入檔頭屬性 “source-language” 來指定全域(預設)的程式語言。如此一來,就不需要在每一個
:source-language: c#
下一個範例會再複雜一點點,而且要測試中文字元。
以下範例是修改自 Asciidoctor 的說明文件。
將上列文字存成檔案 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\
在此路徑下,我看到四個主題的設定檔:
從檔名就能看出來,它們分別是給四種語言使用的,依序是:簡體中文、日文、韓文、繁體中文(台灣)。
用文字編輯器開啟 KaiGenGothicTW-theme.yml,可以看到裡面有字型設定:
其中的幾個副檔名為 .ttf 的字型檔,是位在 asciidoctor-pdf-cjk-kai_gen_gothic 套件的安裝目錄下的 data\fonts\ 子目錄。
如果要讓 pdf 文件使用其他中文字型,只要把字型檔案複製到 data\fonts\ 目錄下,然後把 KaiGenGothicTW-theme.yml 裡面的 .ttf 字型檔案改成新加入的字型檔案名稱就行了。如下圖:
安裝
-
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 。指令:
-
文字圖形套件: asciidoctor-diagram (選用)
gem install asciidoctor-diagram
gem install rouge
gem install coderay
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 字型檔案改成新加入的字型檔案名稱就行了。如下圖:
沒有留言: