DocBook 助你完成传世之作

DocBook 是个什么样的东西呢？我敢打赌，大部分人都早已领略过了 DocBook 的风采。

搞IT的，没有听说过 Linux 的，一定是凤毛麟角。而且，大多数人也一定从Linux的丰富的Howto文档获益匪浅。可是，知道么，大部分 Howto 文档就是用 DocBook 格式完成的。

HOWTO文档中描述的细节可能会逐渐淡忘，但相信大多数人一定会对其一致的文档风格还有清晰的印象，为一个HOWTO文档能有那么多的输出格式（单独的HTML文档，每章一页的HTML文档，PDF格式，WORD文档，...）而惊叹。

而最让人惊叹的要数这些文档的写作方式：分布在世界各地的作者们，使用CVS作为版本控制软件，以DocBook作为文档的格式，协作完成一个又一个的传世之作。

初识了 DocBook，你是否动心了？不过，别急。在深入介绍DocBook之前，先介绍一个实际操作的例子。本例是作者在撰写本书过程中的一个真实的小片断。

为什么要使用DocBook呢？

前面说了这么多DocBook的好话，大家也粗粗的对DocBook有了一点感观上的认识，那么DocBook到底是什么呢？

DocBook 已经有十来年的历史了。它起源于1991年，HaL Computer Systems和O'Reilly公司的一个合作项目。该项目负责推动和以Troff标记语言标记的Unix文档资料的交互。随着该项目不断壮大，该项目的维护便由论坛——Davenport小组维护。1998年，在OASIS(Organization for the Advancement of Structured Information Standards，结构化信息标准促进组织)下成立了一个专门的技术委员会。

DocBook仍在继续发展当中，欲了解DocBook的最新动态，请参考：oasis-open.org。

接下来的章节中，我们先通过一个最为简单的例子《Hello World》，来学习DocBook环境的搭建；

下面是一个符合 sgml 标准的 DocBook 文档——"Hello World!"。虽然它还非常简陋，但是麻雀虽小，五脏俱全。它完全是一个合格的DocBook文档。

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN">	
<article>		
<articleinfo>
  <title>Hello World!</title>
  <author><firstname>名</firstname><surname>姓</surname></author> 
</articleinfo>

<sect1><title>Hello World!</title>	
  <para>
  Hello world! 这是我的第一个 DocBook 文档。
  </para>
</sect1>
</article>	

	文档类型声明（Document Type Declaration），声明该文档的根元素是 article。
	文档中的唯一的根元素——article
	在此处添上作者的姓名
	第一章开始。根元素article可以包含任意多的sect1元素。
	本文档的根元素结束。

即使还没有接触过 DocBook，也不会有人认为以上的 Hello World 文档是一个天书。DocBook 文档是自解释的，通过一个个元素（由尖括号封闭起来的），定义了清晰的文档结构。这片文档是一篇文章（article），它有自己的标题——“Hello World!”，和作者的姓名，它还包含一个章节（sect1），章节的标题是“Hello World!”，内容则是简简单单的一句话。我们把这个文件保存为 helloworld.sgml。

这就大功告成了么？还没有，我们仅仅完成了 DocBook 文档的撰写。借用程序开发的概念，我们仅仅完成了源代码的编写，还没有生成最终的软件产品（可执行文件）呢，甚至还没有测试过。那么，接下来我们的工作就是先通过安装工具软件来搭建环境，再进行文档的编译，形成所需要的输出格式——HTML、RTF等等。

我们在前面提到过，DocBook最早采用的是SGML技术，目前已经有了相应XML技术的实现。为什么不直接选用XML，仍然在SGML上浪费时间呢？这是因为：

下面我们就学习通过我们上面建立的编译环境，将我们的 Hello World 文档转换成可以用来显示的HTML格式和可以打印的RTF格式。

SGML/XML有着陡峭的学习曲线，主要是因为一开始就要面对铺天盖地的新概念。学习DocBook，虽然并不需要对SGML/XML的所有概念都去透彻了解，但是需要掌握的也仍是够怕人的。下面的这些概念都熟悉么？如果答案是肯定的，那么你可以轻松的跳过这一章。

