转载_让Developer用DocBook编写技术文档

2011年，在回到ISS本部工作的头一个月，我负责搭建了一个叫做AutoDoc的环境用于帮助开发人员协作编写技术文档并生成各种不同类型的输出（比如：HTML,
PDF, RTF等）。

AutoDoc 的基础是 DocBook 以及 FOP, Ant, Ant-Contrib, Maven, Hudson, SVN 等技术和开源项目。

AutoDoc的总体架构图：





关于Hudson,Maven和SVN的安装和配置，这里我就不详述了。请参考官方文档。

我们需要在Eclipse里为AutoDoc创建一个Project，然后导入其他依赖的组件。下面是AutoDoc用到的资源：

docbook-5.0
docbook-xsl-ns-1.76.1
fop-1.0
ant-contrib
ant

(推荐使用DownThemAll!下载)

注意：apache-ant-1.7.*需要使用Java 1.6运行。其他版本，请查看Release Notes。

下面对各个组件需要导入的文件做一个简单的介绍：

docbook-5.0: 只需要导入docbook.dtd文件。
docbook-xsl-ns-1.76.1: 导入所有文件。
fop-1.0: 导入build和lib文件夹中的所有jar文件。
ant-contrib: 导入根目录下的ant-contrib-1.0b3.jar和lib文件夹下的所有jar文件。

导入的过程：

选择Project, 右键->“Import...”

在Import对话窗口，填入“Archive”到“Select an import source”文本框中，然后选择“Archive File”节点，点击“Next”

点击“Browser...”选择对应的zip文件，比如“D:\Download\docbook-5.0.zip”。点击“File Types...”,在“Select Types”对话窗口选择目标文件的扩展名，比如“*.dtd”，点击“OK”。

点击“Finish”

源文件（基于DocBook DTD的XML文件以及其他相关文件）的组织结构图：





采用这个组织结构的原因是：

易于组织文档以及文档片断和插入文档中的图片等

易于维护和管理

构建过程比较复杂：

如果temp文件夹存在，删除

拷贝src文件夹下的文件到temp文件夹（导出文件除外，比如*.pdf,*.html等）

将隶属文件（partition source files）中的XML指令和DOCTYPE指令删除（用空格替换）

将主文件中的DTD路径替换为公共路径（配置在build.properties文件中）

扫描temp文件夹及其子文件夹下所有符合命名规则 - “*main.xml”的XML文件（即主文件）

处理主文件，导出*.fo文件

基于*.fo文件，导出*.pdf文件和*.rtf文件

导出*.html文件（修改图片文件的绝对路径为相对路径 - 这样无论在本地还是Web服务器都可正常显示图片）

构建完毕，剩下的工作就是学习DocBook
DTD 和 DocBook
XSL了。基于此，Developer可以编写，修改和管理技术文档，并实现“一次编写，随便阅读”。