Asciidoctor-epub3 入門筆記

這是 Asciidoctor 入門筆記系列的第三篇。上次寫的是 asciidoctor-pdf 與中文套件相關問題，這次則是 asciidoctor-epub3。

寫這篇筆記時，使用的 asciidoctor-epub3 版本是 v1.5.0 Alpha 7。從版本號碼看得出來，這個套件還有一些未盡完善之處。例如：

• 章節標題沒有編號（都三年了，還沒解決 Orz）
• 無法自訂字型： v1.5.0 Alpha 7 允許指定自訂的 epub3.css 和 epub3-css3-only.css 來取代預設的 css 檔案，可是卻無法使用自訂的 epub3-fonts.css。 （這問題也放了兩年多還沒解決）

上述缺點有可能在 v1.5.0 Alpha 8 解決。

安裝

gem install asciidoctor-epub3 --pre

安裝相依套件：

先將現行目錄切換至 asciidoctor-epub3 的安裝目錄，例如：

cd c:\Ruby23-x64\lib\ruby\gems\2.3.0\gems\asciidoctor-epub3-1.5.0.alpha.7\

然後在此目錄下執行 bundler：

bundle

Bundler 便會根據現行目錄下的 Gemfile 檔案來安裝相依套件。在我的環境上執行時，出現錯誤：

C:\Ruby23-x64\lib\ruby\gems\2.3.0\gems\asciidoctor-epub3-1.5.0.alpha.7>bundle

Fetching gem metadata from https://rubygems.org/..........

Resolving dependencies...

Fetching rake 12.3.0

Installing rake 12.3.0

Using asciidoctor 1.5.6.1

Using mini_portile2 2.1.0

Using nokogiri 1.6.8.1 (x64-mingw32)

Using rubyzip 1.2.1

Using gepub 0.6.9.2

Using thread_safe 0.3.6

Using asciidoctor-epub3 1.5.0.alpha.7 from source at `.`

Using bundler 1.16.1

Fetching epubcheck 3.0.1

Installing epubcheck 3.0.1

Fetching kindlegen 3.0.3

Installing kindlegen 3.0.3 with native extensions

Using multi_json 1.12.2

Fetching pygments.rb 1.1.1

Installing pygments.rb 1.1.1

Errno::EACCES: Permission denied @ rb_file_s_symlink -

(vendor/pygments-main/scripts/debug_lexer.py,

C:/Ruby23-x64/lib/ruby/gems/2.3.0/gems/pygments.rb-1.1.1/vendor/pygments-main/scripts/find_error.py)

An error occurred while installing pygments.rb (1.1.1), and Bundler cannot

continue.

Make sure that `gem install pygments.rb -v '1.1.1'` succeeds before bundling.

嘗試以系統管理員的身分來開啟命令視窗，再執行一次就成功了。執行結果如下：

C:\Ruby23-x64\lib\ruby\gems\2.3.0\gems\asciidoctor-epub3-1.5.0.alpha.7>bundle

Fetching gem metadata from https://rubygems.org/.........

Resolving dependencies...

Using rake 12.3.0

Using asciidoctor 1.5.6.1

Using mini_portile2 2.1.0

Using nokogiri 1.6.8.1 (x64-mingw32)

Using rubyzip 1.2.1

Using gepub 0.6.9.2

Using thread_safe 0.3.6

Using asciidoctor-epub3 1.5.0.alpha.7 from source at `.`

Using bundler 1.16.1

Using epubcheck 3.0.1

Using kindlegen 3.0.3

Using multi_json 1.12.2

Using pygments.rb 1.1.1

Bundle complete! 5 Gemfile dependencies, 13 gems now installed.

Use `bundle info [gemname]` to see where a bundled gem is installed.

排版風格

EPUB 和 KF8/MOBI 檔案都是用 CSS3 來控制排版風格。預設的 CSS 檔案放在 asciidoctor-epub3 套件的安裝目錄下的 data/styles 子目錄裡面。例如，在我的 Windows 環境下，這個目錄的完整路徑是：

c:\Ruby23-x64\lib\ruby\gems\2.3.0\gems\asciidoctor-epub3-1.5.0.alpha.7\data\styles

此目錄之下有下列檔案：