SGML/XML文件由字符数据和标记组成，下面就是SGML/XML所支持的几种不同的标记：

<!-- 这是一端注释... -->

<?xml version="1.0" ?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2b1//EN"  [
<!ENTITY author "<ulink url='mailto:johnson@worldhello.net'>Johnson</ulink>">
<!ENTITY orgname "<ulink url='http://www.worldhello.net'>worldhello.net</ulink>">
<!ENTITY chap1  system "chap1.sgml">
<!ENTITY chap2  system "chap2.sgml">
<!ENTITY chap3  system "chap3.sgml">
<!ENTITY chap4  system "chap4.sgml">
<!ENTITY chap5  system "chap5.sgml">
<!ENTITY chap6  system "chap6.sgml">
<!ENTITY chap7  system "chap7.sgml">
<!ENTITY chap8  system "chap8.sgml">
<!ENTITY chap9  system "chap9.sgml">
<!ENTITY chap10 system "chap10.sgml">
<!ENTITY appendix system "appendix.sgml">
]>

<screen>
&lt;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2b1//EN"  [
&lt;!ENTITY author "&lt;ulink url='mailto:johnson@worldhello.net'&gt;Johnson&lt;/ulink&gt;"&gt;
&lt;!ENTITY orgname "&lt;ulink url='http://www.worldhello.net'&gt;worldhello.net&lt;/ulink&gt;"&gt;
&lt;!ENTITY chap1  system "chap1.sgml"&gt;
&lt;!ENTITY chap2  system "chap2.sgml"&gt;
&lt;!ENTITY chap3  system "chap3.sgml"&gt;
&lt;!ENTITY chap4  system "chap4.sgml"&gt;
&lt;!ENTITY chap5  system "chap5.sgml"&gt;
&lt;!ENTITY chap6  system "chap6.sgml"&gt;
&lt;!ENTITY chap7  system "chap7.sgml"&gt;
&lt;!ENTITY chap8  system "chap8.sgml"&gt;
&lt;!ENTITY chap9  system "chap9.sgml"&gt;
&lt;!ENTITY chap10 system "chap10.sgml"&gt;
&lt;!ENTITY appendix system "appendix.sgml"&gt;
]&gt;
</screen>

<screen>
<![CDATA[
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2b1//EN"  [
<!ENTITY author "<ulink url='mailto:johnson@worldhello.net'>Johnson</ulink>">
<!ENTITY orgname "<ulink url='http://www.worldhello.net'>worldhello.net</ulink>">
<!ENTITY chap1  system "chap1.sgml">
<!ENTITY chap2  system "chap2.sgml">
<!ENTITY chap3  system "chap3.sgml">
<!ENTITY chap4  system "chap4.sgml">
<!ENTITY chap5  system "chap5.sgml">
<!ENTITY chap6  system "chap6.sgml">
<!ENTITY chap7  system "chap7.sgml">
<!ENTITY chap8  system "chap8.sgml">
<!ENTITY chap9  system "chap9.sgml">
<!ENTITY chap10 system "chap10.sgml">
<!ENTITY appendix system "appendix.sgml">
]>

]]>
</screen>

DSSSL? 不要被这个缩略语吓坏，它是（Document Style Semantics and Specification Language）的缩写。DSSSL和SGML的关系，就如同CSS和HTML的关系一样。对于DTD来说，只关心元素之间的结构关系，并不关心元素的意义和具体的表现形式，而这正好是DSSSL的天下。一个DocBook文档，通过各种元素将文档内容结构化，但是看起来并不直观，不能提供诸如Word、PDF、网页一样的表现。DSSSL提供了一个将SGML文档到其他输出格式的标准方法。

让我们先看一段 DSSSL 片断：

