构建jBPM用户指南文档

构建jBPM用户指南文档

jBPM用户指南DocBook构建说明

---

第 1 章 构建jBPM用户指南文档

1.1. jBPM用户指南的build.xml文件

文件jbpm.3/src/userguide/build.xml内容如下：

<project name="jbpm.3.documentation" default="all.doc" basedir=".">

  <property name="build.dir" value="${basedir}/../../build/userguide"/>
  <property name="pdf.name"  value="jboss-jbpm.pdf" />
  <import file="../../../docbook-support/support.xml" />

  <target name="all.doc" depends="clean">
    <mkdir dir="en/images" /> 
    <antcall target="lang.all"><param name="lang" value="en"/></antcall>
  </target>

  <target name="html.doc" description="creates the html docs only and opens a browser">
    <mkdir dir="en/images" /> 
    <antcall target="lang.dochtml"><param name="lang" value="en"/></antcall>
    <exec executable="C:/Program Files/Internet Explorer/IEXPLORE.EXE" os="Windows XP,Windows 2000,Windows 98">
      <arg value="file://${basedir}/../../build/userguide/en/html/index.html" />
    </exec>
  </target>

</project>

在Eclipse环境下选中它右键，选择运行方式/Ant 构建。发现找不到../../../docbook-support/support.xml。

1.2. 哪里获得docbook-support/support.xml

连上jboss的CVS服务器：

:pserver:[email protected]:/cvsroot/jboss

选择HEAD/docbook-support（注意：我取过版本/docbook-support/docbook-support JBoss_4_0_4_RC2，会报错），点击右键选择检出为，目录设为跟jBPM.3同级的。

检出后选择jbpm.3/src/userguide/build.xml，右键菜单运行方式/Ant 构建。构建完后，可以在jbpm.3/build/userguide发现编译好的文档，它分别包括HTML分页版、单页版和PDF版，但是PDF版没生成成功。

1.3. PDF版为什么没生成成功

我们在Eclipse的控制台可以看到：

     [java] Making portrait pages on USletter paper (8.5inx11in)
     [java] Error: no ID for constraint linkend: processcompositioningop.

意思是文档中有个链接processcompositioningop没找到。

打 开jbpm.3/src/userguide/en/modules/gop.xml，搜索到第497行的processcomposition，改为 processcompositioningop，重新构建。构建完可以在jbpm.3/build/userguide/en/pdf目录下看到刚生成 的jboss-jbpm.pdf。

1.4. 编译其它语言版本

在jbpm.3/src/userguide目录还可以看到一个目录de,德语版的。现在我们开始构建德语版的。

改jbpm.3/src/userguide/build.xml中的内容如下：

<project name="jbpm.3.documentation" default="all.doc" basedir=".">

  <property name="build.dir" value="${basedir}/../../build/userguide"/>
  <property name="pdf.name"  value="jboss-jbpm.pdf" />
  <import file="../../../docbook-support/support.xml" />

  <target name="all.doc" depends="clean">
    <mkdir dir="en/images" /> 
    <antcall target="lang.all"><param name="lang" value="en"/></antcall>
    <mkdir dir="de/images" /> 
    <antcall target="lang.all"><param name="lang" value="de"/></antcall>
  </target>

  <target name="html.doc" description="creates the html docs only and opens a browser">
    <mkdir dir="en/images" /> 
    <antcall target="lang.dochtml"><param name="lang" value="en"/></antcall>
<!--     <exec executable="C:/Program Files/Internet Explorer/IEXPLORE.EXE" os="Windows XP,Windows 2000,Windows 98">
      <arg value="file://${basedir}/../../build/userguide/en/html/index.html" />
    </exec>-->
    <mkdir dir="de/images" /> 
    <antcall target="lang.dochtml"><param name="lang" value="de"/></antcall>
  </target>

</project>

构建出错，控制台出错信息为：

E:/java/workspace/docbook-support/support.xml:159: E:/java/workspace/docbook-support/styles/de not found.

意思是风格文件没找到。

打开docbook-support/styles，只看到en（英文版的），暂且复制一份en，重命名为de到docbook-support/styles目录。重新构建。

构建出错，控制台出错信息为：

     [java] Error on line 33 column 4 of file:/E:/java/workspace/jbpm.3/src/userguide/de/master.xml:
     [java] Error reported by XML parser: Cannot read from file:/E:/java/workspace/jbpm.3/src/userguide/de/modules/Konfiguration.xml (E:/java/workspace/jbpm.3/src/userguide/de/modules/Konfiguration.xml (The system cannot find the file specified))

找不到Konfiguration.xml，去掉jbpm.3/src/userguide/de/master.xml中关于Konfiguration.xml的内容如下：

<!--
<!ENTITY Konfiguration SYSTEM "modules/Konfiguration.xml">
-->
<!-- &Konfiguration; -->

重新构建。构建完后，可以在jbpm.3/build/userguide/de/目录下看到编译好的文档，它分别包括HTML分页版、单页版和PDF版。

1.5. 附：名词解译

1.5.1. HTML

超 文本标记语言（Hyper Text Markup Language）。是网页的标准格式。实际上HTML文件是一种纯文本文件，里面包含了很多HTML标记和被标记对括起来的文本，如“< br>”“<hr>”“<table>...</table& gt;”“<font>...</font>”，网页浏览器根据这些标记将HTML中标记的文 本显示出不同的格式。

1.5.2. XML

可扩展标记语言（eXtensible Markup Language）。是人们所期待的下一代互联网 标准。从表面上看，XML很像HTML，也有很多标记和标记对，不同之处在于：

• 语法更加严格、统一

• 到底包含那些标记，标记之间如何嵌套如何组织，需要另外定义

• 标记的含义到底是什么，软件应如何处理这些标记，需要另外定义

这后两点，就是XML“可扩展”的原因。

1.5.3. DTD

文档类型定义（Document Type Definition）。一种定义XML文档“到底包含那些标 记，标记之间如何嵌套如何组织”等等事项的文件格式。

1.5.4. DocBook

一套基于XML的规范，即一套定义好的XML标记。它包括一份DTD和一份文档《DocBook：The Definitive Guide》。DTD定义了这种格式的结构，即“到底包含那些标记，标记 之间如何嵌套如何组织”。而《DocBook：The Definitive Guide》解释了DTD中定义的“标记的含义到底是什么，软件应如何处理这些标记”，可以在http://www.docbook.org/tdg/en/中找到它。

1.5.5. XSL

可 扩展样式单语言（eXtensible Stylesheet Language）。包括两个部分：XSLT（ XSL Transformation）和FO（Formatting Object），这两者本身也是基于XML的规范。XSLT文件的后缀名一般为xsl，它描述如何对使用一套标记的XML文件进行转换生成别的格式的文 件，例如html、采用另一套标记的XML文件等等。FO文件的后缀名一般为fo，它描述如何显示文本，类似于html文件，但是它描述的格式更加丰富。

1.5.6. PDF

便携文档格式（Portable Document Format）。Adobe公司推出的，特点是任何可以 打印的文档都可以转化为此种文件格式。是互联网上传递文档事实上的标准。