轻松记录您
灵感和创意

Markdown来写自由书籍

{{ page.title }}

背景

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

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

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

Markdown能做出什么效果呢?

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

Markdown产生的书

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

## Cucumber 简介 ##

Cucumber(英文:黄瓜)(官方网站是)是一个实例化需求的极佳实现伴侣。它是基于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的

Cucumber 简介

 

 

或者书中的小节, 空四个就是表示代码,是否很简单。具体可以看图灵社区的文章 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生成也很方便。

其他常用格式的出版方案

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

Microsoft的Word格式,虽然国内出版界如日中天,缺省就认它(对技术没追求,鄙视)。简单好学,但是不擅长自动化,是开源的死敌。

直接用LaTeX格式,这是很棒的东西,特别适合学术类的各种复杂的公式等,不过学习曲线很高,国内也只有几家学术期刊使用。

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

通过蒋鑫的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是一个比较复杂的东西,用到了pandoc和TexLive软件,用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里面的脚本makeebooks和makepdfs开发的。原书作者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。

未经允许不得转载:坚果之云 Markdown » Markdown来写自由书籍
分享到: 更多 (0)

坚果云Markdown轻松记录您 灵感和创意

坚果云Markdown下载坚果云Markdown介绍