(define (book-titlepage-recto-elements)
  ;; elements on a book's titlepage
  ;; note: added revhistory to the default list
  (list (normalize "title")
        (normalize "subtitle")
        (normalize "graphic")
        (normalize "mediaobject")
        (normalize "corpauthor")
        (normalize "authorgroup")
        (normalize "author")
        (normalize "editor")
        (normalize "copyright")
        (normalize "pubdate")
        (normalize "revhistory")
        (normalize "abstract")
        (normalize "legalnotice")))

(element emphasis
  ;; make role=strong equate to bold for emphasis tag
  (if (equal? (attribute-string "role") "strong")
     (make element gi: "STRONG" (process-children))
     (make element gi: "EM" (process-children))))

也许那些骨灰级程序设计师和计算机史学家会对上述代码感到亲切，而对于像我这样了解程序设计语言是从basic、c开始的新手，一定会对这种语法一头雾水。这段代码的语法来自于 Scheme语言（LISP的一个变种）。

(+ 3 1) ;return 4

  Scheme                               C
------------------------------------------------------------------
(+ 2 3 4)                       (2 + 3 + 4) 
(< low x high)                  ((low < x) && (x < high)) 
(+ (* 2 3)                      (* 4 5)) ((2 * 3) + (4 * 5)) 
(f x y)                         f(x, y) 
(define (sq x) (* x x))         int sq(int x) { return (x * x) } 

(define x 3)
(begin
  (set! x (+ x 1))
  (+ x x))             ; 返回结果 8

DTD定义了SGML文档的结构。在元素的一节，我们已经介绍了元素声明的语法，元素声明即是DTD的最重要的内容。

一个DTD就是用SGML语法表达的一系列语法声明。下面让我们通过一个例子，来学习DTD。

SGML/XML要遵从如下两个规则，一个是好形（well-formed）规则，一个是合法性（Valid）

SGML/XML的文件主要由如下三部分构成：Elements, Attributes and Entities。

是SGML的一个子集，它简化了SGML的设计。既然XML就是SGML，而DocBook已经有了SGML的实现，我们有必要学习XML么？

文档的要素： An SGML Declaration, A Document Type Declaration, An Internal Subset, and The Document (or Root) Element

	其实XML和SGML并无太大区别，只要在写SGML格式的DocBook时遵从： If you are interested in future XML compatibility, input all element and attribute names strictly in lowercase. If you are interested in future XML compatibility, always quote all attribute values.

用 XML 撰写DocBook文档

Breaking a Document into Physical Chunks

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY chap1 SYSTEM "chap1.sgm">
<!ENTITY chap2 SYSTEM "chap2.sgm">
<!ENTITY chap3 SYSTEM "chap3.sgm">
<!ENTITY appa SYSTEM "appa.sgm">
<!ENTITY appb SYSTEM "appb.sgm">
]>
<book><title>My First Book</title>
&chap1;
&chap2;
&chap3;
&appa;
&appb;
</book>

The Categories of Elements in DocBook

Sets 
Books 
Divisions, which divide books into parts 
Components, which divide books or divisions into chapters 
Sections, which subdivide components 
Meta-information elements 
Block elements : lists, admonitions, line-specific environments, synopses of several sorts, tables, figures, examples, ...
Inline elements : Acronym, Emphasis ...

撰写DocBook文档的过程，就是熟悉和使用DocBook元素的过程。Norman Walsh 和 Leonard Muellner 提供的可供免费下载的《DocBook: The Definitive Guide 》，是最佳参考。本书并不罗列这400个元素的语法声明，而是对常用的元素作以总结和示范。

DTD 规定语法、语义；DSSSL 定义样式。

A Survey of Stylesheet Languages

Over the years, a number of attempts have been made to produce a standard stylesheet language and, failing that, a large number of proprietary languages have been developed.

cvs...

apache...

htdig...

测试人员一直背负着效率低下的恶名。在大多数公司中，他们是中最不受重视的一个角色，在出现软件危机时，也是最先要受到“株连”的。我的一位担任测试经理的朋友，对此是深有感触。下面是他的牢骚：

您是否也遇到了同样的问题呢？

