其他博客地址

主力博客:https://tonghuix.io

2014年9月9日星期二

用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 支持的格式超多(html\docbook\pdf\epub\mobi...),而且也超级强大,能够解决的问题也比较完美,著名的《Pro Git》就是使用的这个方案。若想导出 pdf 需要 Latex 的支持。Pandoc因为使用的是 Haskell 其速度很快,不需要什么太多依赖,大多数Linux发行版都已经支持,搜索软件包pandaoc试试就行。
  • MultiMarkdown + latex:与上面的 Pandoc 一样,MultiMarkdown也是比较知名的一种,优点是用C语言编写,速度超快。缺点是支持的格式少,但命令行脚本比较简单,还是很方便的。同样的,导出 pdf 需要 Latex 的支持。
  • gitbook:很多崇尚 Mac 的人喜欢Gitbook,简单粗暴。优点是确实简单,而且支持的格式也多(pdf\epub\mobi)缺点是在 Linux 下保存中文 pdf 有些问题,修改格式和个性化不容易。另外依赖 Node.js。
  • HTML另存为pdf:这个做法挺有意思,利用 Chrome 浏览器的打印成 pdf 功能,直接将 HTML 网页转出 Pdf。优点是简单方便,缺点是只支持单页 HTML,方法有点太山寨。
列个表格来比对一下,只是我目前的需求,也就是导出到中文pdf:

项目 pandoc MultiMarkdown Gitbook HTML打印Pdf
中文支持 依赖 Latex 依赖 Latex 在Linux下不行 没问题
格式支持 pdf\epub\mobi\docbook\slider pdf\opml,epub需要用其他脚本 pdf\epub\mobi 只有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简报宋 英文字体不好看,但已经很完美
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 处写上:

[code language="shell"]./install.latex.ubuntu.sh
./install.multimarkdown.sh
make
[/code]

选择左侧的 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吗,多人协作还是个事啊?事实上,从技术上说这真不是个事!但一旦落实到人本的问题,一旦放到具体社区环境中的时候,这个问题就略有点复杂了。

写书和写代码有相似又有不同,相同的是我们都可以把写作的过程量化和流程化,但写文章有较强的连续性和随意性,不像写代码那么模块化和逻辑性强。因此在多人协作的时候光靠技术来解决是不够的,还需要一些制度性的东西,比如协作要求等等。

另外就是要分章节负责,将具有一定连续性的章节分配给同一个作者,达到结果最优。

参考资料