DocBook 让文档版本化

#ThoughtWorkers好声音# 第十六期(图片:网络)

你们都知道ThoughtWorks曾经是扛敏捷的大旗的,你们也都知道敏捷是反文档的,不过那都是误解啦。虽然作为一个程序员最讨厌的事情有两件:1,写文档,2,别人没写文档。但是文档这个东西,该有还是要有的。我们反对的是写文档的过程带来一些让人灰头土脸问题。 比如版本化,版本之间查找对比不方便之类。所以我们自己写文档的时候,就要避免这种问题。为了体面的写文档,我们来看看杨锐同学的高招《DocBook 让文档版本化》。


由于项目中客户的一些原因,我们不能直接接触产品环境的服务器。导致我们每次部署产品代码前,需要给客户的IT团队准备一份部署文档,然后他们遵循这份文档来部署产品。

最开始的时候,我们是用word来写这份文档的。方便是方便,但是当时间长了以后,文件数越来越多,每次写这个文档也不是固定的人,有时候需要复查一下很久前写的东西,就不那么方便了。所以很期望能把这个部署文档也纳入版本控制当中,这样就可以像代码一样,不管是谁写完文档,check in到repository里,以后想要查找、对比都方便很多。

但是word文档本身并不能直接纳入到版本控制中,需要check in的是纯文本。我们还想提供给客户的文档有一定的格式,所以直接发送纯文本的方式也被否定了。

这个时候就是我们的主角Docbook登场的时候了!Docbook可以把符合自己格式的XML文件转变成pdf,我们可以把pdf作为发送给客户的最终文档。下面就让我们看看,如何使用Docbook来实现文档的版本化吧!

我们这里以Windows环境为例。

依据链接1的步骤,可以很方便的搭建起来Docbook环境。搭建的过程很简单,把那个链接当中提到的东西都下载安装后,就可以了。 之后,我们的重点就可以放在编辑XML文件了,Docbook本身有很多规则,可以参考链接2。由于我们只是准备一份文档,不许要像论文、书籍那么复杂,所以可以只用几个简单有用的元素,就满足我们的需求了。

下面是一个简单的例子,创建一个叫做 docbook5-demo.xml 的文件,编辑如下:

<?xml version='1.0' encoding="utf-8"?>
<article>
<artheader>
<title>Instruction Example</title>
<author><personname><firstname>Your Name</firstname></personname></author>
</artheader>
<sect1>
<title>Topological Diagram</title>
<figure>
<graphicfileref="picture.png"></graphic>
</figure>
</sect1>
<sect1><title>Pre</title>
<sect2><title>Backup following things:</title>
<para>item 1</para>
<para>item 2</para>
<para>item 3</para>
</sect2>
<sect2><title>Update things</title>
<sect3><title>Update xxx file in yyy folder</title>
<para>Remove items below: 
<itemizedlist>
<listitem>removed item1</listitem>
<listitem>removed item2</listitem>
</itemizedlist>
</para>
</sect3>
</sect2>
</sect1>
</article>

很好理解的文件,对吧。

第1行,是来规定文件的编码格式。

<article>定义一个article的开始,在最后有相应的</article>来关闭他。

<artheader>作为article的头,定义了文档的名称,以及作者,同样需要相应的</article>

<sect1>就是章节的划分了,在示例文件中我们会看到多个<sect1>,这些章节的序号会自动按照1、2、3这样的顺序生成。示例中的第一个section是一个插图,可以讲指定的图片插入到我们的文档中。<title>指出了该章节的标题;<graphic>元素中指出了插图的路径和名称,这里XML文件跟png文件在同一路径下。

往下看,我们会发现<sect2>这样的元素,他是我们插入的子章节,他的页面效果是这样的。第一层的<sect1>,会被展现成 2. 这样子,可以认为是表示第二章。<sect2>则会被展现成 2.1 这样子的,表示是第二章第一小节。后面的<sect2><sect3>以此类推。17行中的<para>表示一个章节中普通的段落。

在25行中,我们可以看到<itemizedlist>这个元素,他是一个列表。

