Marshal's Blog

使用docbook编写《Android ABC》

最近开始写一个大的文档，《Android ABC》，希望把一年来积累的Android知识整理一下。因为是和同事一起写，选择了docbook作为编写文档的方案。

第一个方案

在写文档之前，我们做了技术准备，主要是docbook生成pdf和docbook脚本自动化构建。最终选择了jdocbook和maven，并对fop等做了个别针对中文的配置和改动。可参见《转化docbook的maven工程的安装配置》。

按照上面链接的方式，开始使用的是docbook4.4，通过dtd做语法校验，并写出了文档目录和各章结构。在xml文档的dtd部分声明entity：

然后在文档需要的地方引用：

每个entity表示一个物理上分离的xml子文档：

jboss cache就是类似这种方式来写它的官方文档的。

这种方式可以工作，生成分页html，单页html以及pdf。

html页面目录：

生成的pdf文件目录部分：

但是存在问题：

• dtd的module方式物理分割文档，比较乱，无法在文档间导航；
• 另外，就是分割出来的文档不能再使用dtd，因此不好做语法校验，也不好借助工具做语法提示。

第二个方案

使用docbook 5.0 relex ng语法，好处是校验文件自身就是xml，语法更自然，在使用工具的情况下甚至可以做到所见即所得的编辑效果。

主文件的头部的变化：

<?xml version=’1.0′ encoding="utf-8"?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="zh-CN"
    xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Android ABC</title>
    <subtitle>帮助开发人员尽快入门</subtitle>

 

整理了文档结构：

引用文档的方式：

因为使用xi:include的方式，在maven文件中需要把xincludeSupported设置为true：

可以使用XMLmind XML Editor编辑docbook文件，该工具的presonal版本是免费的。网址：

http://www.xmlmind.com/xmleditor/

下载页面：

http://www.xmlmind.com/xmleditor/download.shtml

windows版本安装很简单，我是在ubuntu下执行，需要下载tar.gz版本。解压缩，然后执行：

bin/xxe &

然后打开页面，效果还不错：

这样，多人合作就会比较直观和容易。