• epub3-fonts.css 
• epub3-css3-only.css 
• epub3.css 
• color-palette.css 

Asciidoctor EPUB3 僅提供一種版型，但我們可以透過 epub3-stylesdir 屬性來指定 epub3.css 和 epub3-css3-only.css 的所在目錄，如以下範例所示：

asciidoctor-epub3 manuscript/book.adoc -a epub3-stylesdir=../themes-epub3 -o output/mybook.epub


注意其中的 epub3-stylesdir 屬性值是「../themes-epub3」，這是因為該目錄所在位置應相對於原稿所在位置，而原稿位於 manuscript，跟 themes-epub3 是同一層級的目錄，故在指定 epub3-stylesdir 時須加上「..」，否則會發生找不到資料夾的情形。

字型

預設的字型檔案是放在 asciidoctor-epub3 套件的安裝目錄下的 data/fonts 子目錄裡面，裡面有一個 epub3-fonts.css。我原以為可以透過修改 epub3-fonts.css 的方式來修改預設字體，但結果發現沒有作用。

我試過的方法，是將 asciidoctor-epub3 預設的 CSS 檔案全都複製到自己的資料夾底下，然後修改 epub3-fonts.css，加入以下字型設定：

@font-face {
  font-family: "懷源黑體 TW";
  font-style: normal;
  font-weight: normal;
  src: url(../fonts/KaiGenGothicTW-Regular.ttf);
}

@font-face {
  font-family: "懷源黑體 TW";
  font-style: italic;
  font-weight: normal;
  src: url(../fonts/KaiGenGothicTW-Regular-Italic.ttf);
}

@font-face {
  font-family: "懷源黑體 TW";
  font-style: normal;
  font-weight: bold;
  src: url(../fonts/KaiGenGothicTW-Bold.ttf);
}

@font-face {
  font-family: "懷源黑體 TW";
  font-style: italic;
  font-weight: bold;
  src: url(../fonts/KaiGenGothicTW-Bold-Italic.ttf);
}

然後，在 epub3.css 檔案裡面使用「懷源黑體 TW」，例如：

body p,
ul, ol, li, dl, dt, dd, footer,
div.verse .attribution, table.table th, table.table td,
figcaption, caption {
  color: #333332;
  font-family: serif, "懷源黑體 TW", "微軟正黑體";
}

可是，由於 asciidoctor-epub3 目前的版本並不支援自訂的 epub3-fonts.css，所以實際測試之後，發現上述方法是沒有作用的。

我想，也許可以透過手動的方式解決：把產生好的 epub 檔案解壓縮，修改裡面的內容，再手動打包成 epub。就算可行，這個方法還是麻煩了點。

字型圖示（Font Icons）

Asciidoctor-epub3 似乎無法正常處理 font-based icons。我不確問題出在哪裡，於是到 github 發問：https://github.com/asciidoctor/asciidoctor-epub3/issues/155

手動解決的步驟：

1. 把 epub 檔案解壓縮。
2. 用文字編輯器開啟每一個 html 檔案，搜尋所有的「::before { content: ""; }」，並將其 content 屬性值設定成對應的字元碼。例如：
   .i-commenting::before { content: ""; }
   應改成：
   .i-commenting::before { content: "\f27a"; }
   
   各圖示對應的字元碼可在 Font Awesome 的 CSS 檔案中找到：
   https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.css
3. 把修改後的 html 檔案加回原本的 epub 檔案。例如，把 epub 檔案的副檔名先改成 .zip，然後把修改過的 html 加入壓縮檔，以取代壓縮檔案裡面的現有 html 檔案。
   注意：不要直接用壓縮工具把解開後的檔案重新壓縮起來，再將副檔名改為 .epub——這會產生無效的 epub 檔案。

怎麼知道 epub 檔案的格式正確？

比較簡便的方法是，把 epub 檔案上傳至 Google 圖書。如果上傳之後，在 Google 圖書網站上無法打開那本書，就表示 epub 內容有問題。但究竟是哪裡有問題，就還是得靠其他工具，例如 calibre。

若要使用 Calibre 來檢查 epub 格式：在書籍上面點右鍵，編輯書籍。然後執行 Check book 功能（快捷鍵是 F7）。