到这里,我们已经编辑完我们的XML文件了。然后我们就可以按照最开始提到的链接1中所描述的那样,用相应的工具把这个XML文件转换成pdf文件。 这里分两步: 1. 首先要把XML文件转换成fo文件,在命令行模式中,去刚才编辑好的XML文件所在路径,运行:xsltproc -o ../output/fo/docbook5-demo.fo E:\DevRoot\docbook\config\docbook-xsl-ns-1.77.1\docbook_fo.xsl docbook5-demo.xml这里,-o 参数后面跟的是本次将要生成fo文件的路径和名称;E盘路径那个参数,表示生成fo文件时所要参考的格式文件;最后的参数,就是刚刚编辑好的XML文件. 2. 然后我们会得到一个叫做docbook5-demo.fo的文件,再运行:E:\DevRoot\docbook\tools\fop-1.0\fop.cmd -c E:\DevRoot\docbook\config\fop\fop.xconf -fo ../output/fo/docbook5_demo.fo -pdf ../output/pdf/docbook5_demo.pdf这里,第一个E盘路径表示我们此次要运行的命令,可以根据自己所设置的位置来调整;-c 跟的参数,表示此次转换时要是用的配置文件; -fo 就是刚才生成的fo文件路径; 最后-pdf表示此次要生成的pdf的路径和名称。

运行完上面两步,我们就可以得到一个pdf文件了!

最后,我们可以在本地自己搭建一个repository(git或者hg,随你自己喜欢),把编辑好的XML文件check in上去了。以后每次写完,可以运行上面两条命令来得到交付的pdf文件;编辑完的XML文件则完全纳入版本管理当中了,可以集中、方便地管理,查询以前的提交,两次之间的diff,都是方便得很~~

原文发布于微信公众号 - 思特沃克(ThoughtWorks)

原文发表时间:2014-03-28

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏数据和云

数据库高可用和分区解决方案-MongoDB 篇

许春植(Luocs) (阿里巴巴高级数据库管理员,7年以上数据库运维管理经验,擅长MySQL、Oracle及MongoDB数据库,目前主要研究并建设Mongo...

8516
来自专栏前端黑板报

插件化思维

用过构建工具的同学都知道,grunt, webpack, gulp 都支持插件开发。后端框架比如 egg koa 都支持插件机制拓展,前端页面也有许多可拓展性的...

1902
来自专栏linux驱动个人学习

调度器增强

到目前为止,我们只考虑了实时系统上的调度。事实上, Linux可以做得更好些。除了支持多个CPU之外,内核也提供其他几种与调度相关的增强功能,在以后几节里会论述...

1101
来自专栏Debian社区

为什么 Django 能持续统治 Python 开发世界

对于 Python 开发者来说,web 开发框架真可谓玲琅满目。然而 Django , 毋庸置疑的成为最受青睐的 web 框架。通过本篇博客,我来为大家讲解下为...

1043
来自专栏京东技术

老板们不知道的秘密:开启自动化测试,让我们一起以逸待劳

我认为所有的UI自动化测试都分成基本的三个步骤:定位元素,操作元素和执行断言。大家在做UI自动化不同的主要是方案的选型,封装优化的方式不同。目前移动App的更新...

2673
来自专栏ImportSource

MartinFowler告诉你大数据架构师必备的NoSQL技能-版本戳(上)

-许多NoSQL数据库的批评者老说NoSQL数据库不支持事务。 ? 事务是一个有用的工具,他可以帮助编程者解决一致性的问题。然而,NoSQL的推崇者并不担心这个...

3628
来自专栏大闲人柴毛毛

缓存世界中的三大问题及解决方案

目前的IO设备远不能满足互联网应用海量的读写请求。于是便出现了缓存,利用内存的高速读写性能来应付海量的查询请求。然而内存资源非常宝贵,将全量数据存储在内存中显...

3205
来自专栏无题

mongoDB生产环境三种模式

MongoDb在用于生产环境的三种模式,master/slaves(主从模式);replcation副本集;auto shard 分片模式 1.主从复制 ...

7875
来自专栏Java进阶干货

微服务架构组件分析

服务描述:服务调用首先解决的问题就是服务如何对外描述。 常用的服务描述方式包括 RESTful API、XML 配置以及 IDL 文件三种。

1171
来自专栏腾讯DevOps

Git的艺术—分支管理

Git的开发者—— Linus Benedict Torvalds,22岁就创建了Linux系统,发展到2005年的时候,用了仅两周的时间写了一个分布式版本控制...

56410

扫码关注云+社区

领取腾讯云代金券