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)。



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