{{ page.title }}

背景

随着互联网的进步和技术积累,国内技术圈交流的气氛越来越浓,微博博客上到处可见有质量的技术贴,但是有时候想系统阅读时却不是很方便,如果能够整理成册自由分享该有多好。虽然少数人有幸通过出版社出书了,但代价太大,也不能普及大众,现在技术那么发达,有没有办法自己自助出版呢?

看了图灵社区的文章为什么写作自由书籍?,作为爱书之人,我为什么不能想个办法来解决呢?

技术无极限,办法现在有好几种,在本文中,我就介绍用现在流行的Markdown格式的方式来产生专业的书籍,而且还可以做到利用互联网,不需要本地机器参与的完美方案。如果你喜欢微软的Word,觉得用它已经足够了,那我们不是同道,不用往下看了。

markdown能做出什么效果呢?

多说无益,先来看看效果吧。下面是我去年写的一本小册子:跟我学企业敏捷开发 在PDF阅读器中的效果。注意还有完整的目录和页眉。

Markdown产生的书

书的内容就全是用markdown格式写的,上图相对应的文件内容(6.2节)片断如下。

## Cucumber 简介 ##
Cucumber(英文:黄瓜)(官方网站是<http://cukes.info/>)是一个实例化需求的极佳实现伴侣。它是基于Ruby的开源测试工具,得益于Ruby便于创建和使用DSL的特性,它可以通过自然语言(文本文字)来描述需求(业务层),并通过关键字驱动和正则表达式匹配告诉去做哪些事情(驱动层),在运行自动化测试结束以后,还会给出详细的报告。

Insert 18333fig0601.png
图 6-1. Cucumber的架构

下面就是一个加法例子的需求描述,Cucumber文件以`.feature`结尾。

  # 加法 adding.feature
  Feature: Adding
    In order to avoid silly mistakes
    As a math idiot
    I want to be told the sum of two numbers

下面就是书的全部markdown文件,每一章一个文件。我把它们分成了序、前言、致谢、正文和附录,蛮像回事吧。有兴趣的朋友可以看看作译者手册,来了解标准的书是怎么组成的。

$ find zh
zh
zh/0preface
zh/0preface/00-chapter1-preface.markdown
zh/0preface/00-chapter2-changes.markdown
zh/0preface/00-chapter3-acknowledgement.markdown
zh/1chapters
zh/1chapters/01-chapter1-agile-scrum.markdown
zh/1chapters/01-chapter2-git-gerrit.markdown
zh/1chapters/01-chapter3-ci.markdown
zh/1chapters/01-chapter4-java.markdown
zh/1chapters/01-chapter5-sbe.markdown
zh/1chapters/01-chapter6-cucumber.markdown
zh/1chapters/01-chapter7-workshop.markdown
zh/2appendix
zh/2appendix/02-chapter1-sample.markdown
zh/2appendix/02-chapter2-cc2git.markdown

全书的内容够可以在github上找到https://github.com/larrycai/sdcamp/tree/master/zh

样式的产生全部有模板完成,一般不需要改动,这个稍后讲。

什么是markdown

有兴趣了,就可以聊聊markdown了,简单来说,markdown格式的文件看着像一般的文本文件,里面只是加了很少的格式标记,因此看文本文件也不影响理解,这种格式也有很多工具帮你去转化,而且很容易自动化解决。并且这些技术大多数是开源或免费的。

## Cucumber 简介 ##就可以转换成html的<h2>Cucumber 简介</h2>或者书中的小节, 空四个就是表示代码,是否很简单。具体可以看图灵社区的文章 Markdown语法说明(详解版)

为什么要用markdown

原因也很简单,因为简洁和流行。markdown格式的普及要归功于Github和StackOverflow。因为它们越来越流行,它们支持markdown格式也越来越流行。这里要赞一个的是,国内的图灵社区也支持markdown,用起来超级方便。

我的体会是,它让你关注内容,格式怎么显示不是要你在写得时候关注的。Word让我讨厌的原因就是老要关注格式。

实际上核心是软件思想中的分离,就像HTML关注内容,CSS关注格式表现一样。

背后的魔法

从Markdown源文件产生电子书一般有两种方案:一种是产生HTML中间格式再转换出电子书,另一种是对应地转换产生出LaTeX文件格式,再和LaTeX模板合在一起,最后转换产生PDF,达到标准书籍出版的质量(完整的封面,目录,页眉等等),这里主要讨论第二种。

Markdown产生的书技术方案

LaTeX(就是Donald E. Knuth(高德纳)发明的)是一个出版界(至少是科技界)常用的格式,PDF也能很容易地产生出来,它的好处是内容和形式是很容易分开的,感谢大师的设计。

Markdown可以通过工具自动转换出LaTeX的标准内容。

\section{Cucumber 简介} % 

就是上面由## Cucumber 简介 ##自动生成的LaTeX内容,表示小节。

余下书的表现形式就有预先调好的LaTeX的模板来处理,像页眉、目录、字体之类的和内容无关的就全部有LaTeX搞定了。不同的出版社或者图书系列都会有特定的模板,这和作者的内容无关。

这有点像HTML和CSS的关系。下面这一段是调整小节标题显示:

\definecolor{colorsection}{RGB}{95,158,160}    % CadetBlue
\setromanfont[Mapping=tex-text,BoldFont="WenQuanYi Micro Hei"]
\titleformat{\section}
    {\color{colorsection}\normalfont\Large\bfseries}
    {\color{colorsection}\thesection}{1em}{}

\bfseries 是让 LaTeX 使用粗体字排版,这儿选择了文泉驿的微黑。

下面这一段是调出页眉左上角(LE=Left Head)的:显示页码和内容,颜色设定为钢铁蓝,

\definecolor{colorheader}{RGB}{70,130,180} % SteelBlue
\fancyhead[LE]{\color{colorheader}\quad\small\textbf\thepage\quad\quad\small\leftmark} %页眉左上角

初看有点复杂,学习曲线蛮陡的。不懂的话,知道里面含有样式就可以了,反正你可以用现成的模板,这也是出版的专业所在,不用写书的负责。

工具软件pandoc能帮着从markdown转换出LaTeX格式,然后通过TexLive软件中的xelatex再转成PDF格式。

强烈建议你到Pandoc的在线实验环境试一下。

这里主要讨论PDF的格式,实际上epub/mobi格式的用pandoc生成也很方便。

其他常用格式的出版方案

计算机类图书对格式要求不是很多,图文、章节、源代码基本就够了,就算有些复杂公式,也可用图来显示。这也从理论上说明,它不需要复杂的格式。现在对这类技术书出版我的理解主要有几种:

  1. Microsoft的Word格式,虽然国内出版界如日中天,缺省就认它(对技术没追求,鄙视)。简单好学,但是不擅长自动化,是开源的死敌。
  2. 直接用LaTeX格式,这是很棒的东西,特别适合学术类的各种复杂的公式等,不过学习曲线很高,国内也只有几家学术期刊使用。
  3. DocBook格式是最有名的(从SGML演化过来),O'Reilly和Pragmatic出版社缺省就用它,它能很方便地转化出出版要的各种样式。如Jenkins - the definition guide开源书就是采用docbook。但由于是XML格式,很多人不习惯,而且多人网上协作不是很方便。
  4. 通过蒋鑫的Got Github开源书,我也了解reStructureText也是和markdown差不多纯文本(plain text)的,也是蛮流行的,结合sphinx也所向无敌。

自己动手产生电子书

讲了那么多,作为码农,该动手实践一下,其他读者可以跳过这一章。

你需要一台Linux机器(虚拟机就可以了)和简单的Linux命令就可以试验了。有git和ruby的知识那就更方便了。

我用的试验环境是Ubuntu 12.04 (Precise) 版本。

下载书的源代码

很简单,git clone一下就可以了,下载它的源文件包我觉得还是烦了点。

$ git clone https://github.com/larrycai/sdcamp.git

生成PDF是一个比较复杂的东西,用到了pandocTexLive软件,用Ubuntu库里就可以了。关于Pandoc,可以看图灵社区翻译的文章关于通用文档转换器Pandoc,TexLive就是LaTeX的工具集。

$ sudo apt-get install pandoc 
$ sudo apt-get install texlive-xetex texlive-latex-recommended texlive-latex-extra # 安装texlive 2011

因为是中文PDF,需要把字体嵌入在文件中,因此需要安装字体文件(如果不是Ubuntu中文版),具体可看我在图灵社区的文章开源书和开源技术-PDF中蛋疼的中文字体

$ sudo apt-get install ttf-arphic-gbsn00lp ttf-arphic-ukai ttf-wqy-microhei ttf-wqy-zenhei

现在你就可以生成pdf文件了。

$ ./mkbok    

mkbok 脚本

pandoc本身也支持模板,但很多情况下,还需要调整,写个脚本就方便多了。我用的脚本mkbok是基于Pro Git里面的脚本makeebooksmakepdfs开发的。原书作者Scott原来还用calibre产生epub文件,我统一用pandoc。并原有的基础上进行了扩展,统一为mkbok脚本。

$ ./mkbok --build pdf,html,epub --lang zh --template latex/template.tex

这样就可一次性完成电子书的活,而且还改造了LaTeX模板(加了前言、致谢和页眉等,使它最后的结果更像一份标准的书。主要功能差不多,但是扩展应该会更好些,特别是有机会更方便地采用不同的专业模板。

基于Github和Travis-ci的互联网在线方案

你可以建一套基于上述技术的方便的出版系统。不过也可以利用互联网的服务,混搭一下。Github和Travis-ci就是我要利用的混搭服务。

Github和Travis CI这里就不介绍怎么使用了,具体可以先看晓斌的博客和蒋鑫的Got Github,强烈建议你先试一下。要不下期码农吧。

简单道理就是当你把代码推送到Github时,就可以触发Travis-ci的构建。Travis-ci会启动一个基于Virtualbox的Ubuntu的虚拟机(当前是12.04版本),然后根据你的.travis-ci.yml中的配置来构建你的产品,也就是执行上面的步骤来产生PDF文件。

构建结束后,虚拟机会被删除掉,虽然Travis-ci网站本身没有提供归档功能,但是Github的API提供了极好的方法来上传文件。所以我们可以用Github API和Travis-ci的保密环境变量的方式来把Travis-ci的结果上传回Github。

具体请看我的博客把Travis-ci的结果上传回Github

李明老师的源码开放学ARM也是此方案的忠实用户,基本上可以全用浏览器解决。

结尾

里面的技术细节还有蛮多的,不知是否你都明白,实际上照着试一遍,你会发现不是那么复杂。如果有问题,尽管找我 (@larrycaiyu)。

我一直设想中有一天上面提到的各个环节都能打磨得非常流畅,吸引更多的使用者。然后能够有很多人有兴趣用它来写书,可能是自娱自乐,也可以免费出版。不管怎样都是促进图书业。

出版界或者LaTeX的高手可以提供设计些更好的LaTeX模板(可以收费)供大家使用。

图灵出版社也提供网上的编辑服务(当然是可以收费的),对一些想把书写得专业点的作者提供额外的帮助,这样或许是一个很好的增值服务。至少像我这样的文笔超烂的技术人员很想得到的。

这些本是我2012想做到的事情:设想中的开源书项目,而且域名都买好了,留个遗憾放到明年吧。

技术无极限,只怕没追求。

评论

推荐 0
https://github.com/larrycai/sdcamp/tree/master/zh 链接似应为 https://github.com/larrycai/sdcamp/tree/master

推荐 0
现在好多博客都提供MARKDOWN语法 ,像
github.com,jianshu.io,xiaoshujiang.com
而且有些还提供版本管理,这才是最重要的

推荐 0
很受益,谢谢。
又:“并原有的基础上进行了扩展”似为“并在原有的基础上进行了扩展”误。

推荐 0
CPyUG 社区基于 Sphix 进行的开放图书工程,也已经有5年了,,,openbookproject - O.B.P~Open Book Proj.中文蟒样开放图书计划! - Google Project Hosting
http://code.google.com/p/openbookproject/
挺羡慕的,sphix确实是好东西,相当完整。只是rst用的人太少。 –  larrycai 2012-12-19 08:44
亲!你是知道 https://readthedocs.org/ 的吧,已经有无数开源作品文档是发布在这儿的? code.google/github/bitbucaket 等等主流开源项目 hosting 都支持 RTFD 服务了! 能说用的人少嘛? 而且 rST 比 md 出生早太久,工具链更加丰富,,,,不过,看个人爱好了,,,而且有通用转换服务了,,,用什么不是重点 ,重点是誰来用,,, –  Zoom.Quiet 2012-12-20 10:19

推荐 0
thx

推荐 0
>docbook格式是最有名的(从SGML演化过来?),Orielly和Pragmatic出版社缺省就用它,它能 很方便的转化出出版要的各种样式。如Jenkins - the definition guide开源书就是采用docbook。但由于是XML格式,很多人不习惯,而且多人网上协作不是很方便。

DOCBOOK 只是一套规范格式,它可以用 SGML,XML 来写,XML的语法定义格式有DTD,XML Schema,Relax NG。我喜欢最常用的方式,使用 DTD 定义,XML来写,使用 XLST 和一些工具来输出其它格式。

从出版的角度,DOCBOOK 几乎是其它工具无法超越的。

不管是markdown, 还是textile 最初都是为输出 HTML为准备,正如 markdown 网站所说的那样,markdown 是 writing format, HTML 是它的最终 publishing format ,而且 markdown 相对较弱,主要针对以文为主文章,在文本表示方面远不如 DOCBOOK。DocBook 从一开始就考虑了多种格式的输出。而 markdown 只是定义们简化 HTML 编写过程,这样带来的问题,没有原生的输出其他格式,特别是 PDF,现在的方案都是通过中间格式转换。

SUN 和 Oreilly是 DOCBOOK 最初的推动力。目前 DOCBOOK 广泛用于开源社区文档组织,如大家熟悉的 Hibernate,Spring,JBoss 及 Redhat 其他商业产品(不过现在 JBoss 有部分移植到 Confluence Wiki上)的文档几乎都是用 Docbook。

非常可惜的, DOCBOOK 入门容易,但要自定义输出样式,需要对 DOCBOOK 规范和转换过程相当熟悉,这对国内的出版来说,似乎是难题,目前没有一家有自己的一套输出样式(我想 Oreilly和 Programtic 都有自己修改的一套样式,写完了DocBOOK 文件后,只要使用它们的样式输出来就是漂亮的文档了。)。

同意。补充一点,基于markdown出书的话,考虑采用latex作为中间过程,这样就两者兼得:方便协作,又能达到书籍的质量。 –  larrycai 2012-01-29 17:08
你试过docbook么?至少我在2008年前后的尝试给我的感觉是,用docbook格式写书,中文支持很成问题。 –  acid-free 2012-05-15 13:05
试过一点,要好的编辑器,而且还要考虑XML,有点烦。 –  larrycai 2012-05-15 13:54

推荐 0
当初选择使用Markdown而不是HTML,还是很有压力的。但是确实Markdown太好用了,所以值得冒风险。相信越来越多的人会喜欢上Markdown。

推荐 0
对出版技术也提出了要求。

推荐 0
我现在的习惯做法是课堂笔记用LaTeX(因为经常涉及一些公式什么的), 其他格式比较简单的或者需要显示在网页上的就用reStructuredText写.

推荐 0
祝蔡老师新年快乐,新年新气象!

打算明年研究一下Pandoc,感觉很好玩 :D

我要评论

需要登录后才能发言
登录未成功,请修改提交。