構建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公司推出的，特點是任何可以 打印的文檔都可以轉化爲此種文件格式。是互聯網上傳遞文檔事實上的標準。