我们来帮助他寻找一下问题的症结所在吧。是什么原因导致测试的工作没有得到足够的重视呢？是因为看不到测试工作的价值。这又是为什么呢？测试工作没有秩序的，难以及时发现问题，当软件产品抱着极大的期望值上市的时候，漏洞百出，人们当然习惯性的反推，为什么没有能够测试出来？进一步会问，到底测试了哪些功能？如果这时测试部门回答不出，那么可能就要有人要承担责任了。这当然不一定是测试的错。但是测试部门能够拿出一整套测试用例文档，告诉项目经理，这些都是我们测试通过的。那么问题的焦点就回到了分析测试用例上了。是不是有发现问题的测试用例？如果有，是哪个测试人员的疏忽导致问题没有找到？如果是测试用例没有覆盖到，那么就应该借这个代价昂贵的机进一步补充和完善测试用例，确保不会再出现类似问题。

如果以上的分析大致正确的话，测试用例文档的积累，是重树测试部门形象的良机。DocBook正好适合这种需要持续积累的技术文档的撰写，再配合版本控制软件，建立一套可行的测试用例撰写和维护规范应该不难。当我把DocBook介绍给我的这位担任测试经理的朋友之后，他真的用 DocBook 改进了他的工作，得到领导的赏识。这不能不说是一个奇迹。

下面是改进的测试部门的工作流程：

如图9-1，是一个DocBook撰写测试用例的示例，后面是其代码。

图9-1. 用DocBook编写可以持续维护的测试用例

测试用例的 DocBook 源代码

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2b1//EN"  [
<!ENTITY compname "<ulink url='mailto:yourname@email.address'>某某公司</ulink>">
]>
<article>
<articleinfo>
  <title>B2B网站测试用例汇总</title>
  <author><firstname>测试部</firstname></author>
  <revhistory>
    <revision>
      <revnumber>1.1</revnumber>
      <date>2002/12/11</date>
      <authorinitials>David</authorinitials>
      <revremark>添加测试用例2</revremark>
    </revision>
    <revision>
      <revnumber>1.0</revnumber>
      <date>2002/12/10</date>
      <authorinitials>Johnson</authorinitials>
      <revremark>添加测试用例1</revremark>
    </revision>
  </revhistory>
  <abstract>
    <para>
    本文档作为公司的测试部门的测试用例汇总，是测试部门测试工作中的参考。有任何补充和更改的需要，请用 CVS 从服务器中Checkout本文档的源代码，修改完毕后，提交 CVS 服务器。测试部门的内部网站会在每小时重新编译改动过的文档。
    </para>
    <para>
    &compname;, $Revision$, $Date$
    </para>
  </abstract>
</articleinfo>

<sect1><title>TESTB2B-0001</title>
<informaltable  frame='all'>	
<tgroup cols='8' align='left' colsep='1' rowsep='1'>
  <colspec colname='c1'/>
  <colspec colname='c2'/>
  <colspec colname='c3'/>
  <colspec colname='c4'/>
  <colspec colname='c5'/>
  <colspec colname='c6'/>
  <colspec colname='c7'/>
  <colspec colname='c8'/>
<tbody>
  <row>
    <entry>项目编号</entry>
    <entry>B2B</entry>
    <entry>项目名称</entry>
    <entry>电子商务网站测试</entry>
    <entry>测试日期</entry>
    <entry></entry>			
    <entry>测试人员</entry>		
    <entry></entry>
  </row>
  <row>
    <entry>测试用例编号</entry>
    <entry>TESTB2B-0001</entry>
    <entry>测试用例名称</entry>
    <entry>用户登录测试</entry>
    <entry>作者</entry>
    <entry>Johnson</entry>
  </row>
  <row>
    <entry>测试用例描述(方法和目的)</entry>
    <entry namest="c2" nameend="c8">
      <para>测试登录界面对不同浏览器的兼容性；</para>
      <para>测试异常输入对CGI的影响；</para>
    </entry>
  </row>
  <row>
    <entry>测试环境设置</entry>
    <entry namest="c2" nameend="c8">
      <para>测试平台：Windows 98 + IE4.0；Windows 98 + IE5.0；Windows 98 + IE6.0；Windows 2000 + IE5.0；Linux + Mozilla</para>
    </entry>
  </row>
