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 範例所用到的文件標頭屬性:


延伸閱讀:

買書 打賞
Copyright © 2012. Huan-Lin 學習筆記 - All Rights Reserved
Powered by Blogger
Template Design by Cool Blogger Tutorials
Published by Templates Doctor