初识DocBook（编写技术文档的工具）

突然在Linux下看到一堆命令：

[root@localhost default]# do
do            docbook2rtf   docbook2txt   dosfsck       doveconf      doxytag       
docbook2html  docbook2tex   domainname    dosfslabel    dovecot       
docbook2man   docbook2texi  done          doveadm       doxygen       
[root@localhost default]# man docbook2txt

马上百度了docbook的相关资料。

DocBook是一种文档工具，特别适合技术人员用做文档编写。感觉早该知道有这玩意了，就像知道visio和project这样良好的工具一样，好的工具就像是武侠世界里的神器，只不过这个神器人人可得，却不是人人知道。

下面内容是转载自 http://blog.sina.com.cn/s/blog_517d1cb00100uqcv.html

责搭建一个叫做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文件。

导入的过程：

1. 选择Project, 右键->“Import...”
2. 在Import对话窗口，填入“Archive”到“Select an import source”文本框中，然后选择“Archive File”节点，点击“Next”
3. 点击“Browser...”选择对应的zip文件，比如“D:\Download\docbook-5.0.zip”。点击“File Types...”,在“Select Types”对话窗口选择目标文件的扩展名，比如“*.dtd”，点击“OK”。
4. 点击“Finish”

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

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

1. 易于组织文档以及文档片断和插入文档中的图片等
2. 易于维护和管理
   

构建过程比较复杂：

1. 如果temp文件夹存在，删除
   
2. 拷贝src文件夹下的文件到temp文件夹（导出文件除外，比如*.pdf,*.html等）
   
3. 将隶属文件（partition source files）中的XML指令和DOCTYPE指令删除（用空格替换）
   
4. 将主文件中的DTD路径替换为公共路径（配置在build.properties文件中）
   
5. 扫描temp文件夹及其子文件夹下所有符合命名规则 - “*main.xml”的XML文件（即主文件）
6. 处理主文件，导出*.fo文件
7. 基于*.fo文件，导出*.pdf文件和*.rtf文件
8. 导出*.html文件（修改图片文件的绝对路径为相对路径 - 这样无论在本地还是Web服务器都可正常显示图片）

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