buildebooks
Build ebooks using Pandoc and Kindlegen
Last updated 4 years ago by wastemobile .
ISC · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install buildebooks -g
SYNC missed versions from official npm registry.

Build Ebooks

Mac 上需要預先準備好必要程式,參考 預裝程序。打開終端機在任何目錄輸入下列三條指令,都必須運作正常、顯示目前版本,否則製書程式無法執行成功。

  $ npm -v //檢視 NPM 版本(2.8.4)。
  $ pandoc -v //檢視 Pandoc 版本(1.13.2)。
  $ kindlegen -releasenotes //檢視 Kindlegen 版本(V2.9)。

持續不穩定建置中。

  $ npm install -g buildebooks
  $ buildebooks -v //檢視目前版本
  $ npm update -g //更新

0.2.x

安裝

  1. npm install -g buildebooks 安裝於全域環境以便執行終端機指令模式。(如果遵照 預裝程序 的安裝方式,就不需要 sudo;萬一 Node.js 的安裝方式不同,可以嘗試使用 sudo npm install -g buildebooks 安裝。)
  2. 打開終端機,不管在單書目錄、多書目錄,或使用總專案管理目錄,都只需要輸入 buildebooks 命令就能自動判斷、製作電子書。
  3. 未安裝在全域執行環境就無法使用終端機指令,你需要自行建立 Node 指令檔,例如:
var build = require('buildebooks').bes;
build();
  1. 製書時輸入 node index.js 即可運作。

安裝於全域(with -g)之後,任意目錄執行 buildebookbuildebooks 均可。輸入 buildebook(s) -v--version 會顯示目前版本。由於仍處於不穩定開發階段,常常運行 npm update -g 獲得最近的更新版本。

運作於單書目錄

(1) Single Book Folder
/yourfolder
  /book.md //製書索引,沒有這個檔案就不會製作電子書
  /metadata.md //詮釋資料
  /intro.md
  /ch1.md
  /ch2.md
  /ch3.md
  /Cover.png
  /epub.css
  /style/default.css
  /image/cover.jpg
  /part2/another.md

你可以自由使用次目錄擺放內容、素材,只要在製書索引中添加正確的路徑,例如 images/cover.jpg, style/stylesheet.csspart1/mycontent.md, part2/another.md 均可。

---
# 唯一必要的設定
files:
  - intro.md
  - ch1.md
  - ch2.md
  - ch3.md
# 自訂電子書檔名稱,未設定會使用上層目錄名稱(此例就是 `yourfolder`)
# filename: "mybook"
# 關閉製作。未設定時的預設值是 true
# build: false
# 同步製作 Kindle 電子書,預設值是 false
# kindle: true
# 編輯版本號
# edit_version: "0.2"
# 是否複製成正式發行版本,預設是 false
# public: false
# 發行版本號
# release_verson: "1.0"
# 試讀版本(public 設為 true 時才會製作)
sample:
  - intro.md
  - ch1.md
---