</tbody>
</tgroup>
</informaltable >

<table  frame='topbot'><title>测试步骤</title>
<tgroup cols='4' align='left' colsep='1' rowsep='1'>
  <colspec colwidth='1*'/>
  <colspec colwidth='20*'/>
  <colspec colwidth='10*'/>
  <colspec colwidth='5*'/>
<thead>
  <row>
    <entry>序号</entry><entry>操作</entry><entry>预期结果</entry><entry>实际结果</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>1</entry>
    <entry>
      <para>Windows 98 + IE4.0登录开发服务器:"http://10.0.0.99/servlet/login"；</para>
      <para>输入用户名密码:test/test555</para>
    </entry>
    <entry>
      <para>登录成功，进入用户自定义界面。</para>
    </entry>
    <entry>
    </entry>
  </row>
  <row>
    <entry>2</entry>
    <entry>
      <para>Windows 98 + IE5.0登录开发服务器:"http://10.0.0.99/servlet/login"；</para>
      <para>输入用户名密码:test/test555</para>
    </entry>
    <entry>
      <para>登录成功，进入用户自定义界面。</para>
    </entry>
    <entry>
    </entry>
  </row>
  <row>
    <entry>...</entry>
    <entry>
      <para>...</para>
      <para>...</para>
    </entry>
    <entry>
      <para>...</para>
    </entry>
    <entry>
    </entry>
  </row>
</table>

<note>
  <para>
  其他注意事项：
  </para>
</note>
</sect1>


<sect1><title>TESTB2B-0002</title>	
<para>
...
</para>
</sect1>

</article>

	不带标题行的表格。
	作为模板，此项留空，在实际测试过程中，该表格打印，手工填写存档。
	以追加方式增加新的测试用例。

目前介绍软件工程和项目管理的书是越来越多了。遍历各家之说，体会最深的是两个字：“沟通”。没有沟通，开发人员单枪匹马，重复着“前辈们”走过的路，缓慢的成长着。没有沟通，测试和开发团队就在没完没了的争吵中迎接项目的延期。没有沟通，部门之间的鸿沟足可以吓退客户。没有沟通，公司的决策人还在期盼着项目的成功的那一天，而不知道危险已经临近。沟通是这么样的重要，而项目经理就是这些沟通途径的交汇点。

每个公司都会对项目经理有着这样或者那样的沟通上的要求，比如常见的周计划、月计划。它们是是项目经理分解任务以及向直接上级汇报工作的重要工具。自从南开大学毕业以来的几年间，我做得最多的职位就是项目经理，已经不记得写了多少计划。很长一段时间，一旦写完计划，发出邮件便了事，计划也就在本地磁盘中不知去向。后来，在做项目总结时，有些里程碑事件实在是想不起来，只是依稀记得在某个项目计划中曾经提到过。于是，从邮件的故纸堆中查找，经常是费了半天劲一无所获。从此就有了把项目总结和项目日志积累起来的习惯。最开始的文档管理手段是比较落后的，直接放到文件服务器中，对于项目日志，就是每天在 Word 文档后面追加，直到有一天，一个不留神把项目日志整个覆盖掉了，那是可真是后悔不迭。有什么技术，可以对文档像对代码一样的版本控制呢？我发现了 DocBook，从此便用 DocBook 开始我的新的项目日志。

项目日志的文件格式是以一周为一个章节，每章节分为两个部分，日志部分是每天的“流水账”（记录比较重要的事件），周计划部分，是上周的项目总结和下一个星期的工作计划。如图9-2。用 DocBook 维护你的项目日志，让你的领导对你刮目相看。

图9-2. 用DocBook编写项目日志

图9-3. 用DocBook编写项目周计划

