淺談 reStructuredText 與 Sphinx

出版電子程式書籍需要面對的問題

如果你想出版電子程式書籍。你將會遇到下列問題：

1. 讀者希望出版商提供 PDF / EPUB / Mobi 三種無 DRM 版本。
2. 必須在書中黏貼大量的程式碼以及加上 highlight。
3. 必須張貼大量的示意圖片（可調整 Scale）。
4. 必須有稍微複雜的表格。
5. 除了基本的 Heading 、Ordered List，必須有 Warning / Note / Tips 以供參考。
6. 如果章節過於冗長，必須能夠用巢狀文件書寫整理。

在這情況下，Markdown 就完全不夠用了。

當然，你也可以使用 Markdown 的 extension，但是只要是 extension ，就不免落入各自為政的情況。這對即便是我這種有能力實作 Markdown 出版系統的作者來說，也會是相當困擾的狀況。（介面的即時轉換，後端輸出成果）。

所以理想的狀況是，書籍的文件格式 必須在「基本格式」要能應付一定的複雜需求 。

最後我採用了 Sphinx + reStructuredText 。

排版與成果

1. 支援 PDF 與 EPUB

PDF 為 latex template

EPUB 排程式碼也不錯看

1. 可以黏貼大量的 console log / 程式碼 以及加上高亮顯示
2. 張貼圖片
3. 複雜表格（我還沒排過故目前無沒示意圖）

1. 巢狀文件

方便整理文件。可將文章或程式碼用 include 的方式嵌入。
在排版時不易黏膩糾纏

1. Warning / Note / Tips
2. 自帶 HTML 格式

是否為一般出版者能夠使用的工具？

雖然 Sphinx 可以支援複雜的格式，滿足技術書籍出版的需求。
但相對的，它的技術需求對一般人也算高。

比如說：

1. Sphinx 是純 command 操作，所以你必須要有 Unix 操作經驗
2. Sphinx 是 python 寫成，所以如果有特殊需求或要 debug，需要一定程度的 python 能力去修改核心。
3. PDF 是使用 latex 的 template 轉成，若轉出亂碼或想要更改排版格式需要一點程度的 tex 技巧。
4. PDF hook 的 tex 轉換引擎，你必須有能力知道怎樣掛上 command line 能夠讓 Sphinx 呼叫。

而 reStructuredText 目前也沒有算好用的 WSYSG editor。重排的作業我是在 vim 上排版完成的。

結語

重排這本書花了我總共 1.5 個工作天。
比用 Pages 排版快了一點點。

Pages 也沒什麼不好，我想也是一般人堪用的工具，但程式碼與程式碼造成的浮動 box 在 epub 成品上目前會有嚴重的錯亂問題。目前無解。

這是我目前摸到現在的經驗，提供大家做參考。

如果你對出版電子技術書籍有興趣，歡迎寫信切磋討論： xuite.joke AT gmail.com ，或者是 http://twitter.com/xdite 找我也行。

我的 Google +、Facebook 專頁

本文的 rst 原始版本在此: https://www.dropbox.com/s/cc6rwkn0pukn45v/01.rst 希望對大家有幫助。

====

廣告：如果你有興趣看轉出來的全部成果，可以順道購買 書：第一次學 Rails 就上手 – 7 天之內學會 Rails（USD $9.99）

排書之餘也學學 Ruby on Rails （誤）