2014-09-09

用Markdown和Git多人協同編寫技術書籍

早年做嵌入式培訓的時候,就開始關注如何使用簡單的輕文本標記語言編寫教程和其他技術文檔,最早使用的是Docbook和Latex,但還不夠輕量級。雖然當時Markdown剛剛在github上大規模使用,但因為其不容易導出成易於出版pdf而沒有選用。後來又接觸了一些其他技術方案,最終選定了 MultiMarkdown + Latex 的方式。

從需求上看,我主要需要最終的PDF版本,如果能有 epub/mobi 更好。而且這些文檔都是中文編寫的,一個很重要的考察點就是中文支持。

一些常見的方案比較

Pandoc 和 MultiMarkdown 都非常有效的擴展了原生 Markdown 的一些語法特徵,帶來了諸如表格、代碼段高亮、圖表、尾注等等非常好的支持。特別是MultiMarkdown大大擴展了Markdown的語法,甚至可以排版非常專業的技術書籍,可以看這份語法說明。同時 Pandoc 和 MultiMarkdown 支持很多輸出格式,除了 HTML 還支持 Docbook、pdf、epub、opml、segl等等,可以放到移動端和各種設備上,可謂一次編寫,多平台共用。

  • pandoc + latex:這是目前比較常見的,優點是 Pandoc 支持的格式超多(htmldocbookpdfepubmobi…),而且也超級強大,能夠解決的問題也比較完美,著名的《Pro Git》就是使用的這個方案。若想導出 pdf 需要 Latex 的支持。Pandoc因為使用的是 Haskell 其速度很快,不需要什麼太多依賴,大多數Linux發行版都已經支持,搜索軟件包pandaoc試試就行。
  • MultiMarkdown + latex:與上面的 Pandoc 一樣,MultiMarkdown也是比較知名的一種,優點是用C語言編寫,速度超快。缺點是支持的格式少,但命令行腳本比較簡單,還是很方便的。同樣的,導出 pdf 需要 Latex 的支持。
  • gitbook:很多崇尚 Mac 的人喜歡Gitbook,簡單粗暴。優點是確實簡單,而且支持的格式也多(pdfepubmobi)缺點是在 Linux 下保存中文 pdf 有些問題,修改格式和個性化不容易。另外依賴 Node.js。
  • HTML另存為pdf:這個做法挺有意思,利用 Chrome 瀏覽器的打印成 pdf 功能,直接將 HTML 網頁轉出 Pdf。優點是簡單方便,缺點是只支持單頁 HTML,方法有點太山寨。

列個表格來比對一下,只是我目前的需求,也就是導出到中文pdf:

項目 pandoc MultiMarkdown Gitbook HTML打印Pdf
中文支持 依賴 Latex 依賴 Latex 在Linux下不行 沒問題
格式支持 pdfepubmobidocbookslider pdfopml,epub需要用其他腳本 pdfepubmobi 只有pdf
跨平台性 依賴 Haskell 全平台 依賴 Node.js 全平台
美觀及定製化 完全自由定製 非常美觀,某些Latex格式內置 定製不方便 依賴HTML源文件的CSS,效果難料
擴展Markdown 比較符合文檔要求 更符合書籍要求 符合文檔要求 依賴生成 HTML 的工具
多人協作 與 Git 結合 與 Git 結合 與 Github 結合 也可以與 Git 結合
技術難度 比較複雜 比較複雜 比較簡單 非常簡單

 

經過對比,最終我在pandoc和multimarkdown之間猶豫,最後發現了larrycaiyu的項目sdcamp,發現他用了multimarkdown,整個項目非常簡單,而結果又非常漂亮,所以決定基於他的項目做一些修改,進而完成我的目的。

配置編寫環境

為了能導出成pdf,需要Latex的支持,而為了支持中文pdf,還需要CJK包和相關字體等。

我用的是 Debian Testing(Jessie),整個配置過程還是挺順利的,可以直接執行如下命令:

sudo apt-get install texlive-xetex
sudo apt-get install texlive-xetex
sudo apt-get install texlive-latex-recommended # main packages
sudo apt-get install texlive-latex-extra # package titlesec
sudo apt-get install ttf-arphic-gbsn00lp ttf-arphic-ukai # from arphic
sudo apt-get install ttf-wqy-microhei ttf-wqy-zenhei # from WenQuanYi
sudo apt-get install texlive-fonts-recommended
sudo apt-get install latex-cjk-all

