使用Docbook编写技术文档

DocBook 作为风行于开放源码世界的一种文档撰写格式，已经成为很多组织和公司撰写技术文档的事实上的规范。DocBook 提供了一种基于SGML/XML的、面向语义、面向结构、纯文本格式、可版本控制的文档撰写模式，它打破了传统的、面向表现的、所见即所得的、基于私有格 式的文档撰写模式。基于SGML/XML的面向结构的文档，使得 DocBook 格式的文档，成为一种真正的万能格式的文档，几乎可以转换为任何一种文档格式。而属于纯文本范畴的 DocBook 文档，更可以利用版本控制软件，实现多人协作维护。

一、搭建Docbook使用环境（以windows系统下为例）
    1、下载Docbook XSL样式表
       只需要docbook-xsl-ns即可（例如目前的软件包版本docbook-xsl-1.77.0.tar.bz2），并解压到某个路径下（例如D:\docbook\docbook-xsl-ns-1.77.0目录）。
    2、安装xsltproc转换程序
       下载libxslt – XSL和EXSL转换工具，xsltproc程序就在此包中。目前的版本是libxslt-1.1.26.win32.zip
       该程序包依赖于以下几个软件：      
       iconv – 编码转换工具（例如iconv-1.9.2.win32.zip）
       zlib – 压缩工具（例如zlib-1.2.5.win32.zip）
       libxml2 – XML解析工具和处理工具（例如libxml2-2.7.8.win32.zip）
       将以上几个软件包中的文件解压到同一个文件夹中（例如D:\docbook\xsltproc目录，它包含有bin、include、lib子目录）。
    3、安装可选的其它软件包
       例如，可以安装fop-1.0-bin.tar.gz，它用于把Docbook文档转换成PDF格式的文档。

二、编写Docbook文档
    下面是一个Docbook 5.X文档的内容，将其保存到一个xml文件中（例如，docbook.xml）。

  xmlns:xlink=''>
 
   
   
      saodrin
      Zhang
   
 
 

   
   
      这是一个使用Docbook 5.X编写技术文档的示例，欢迎你参考DocBook网址上的内容。
   
   

     
   

   

     
     
       
         
       
       
          Here there's an image of JPG example
       
       
          JPG picture's caption.
       
     
   

   

     
     
       
         
       
       
          Here there's an image of GIF example
       
       
          GIF picture's caption.
       
     
   

 

以上的单个文档实体还可以嵌套到一个大的文档中（例如下面的test.xml文件）：

    ""
    [
       
    ]
>


&chap1;

可以在上面的book内添加多个chap章节。

三、将文档转换为HTML格式
    在转换之前，需要把输出编码设置为UTF-8（文档中所指定）。docbook-xsl-ns的缺省输出编码是ISO-8859-1，因此可以另写一个xsl文件，在这个文件中包含标准的docbook-xsl，然后重新定义自己的编码为UTF-8。例如自定义的docbook_usr.xsl文件内容：

                version='1.0'>

            encoding="UTF-8"
            indent="no"/>

然后，可以使用命令将Docbook文档编译成HTML文档。例如，在cmd窗口中D:\docbook\samplebook路径下执行以下命令：
..\xsltproc\bin\xsltproc.exe -o test.html docbook_usr.xsl test.xml
则生成了test.html文件。
最后，可以使用浏览器直接打开html文件来验证和查看。

四、发布或转换输出
    可以将Docbook文档添加到版本控制系统中，随时发布更新或者转换成其它如PDF等格式的文档。