基本設定(config.md

0.2.x 之後,非單書目錄才會用到 config.md

使用 config.md 設定:擺放書籍專案的目錄(base)、擺放電子書的目錄(dest)、書籍索引檔的名稱(index)以及預設讀取書籍資料的檔案名稱(metafile)。可以沒有這個檔案,系統就會依照預設值尋找。

---
# 擺放所有書籍專案的目錄(使用集中目錄的情境)
base: 'projects'
# 預設擺放製成書檔的目錄
dest: 'books'
# 製書索引檔的名稱
index: 'book.md'
# 預設尋找的詮釋資料檔名稱
metafile: 'metadata.md'
# 共用樣式檔目錄
stylesFolder: 'styles'
---
  • 你所有的書籍專案都在 projects 目錄下,一個專案一個子目錄,名稱不能重複。
  • 書籍專案內使用一個 book.md 作為製書指引(索引)檔。
  • 書籍(詮釋)資料檔是必要的。

除了上面提到的「單書目錄」之外,以下兩種目錄也都可以自由使用:

(2) Multi-Books folder
/somefolder
  /book1
  /book2
  /book3
  /styles (可以使用共用樣式目錄)
  config.md (可以使用設定檔,`base` 設定在此狀況下無效)

使用終端機在該目錄下執行 [ ~/somefolder] $ buildebooks 即可。

(3) Center Projects folder
/minifactory
  /projects
    /book1
    /book2
    /book3
  /styles (共用樣式目錄)
  config.md (可以使用設定檔)

使用終端機在該目錄下執行 [ ~/minifactory] $ buildebooks 即可。

安裝在全域的好處就是:你的書籍專案目錄不再有什麼 index.js 或是 node_modules 目錄之類的玩意,完全只有與內容相關的檔案,清爽許多。

製書索引檔(book.md 或自訂名稱)

某些製書程序要求使用固定的檔名與順序(例如 01-xxx, 02-xxx...),不太人性且增加了麻煩。Leanpub 與 GitBook 使用的模式好一些:透過一個索引檔案,告訴系統要使用哪些內容檔案製作電子書。

使用製書索引檔還有其他好處:

  1. 書籍專案目錄下,可以自由擺放各種檔案,草稿、參考文件、編輯註記等等,無需受限任何規則。
  2. 只有那些寫進索引檔的內容文件,才會影響電子書的製作。
  3. 索引檔還可以處理一本書製作時的獨立配置,像是一些開關,要不要暫時關閉製書程序、要不要同步生成 Kindle 電子書、設定編輯版本等等。

製書索引檔至少需要指定內容檔案(files),依序構成書籍的內容(目錄)。

還可以配置下面這些開關:

  • filename 未設定時,書籍專案目錄名稱就是書檔名稱。
  • metafile 書籍詮釋資料檔是必要的,預設會尋找 metadata.md,你可以自由指定。
  • build 設置為 truefalse,未設定的預設值為 true,也就是在執行程序時會自動製作電子書,當你還在書寫或編輯流程,或是已經發行一個正式版本,暫時不需要每次都製作、覆蓋電子書檔時,可以選擇將其關閉。
  • kindle 設置為 true/false,預設為 false。開啟這個開關會在製書時同步產生 Kindle 版本(使用 Kindlegen 轉製)。
  • edit_version 編輯版本設定。
  • stylesheet 使用的樣式檔,在此處設置的優先權比詮釋資料檔更高,在編輯、修正測試與改版的情境下比較方便。指定樣式檔時,專案目錄找不到,會去比對共用樣式目錄。
  • cover-image 指定封面圖檔,在此處設置的優先權比詮釋資料檔更高,便利編輯與改版過程的使用。
  • publish 設置為 true/false,是否產生正式發行書檔。(not yet)
  • publish_version 設置發行版本號。(not yet)

編輯版本設置

當你持續書寫與編輯,並執行製書程序時���filename.epubprojectname.epub 會被擺在專案目錄下的 books 目錄,每次製書都會覆蓋掉舊檔。在測試與發想階段你可以這樣用,但隨著內容愈來愈多,或是已經有對外提供過書檔,你會希望能更清楚的管理流程,這時就需要設置「編輯版本號」。

試著將編輯版本號設置為 "0.1",這時製成的書檔會變成 filename-0.1.epub。當版本號未異動,任何修改與重複製書都會覆蓋掉舊檔。一旦你將版本號升級成 "0.2" 時,一個新的 filename-0.2.epub 被製作出來,"0.1" 版的書檔依舊保留著。

使用概念很簡單,當書寫與編輯告一段落,特別是有將書檔交給其他人檢視,或是已經發行出去時,你應該保留這一版的書檔供參考比對,此時就只需要將「編輯版本號」往前推進一版即可。

樣式檔使用 0.1.7

使用樣式檔(stylesheet)時,最簡單的方法就是擺放在書籍專案目錄,指定目錄下的 epub.css 或次目錄中的 stylesheet/epub.css。因為詮釋資料是跟著書走的,理論上應該在其中設定要使用的樣式檔,這也是 Pandoc 的預設處理模式。

但你可以在製書索引檔中指定樣式檔,同樣是以一個專案的目錄為基準去優先比對檔案,找到了就使用,測試調整時比較方便。

因為這個系統一開始就以能「同時處理多本書」為出發點,共用樣式檔的可能性很高,所以在基本設定中加了一個 stylesFolder (共用樣式目錄)的選項,預設是 styles,可以擺放多個常用、通用的樣式。

如此一來,假設你預先製作好了 default.cssfiction.csstech.css 幾種樣式,就可以在詮釋資料或製書索引中直接指定。若是書籍專案目錄下有同名的樣式檔,會優先被使用。

比對優先順序為:

  1. 索引檔中指定了樣式,先找專案目錄,其次是共用樣式目錄,先找到先用。
  2. 索引檔中未指定或找不到,詮釋資料有指定,一樣先找專案目錄,其次是共用樣式目錄,先找到先用。
  3. 索引檔或詮釋資料檔中均未指定,或在專案目錄與共用樣式目錄都找不到,套用的就是 Pandoc 預設、最精簡的樣式。

唯一識別碼 0.1.9

Pandoc 可以接受這些唯一識別碼:ISBN-10, GTIN-13, UPC, ISMN-10, DOI, LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC, ISMN-13, ISBN-A, JP, OLCC,這些也是 EPUB 允許的代碼。

在詮釋資料中以這樣的形式輸入:

identifier:
- scheme: ISBN-13
  text: 978-986-276-419-0

如果沒有設定任何一個,Pandoc 預設會自動產生一個隨機生成的 UUID,每一次製作時都不一樣。對於自主出版或新型態的數位出版來說,沒有必要去申請傳統的 ISBN,所以要想辦法讓每一個書籍專案擁有一個不變的唯一識別 UUID,不管轉製多少次,這個識別碼都該維持不變。

所以當第一次轉製電子書時,在書籍專案目錄下會建立一個 uuid.xml 的檔案,另外在根目錄的 books.json 中也有一份0.2.0 之後已不再使用)。這個檔案由程式管控,不應該碰觸。萬一 uuid.xml 被殺掉了,下次製書時會自動產生,UUID 依舊維持不變。但若是殺掉了 books.json,就請也一併手動移除 uuid.xml,否則 UUID 就會不一致了。 書籍目錄下的 uuid.xml 若被人工移除,下次製書時會重新產生,但 UUID 不同,請小心。

