DocBook 的 Line Numbering 和 Code Highlighting

最近在製作 DocBook 文件時，遇到了「Line Numbering」和「Code Highlighting」問題，花了三天的時間終於解決，特別筆記在此紀錄一下解決的步驟。

首先，說一下前置作業：

1. 取得「docbook-xsl」。從 SourceForge下載「docbook-xsl-1.?.?.zip」，請特別留意版本號！不要太新、也不要太舊，網址在：http://sourceforge.net/projects/docbook/files/docbook-xsl/ ，我自己下載的是 「docbook-xsl-1.78.1.zip」。
2. 取得 XSLT 1.0 proccessor —— Saxon 或 Xalan，也一樣請留意版本號：
1. Saxon：請從 http://saxon.sourceforge.net/#F6.5.5 下載，取得 Saxon 6.5.5 就好了，我自己下載的是「saxon6-5-5.zip」。
2. Xalan：它被包在 Xerces2 Java 裡了，請從 http://xerces.apache.org/mirrors.cgi#binary
   下載 Binary 和 Tools，我自己下載的是「Xerces-J-bin.2.11.0.zip」和「Xerces-J-tools.2.11.0.zip」。
3. 取得 XSLT Syntax Highlight  —— xslthl，請從 http://sourceforge.net/projects/xslthl/ 下載，我自己下載的是「xslthl-2.1.0-dist.zip」。
4. 下載完上述檔案後，把它們解開在「D:\docbook」下方，也就是像這樣：
• docbook-xsl-1.78.1\
• saxon6-5-5\
• tools\
• xerces-2_11_0\
• xslthl-2.1.0\
5. 閱讀「DocBook XSL: The Complete Guide 4th Edition」的這兩篇：
1. Chapter 27. Program listings - Line numbering
2. Chapter 27. Program listings - Syntax highlighting

此外，要提醒的是：只有「Saxon」和「Xalan」才支援「Line Numbering」和「Code Highlighting」這兩項功能， xmltproc 並不支援喔！

接著，請準備好以下三個檔案（其內容列於本文底部），並盡量都使用一樣的編碼（如 UTF-8），也放到 D:\docbook  下面：

1. my_article.xml：DocBook 文件。
2. my_article.xsl：DocBook XSL 樣式檔。
3. my_code.java：一段 Java 程式碼。

然後，在 D:\docbook 下執行以下指令，就可將 DocBook 格式轉換為 HTML 格式了：

1. 如果你是用 Saxon 的話：

   java -cp "D:\docbook\xslthl-2.1.0\xslthl-2.1.0.jar;D:\docbook\saxon6-5-5\saxon.jar;D:\docbook\docbook-xsl-1.78.1\extensions\saxon65.jar" -Dxslthl.config="file:///D:/docbook/docbook-xsl-1.78.1/highlighting/xslthl-config.xml" com.icl.saxon.StyleSheet -o output\my_aritcle.html my_article.xml my_article.xsl use.extensions=1
   

2. 如果你是用 Xalan 的話：

   java -cp "D:\docbook\xslthl-2.1.0\xslthl-2.1.0.jar;D:\docbook\tools\xalan.jar;D:\docbook\xerces-2_11_0\xml-apis.jar;D:\docbook\xerces-2_11_0\xercesImpl.jar;D:\docbook\docbook-xsl-1.78.1\extensions\xalan27.jar" -Dxslthl.config="file:///D:/docbook/docbook-xsl-1.78.1/highlighting/xslthl-config.xml" org.apache.xalan.xslt.Process -OUT output\my_article.html -IN my_article.xml -XSL my_article.xsl -L -PARAM use.extensions 1
   

轉換完的 my_article.html 內容就像下面這個樣子：




加上行號與程式碼 highlight 的 my_article.html

最後，我發現一個問題，就是 Xalan 在轉換外部檔案「my_code.java」時，即使有在<textdata> 標籤加上「encoding="UTF-8"」屬性，中文（在註解的位置）會變成亂碼，但 Saxon 就不會。

至於其原因，我暫時沒時間去探究。因此，如果你也遇到同樣的問題，建議就先改用 Saxon 吧！（或者幫忙查一下原因，並回饋給小弟，:-p）

前面所提到的三個檔案內容如下：

1. my_article.xml：

<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article lang="zh_tw">
  <title>快來測試 Line Numbering 和 Code Highlighting 的功能吧！</title>
  <sect1>
    <title>my_code.java</title>
      <programlisting linenumbering="numbered" startinglinenumber="1" language="java"><?dbhtml linenumbering.everyNth="1" linenumbering.separator=" " linenumbering.width="4"?><?dbfo linenumbering.everyNth="1" linenumbering.separator=" " linenumbering.width="4"?><textobject><textdata fileref="file:///D:/docbook/my_code.java" encoding="UTF-8" /></textobject></programlisting>        
  </sect1>
</article>

2.  my_article.xsl：

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                xmlns:saxon="http://icl.com/saxon"
                extension-element-prefixes="saxon" 
                version='1.0'>

<xsl:import href="file:///D:/docbook/docbook-xsl-1.78.1/html/docbook.xsl"/>
<xsl:import href="file:///D:/docbook/docbook-xsl-1.78.1/html/highlight.xsl"/>

<xsl:output method="html" 
            encoding="UTF-8"
            indent="yes"
            saxon:character-representation="native;decimal"/>
<!--=====================================​=======================================
Code Line Numbering & Highlighting Global Settings
====================================================​=========================-->
<xsl:param name="linenumbering.extension" select="1"></xsl:param>
<xsl:param name="linenumbering.everyNth">1</xsl:param>
<xsl:param name="linenumbering.width">4</xsl:param>
<xsl:param name="linenumbering.separator"><xsl:text> </xsl:text></xsl:param>
<xsl:param name="highlight.source" select="1"></xsl:param>
</xsl:stylesheet>

3. my_code.java：

/**
 * 使用「Adapter」Design Pattern 
 */
abstract class HumanWorkerAdpater implements IWorker {
   public void work();
   public void eat();
}
abstract class RobotWorker implements IWorker {
   public void work();
}
IWoker HumanWorker = new HumanWorkerAdpater() {
   public work() {
      // working....
   }
   public eat() {
      // eating....
   }
}
IWoker RobotWorker = new RobotWorkerAdpater() {
   public work() {
      // working....
   }
}