以下是DocBook 源代码：

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2b1//EN"  [
<!ENTITY yourname "<ulink url='mailto:yourname@email.address'>Your Name</ulink>">
]>
<article>
<articleinfo>
  <title>项目日志</title>
  <author><firstname>作者姓名</firstname></author>
  <abstract>
    <para>
    项目日志和项目计划，为项目组同志提供参考。
    </para>
    <para>
    &yourname;, $Revision$, $Date$
    </para>
  </abstract>
</articleinfo>

<sect1 id="w021028"><title>1028--1101</title> 

<sect2 id="daily021028"><title>日志</title>
<itemizedlist>
  <listitem>	
    <para>
    2002/10/30, 3
    </para>
    <orderedlist>
      <listitem>
        <para>
        完成任务：******
        </para>
        <para>
        David
        </para>
      </listitem>
      <listitem>
        <para>
        完成任务：******
        </para>
        <para>
        Johnson
        </para>
      </listitem>
    </orderedlist>
  </listitem>
  
  <listitem>
    <para>
    2002/10/29, 2
    </para>
    <orderedlist>
      <listitem>
        <para>
        Seminar: ******
        </para>
        <para>
        yzw
        </para>
      </listitem>
    </orderedlist>
  </listitem>
  
  <listitem>
    <para>
    2002/10/28, 1
    </para>
    <orderedlist>
      <listitem>
        <para>
        讨论需求：******
        </para>
        <para>
        Mahui
        </para>
      </listitem>
    </orderedlist>
  </listitem>
</itemizedlist>
</sect2>

<sect2 id="weekly021028"><title>周报</title> 

<segmentedlist>
  <segtitle>填表日期</segtitle><segtitle>填表人</segtitle><segtitle>时 间</segtitle><segtitle>主要工作</segtitle>
  <seglistitem>
    <seg>2002/10/28</seg>
    <seg>Johnson</seg>
    <seg>2002/10/28－2002/11/01</seg>
    <seg>******</seg>
  </seglistitem>
</segmentedlist>

<orderedlist>
  <listitem>                              
    <table frame='all'><title>本周工作计划表</title>
    <tgroup cols='2' align='left' colsep='1' rowsep='1'>
    <colspec colname='c1' colwidth="300pt" >
    <colspec colname='c2' colwidth="80pt" >
    <thead>
    <row>
    <entry>本周工作任务</entry>
    <entry>相关人员</entry>
    </row>
    </thead>
    <tbody>
    
    <row>
    <entry>
    <para>
    工作任务1...
    </para>
    </entry>
    <entry>
    人员1
    </entry>
    </row>
    
    <row>
    <entry>
    <para>
    工作任务1...
    </para>
    </entry>
    <entry>
    人员2
    </entry>
    </row>
    
    <row>
    <entry>
    工作任务3...
    </entry>
    <entry>
    人员3
    </entry>
    </row>
    
    </tbody>
    </tgroup>
    </table>
    <note>
    <title>备注</title>
    <para>
    </para>
    </note>
  </listitem>
  
  <listitem>               
    <table frame='all'><title>上周项目进展</title>
    <tgroup cols='2' align='left' colsep='1' rowsep='1'>
    <colspec colname='c1' colwidth="300pt" >
    <colspec colname='c2' colwidth="80pt" >
    <thead>
    <row>
    <entry>任务名称</entry>
    <entry>负责人</entry>
    </row>
    </thead>
    <tbody>
    
    <row>
    <entry>
    完成上周任务1...
    </entry>
    <entry>
    人员1
    </entry>
    </row>
    
    <row>
    <entry>
    完成上周任务2...
    </entry>
    <entry>
    人员2
    </entry>
    </row>
    
    <row>
    <entry>
    完成上周任务3...
    </entry>
    <entry>
    人员3
    </entry>
    </row>
    
    </tbody>
    </tgroup>
    </table>
    <note>
    <title>备注</title>
    <para>
    </para>
    </note>
  </listitem>
</orderedlist>

</sect2>
</sect1>

<sect1 id="w021021"><title>1021--1025</title>  
<sect2 id="daily021021"><title>日志</title>
<para>
...
<para>
</sect2>
<sect2 id="weekly021021"><title>周报</title>
<para>
...
<para>
</sect2>
</sect1>