可以非常方便的把需要的包都安裝好,整個安裝過程比較長,費時也費空間,大概需要1.2GB左右才能把這些latex包全都裝好。

之後就是獲取MultiMarkdown,目前MultiMarkdown是4.0版本,完全用C重構,速度很快。但是在主流的Linux環境下都沒有為其打包,而且這個項目比較複雜,還有一些不確定的依賴,對打包來說困難不小。

至於如何安裝MultiMarkdown,就比較簡單了,過程如下:

git clone git://github.com/fletcher/multimarkdown-4.git
cd multimarkdown-4
git submodule init
git submodule update
make
sudo make install

剩下的問題就簡單了,我修改了larrycaiyu的sdcamp項目之後稍微做一些微調,便有了gnome3-app-book項目,這將會是一次多人協作來完成的寫作過程。我將原先的mmdbok腳本改成了 Makefile 這樣只要直接在命令行下執行 make 就萬事大吉了。

依然存在的問題

首先是這個方案畢竟嚴重依賴 Latex,而目前來看離開latex實現pdf的輸出還沒有太好的方案。這是一個大問題,因此本機需要大量資源消耗在Latex環境就是個較大的問題,而Latex超複雜的語法造成的高入門門檻也是個巨大的繞不開的問題。

除此之外,MultiMarkdown–4 項目本身尚不成熟,與 Pandoc 相比支持的格式偏少,再加之其很多 Latex 樣式排版是內置的,導致有時候修改起來略有不便。

特別是若我想導出 epub 格式用來放在移動設備上閱讀時,依然還要依賴 Pandoc 的工作。

蛋疼的中文字體問題

這個問題在 Larrycaiyu 的博文PDF蛋疼的中文字體一文中已經有所表述,我在他的基礎上再進行實驗,增加了Google和Adobe最近新出的 思源黑體,總結如下:

字體英文名 字體中文名 測試結果
AR PL UMing 文鼎PL細上海宋 會出現標點符號在中間的錯誤
AR PL SungtiL GB 文鼎PL簡報宋 英文字體不好看,item的”·”號不能顯示
Adobe Song Std L Adobe宋體 item的”·”號無法顯示
Hiragino Sans 字體很完美,但item的”·”不能顯示
WenQuanYi Micro Hei 文泉驛微米黑 沒有對應的粗體字體
Source Sans Han S(Noto Sans CJK) 思源黑體 不能用,出現 CMap 錯誤
FZSong FZheiti 方正宋體方正黑體 非開源字體,有潛在版權風險

使用在線持續集成環境

可以配置 drone.io 或者 Travis-CI 來引入在線持續集成環境,結合 Github 就可以直接在線生成 pdf 電子書,避免了安裝Latex的一堆麻煩事,節省了本機資源。

這裡以 drone.io 為例,可以設置語言為 C/C++,這個不影響。然後在 Commands 處寫上:

./install.latex.ubuntu.sh
./install.multimarkdown.sh
make

選擇左側的 Artifacts 然後填上 gnome3-app-book.pdf。這樣生成的 pdf 文件 URL 就類似是 https://drone.io/github.com/tonghuix/gnome3-app-book/files/gnome3-app-book.pdf

每次 push 到相應的 Github 倉庫就會自動啟動開始生成 pdf, 大概15~20分鐘後就搞定了。

多人協作的實現

可能有人會說不是有Git嗎,多人協作還是個事啊?事實上,從技術上說這真不是個事!但一旦落實到人本的問題,一旦放到具體社區環境中的時候,這個問題就略有點複雜了。

寫書和寫代碼有相似又有不同,相同的是我們都可以把寫作的過程量化和流程化,但寫文章有較強的連續性和隨意性,不像寫代碼那麼模塊化和邏輯性強。因此在多人協作的時候光靠技術來解決是不夠的,還需要一些制度性的東西,比如協作要求等等。

另外就是要分章節負責,將具有一定連續性的章節分配給同一個作者,達到結果最優。

參考資料

You may also like...

2 Responses

  1. Eric_plus says:

    Gitbook還是能滿足導出PDF/MOBI/EPUB文檔的需求,MD語言的簡潔性方便後期的文檔製作。還有我這邊希望轉載推薦這篇文章,可以嗎?