目前這個維持「唯一識別 UUID」的機制還不是很牢靠,在專案目錄名稱不變的狀況下,一般不會出錯。未來或許該添加一些清理、檢測或搬移的功能。

試讀版本 0.1.12

在製書索引中增加了一個 sample 的設定,方法與 files 相同。這是準備與發行功能搭配的選項,因此 publish 也必須設置為 true

簡單的說,就是製作一個「試讀版本」,可以自由指定要擺放的內容章節。檔名後以 -sample 區隔,命名原則與正式版(含版本號)一致,同時適用於 EPUB 與 Kindle 版本的製作(因此若指定 publish: true 且設置了 sample 要使用的內容,一次就會產生四個書檔。

檢查可用程式 0.2.1

加入檢查系統是否已安裝 Pandoc 與 Kindlegen。

找不到 Pandoc 會提示並跳出;找不到 Kindlegen 則顯示警告訊息。

Current Tags

  • 0.2.1                                ...           latest (4 years ago)

13 Versions

  • 0.2.1                                ...           4 years ago
  • 0.2.0                                ...           4 years ago
  • 0.1.12                                ...           4 years ago
  • 0.1.11                                ...           4 years ago
  • 0.1.10                                ...           4 years ago
  • 0.1.9                                ...           4 years ago
  • 0.1.8                                ...           4 years ago
  • 0.1.7                                ...           4 years ago
  • 0.1.6                                ...           4 years ago
  • 0.1.5                                ...           4 years ago
  • 0.1.4                                ...           4 years ago
  • 0.1.3                                ...           4 years ago
  • 0.1.2                                ...           4 years ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (10)
Dev Dependencies (0)
None
Dependents (1)

Copyright 2014 - 2016 © taobao.org |