</article>

	10月28日到11月1日的一个星期的日志和周计划。每周开始一个新的章节。
	10月30日（星期三）的项目日志。最新的日期总是在最前。每天的项目日志只需要重复拷贝一下前一天日志的结构即可。
	周计划开始，包括本周计划和上周项目进展。
	本周工作计划。
	上周项目进展。
	上周项目进展。
	上一个星期的项目日志和工作计划。

版本变更说明，又叫做"Release Notes"，"Changes"，经常伴随着软件产品一道发布，提供给最终用户。该文档也可以在开发小组内部的参考。该文档的维护，意味着开发工作在继续，否则意味着项目的终结。该文档的维护也反映了软件开发中配置管理的水平以及软件开发对市场、对BUG的响应能力。

同时，该文档的维护非常频繁，而且用户需要的格式也是五花八门，如常见的网页格式，纯文本格式，PDF格式等。如何尽量保证该文档的更新和产品版本提升保持同步，是困扰很多项目组的一个难题。使用 DocBook 不难作出国际水准的版本变更说明。

图9-4 就是一个版本变更说明的范例。

图9-4. 版本变更说明

以下是DocBook 源代码：

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2b1//EN"  [
<!ENTITY yourname "<ulink url='mailto:yourname@email.address'>Your Name</ulink>">
]>
<article>
<articleinfo>
  <title>Linktrust Cyberwall 2.4版本变更说明书</title>
  <author><firstname>作者姓名</firstname></author>
  <revhistory>
    <revision>
      <revnumber>1.4</revnumber>
      <date>2002/11/29</date>
      <authorinitials>caijm</authorinitials>
      <revremark>
      补充 2.4.0040版本更改记录；
      </revremark>
    </revision>
  </revhistory>
  <abstract>
    <para>
    记录当前版本号（build number）下，添加的新功能和修改的BUG。
    </para>
    <para>
    &yourname;, $Revision$, $Date$
    </para>
  </abstract>
</articleinfo>


<sect1><title>Build 2.4.0040 Major changes</title>
  <sect2><title>版本信息</title>
  <segmentedlist><title>版本信息</title>
    <segtitle>版本号</segtitle>
    <segtitle>编译日期</segtitle>
    <segtitle>Cyberwall Label</segtitle>
    <segtitle>LTOS Tag</segtitle>
    <segtitle>描述</segtitle>
    <seglistitem>
      <seg>2.4.0040</seg>
      <seg>20021128</seg>
      <seg>2.4.0040-last</seg>
      <seg>LTOS24B_021128_DONTPANIC</seg>
      <seg>collect crash data</seg>
    </seglistitem>
  </segmentedlist>
  </sect2>

  <sect2><title>New features or changes since Build 2.4.0039</title>
    <itemizedlist>
      <listitem>
        <para>
        panic后把信息写到磁盘；[xucm]
        </para>
      </listitem>
      <listitem>
        <para>
        加入了对Intel 82543/82544/82545 系列千兆卡的支持；[xucm]
        </para>
      </listitem>
      <listitem>
        <para>
        change lt software dog timeout from 10 seconds to 8 seconds；[song]
        </para>
      </listitem>
      <listitem>
        <para>
        修改tcp状态机算法；[song]
        </para>
      </listitem>
      <listitem>
        <para>
        WEB界面ha增加心跳线设置；[wuzj]
        </para>
      </listitem>
    </itemizedlist>
  </sect2>

  <sect2><title>Bugs fixed since Build 2.4.0039</title>
    <itemizedlist>
      <listitem>
        <para>
        fix vrrp interface number checking problem; [qianxb]
        </para>
      </listitem>
      <listitem>
        <para>
        改正WEB界面“应用”后ie浏览器上方的显示调用情况的黑色地球标志一直转动的问题；[mahui]
        </para>
      </listitem>
    </itemizedlist>
  </sect2>
</sect1>
</article>