XML 是一種機制:它用標記把資料中不同層級的部分層層包住,藉此標示出資料集裡的結構,而這些標記也說明了它們所界定的那段文字在整體結構中扮演什麼角色。這些文字標記——又叫標記、標籤,或者更精確地說是「元素」——必須符合預先定義的結構。該結構因資料類型而異,一般稱為 Schema,早期則叫 DTD。Schema 本身以 XML 寫成,DTD 則擁有自己的語法。
標記語言乃至 XML 本身的概念,其實都源自文件生成系統。在那類系統裡,文字檔含有處理指令或用來標示文件各部分的結構標識符;這些檔案隨後交由軟體處理,而軟體知道如何解讀指令,以及如何針對特定輸出裝置產生格式化結果。標記語言在文件處理上的演進,一路伴隨的是抽象程度的提高。
早期標記語言採用格式化指令,規格的是字體、字級變化這類低層細節,之後很快演化為更普遍性、能標示邏輯與結構組成的標記,例如醒目標示的術語、段落、清單、標題等。
較現代的標記語言,如通用標記語言標準(SGML)與 XML,則讓書、章、節這類更抽象化的結構標記更容易被大眾理解與接受。SGML 引進了 DTD 概念,使得 SGML 工具得以驗證某一批標記元素在特定上下文中是否合規,而這些元素本來就該出現在某一類文件的結構裡。
很明顯,XML 把標記從文件領域中解放出來,將使用範圍擴展到任何型式的結構化資料,同時也提高了對「格式良好」的要求——每個元素都必須具備成對的起始與結束標籤。雖然 XML 規範最初的版本從 SGML 繼承了 DTD,隨後的版本卻引入了 Schema 概念來定義 XML 資料的結構。Schema 與 DTD 大致相同,只是 Schema 本身也用 XML 撰寫,並以更靈活的模型界定有效元素、元素的資料型別,以及這些元素可以出現在文件中哪些上下文裡。
把文件的「內容」(文件確切包含的文字與資料)和文件的「呈現」(文件在特定輸出格式或特定裝置上顯示的方式)分開,正是現代標記語言、特別是 SGML 與 XML 背後的核心概念。
儘管 XML 讓針對特定應用或產業設計 DTD 與 Schema 變得容易,它在文件領域真正的優勢,其實在於有大量現成的標準 DTD 與 Schema 可用。其中為人熟知的包括 DocBook、Text Encoding Initiative(TEI)、XHTML,以及 Darwin Information Typing Architecture(DITA)所採用的那些。本文聚焦 DocBook——最知名、也被最廣泛用於文件標記的 Schema。
由於核心精神就是把內容與呈現分離,XML 本質上是一套「寫一次、用多次」的機制,因此要在多份文件中重用資訊,或針對特定輸出格式與讀者群體調整呈現,都變得容易。系列中的另一篇文章會深入談這些主題。
在本文脈絡下,「發布」指的是把一份含 DocBook 標記的文字檔,轉換成一個或多個特定格式的輸出檔,例如 HTML、Adobe 的可攜式文件格式(PDF)、PostScript、微軟的 RTF 等。從 XML 文件產生 HTML 只需一步,而且單一應用程式即可完成;若要產生 PDF、PostScript 或 RTF,則再多一個步驟:
先解析文件內全部內容或 DocBook 文件中的外部引用,再用 XSL 樣式表產生該文件的 Formatting Object(FO)格式版本。
接著,把 DocBook 文件的 FO 版本轉換成對應格式的輸出檔。
能完成這些轉換的開源工具很多,本文只介紹筆者認為最實用、最靈活的三種,如表 1。
表 1. 本文涵蓋的開源轉換工具
| 工具 | 說明 |
|---|---|
| fop | 把 XML 輸入轉換成 PDF、PostScript、RTF 等輸出的 Java 應用程式,執行前系統必須安裝 Java Virtual Machine(JVM)。 |
| XMLto | 一支簡單的 Bourne-Again shell 腳本,加上一組能從 XML 輸入產生 HTML 輸出的相關樣式表;此外還需要 GNU find、mktemp 等開源工具。 |
| xsltproc | 編譯型應用程式,能搭配 XSL 樣式表把 XML 輸入轉成另一種 XML 輸出格式,使用前需安裝 DocBook XSL 樣式表。只要樣式表齊備,fop 也能直接吃 DocBook XML;但若輸入檔有問題,另外拉一支獨立的 XML 到 FO 轉換器(如 xsltproc)會讓除錯簡單得多。 |
以下小節說明如何下載與安裝這些應用程式;之後的小節會提供一支 shell 腳本,把前面內容整合起來,並方便指定輸出格式、更換樣式表等。
前一節提到的軟體與樣式表,取得方式請見參考資料。
注意:若使用 Linux 系統,XMLto 與 xsltproc 通常已隨系統安裝,或至少能在該發行版的套件庫或安裝媒體中找到。此外還需要一個 JVM 來跑 fop——建議用 GNU Compiler for Java,因為它提供了 fop 所需的完整功能。
許多這類套件會把軟體裝到系統指定的位置,好讓套件管理工具監控並隨時更新;但 XSL 樣式表與 Apache Formatting Objects Processor(FOP)不適用這種方式,它們是以壓縮檔形式下載,解開後有一個頂層目錄與多個子目錄。
若要統一文件解析與格式化環境,最好把沒有寫死路徑名稱的套件裝到一個原本不存在的目錄(例如 /home/doc)裡。這樣就有一個獨立位置,可以集中查找相關檔案、視需要升級軟體,也能收納自己開發或收藏的其他工具與樣式表。
要讓前面討論的套件與後面提供的統一腳本協同運作,必須以 UNIX 或 Linux 的 root 使用者身分執行列表 1 的命令。
列表 1. 讓 fop、XMLto、xsltproc 能與統一腳本協作的命令
mkdir /home/doc
mkdir /home/doc/bin
mkdir /home/doc/external
mkdir /home/doc/external/SAVE
mkdir /home/doc/XSL
下載 FOP 與 DocBook XSL 樣式表的壓縮檔(.zip)後,把它們放進 /home/doc/external,切到該目錄,再用列表 2 的命令解壓。
列表 2. 解壓 FOP 與 DocBook XSL 樣式表的命令
cd /home/doc/external
unzip fop-0.95-bin.zip
unzip docbook-xsl-1.74.3.zip
chmod 755 fop-0.95/fop
要確認必備套件是否都裝好了,可執行列表 3 的命令。
列表 3. 驗證套件是否安裝完成的命令
XMLto --version
xsltproc --version
Java --version
若 XMLto、xsltproc 與 JVM 都已正確安裝且位於執行路徑中,上述每道命令都會回報該程式的版本資訊。
把 DocBook 發布所需軟體都裝好之後,剩下的難題只是「要記住所有必填選項並按正確順序執行」。與其死記,不如寫一支包装腳本把流程串起來,順便對發布過程做一些控制,例如列表 4、5、6 所示。
這支腳本依傳入參數產生 HTML、PDF 或 RTF 輸出。產生 PDF/RTF 時採兩步流程:先跑 xsltproc,用 driverfile 變數裡指定的 XSL 樣式表套用轉換規則,從 DocBook 輸入產生 FO 檔;再由 fop 把 FO 檔轉成目標格式。兩個步驟的訊息分別寫入 xsltproc.out 與 fop.out,腳本靠這些中間檔監視轉換過程,出問題時也能取得除錯線索。
列表 4 是腳本的開頭,定義了使用說明訊息(在沒有參數或參數數量錯誤時顯示),設定若干預設值,再用標準 Bash shell 的 getopt 函式解析命令列參數(實際輸出的使用訊息見列表 7)。
列表 4. 包装腳本的起始部分
#! /bin/bash
#
# Simple script to generate Html output from a DocBook file using
# XMLto, or to generate PDF/RTF output by generating a fo file,
# and then using apache's FOP to format that.
#
# wvh@vonhagen.org
#
function usage {
echo "Usage: $0 [OPTIONS] document-name"
echo " -D : produce draft mode document"
echo " -d : use specifIEd xsl driver (requires name of XSL file) "
echo " -h : generate Html output (requires output directory name)"
echo " -k : attempt PDF generation even if xsltproc errors were encountered"
echo " -n : suppress TOC"
echo " -r : produce RTF output rather than PDF"
exit 1
}
dir=`dirname $0`
XSLTPROC="xsltproc"
PATH=$dir/../external/fop-0.95:${PATH}
if [ $# == 0 ] ; then
usage
exit
fi
driverfile="$dir/../external/docbook-xsl-1.74.3/fo/docbook.xsl"
# driverfile="$dir/../XSL/generic-print-driver.xsl"
draft="no"
keepgoing="no"
RTFoutput="no"
Htmloutput="no"
while getopts ":d:h:Dknr" opt
do
case $opt in
d )
driverfile=$OPTARG
echo "Using driver file: $driverfile"
if [ ! -f $driverfile ] ; then
echo " Driver file not found"
exit 1
fi
;;
D )
draft="yes"
echo "Producing Draft Mode Document"
;;
h )
Htmldir=$OPTARG
Htmloutput="yes"
echo "Producing HTML output to $Htmldir instead of PDF"
if [ -d $Htmldir ] ; then
echo " Output directory $Htmldir already exists"
exit 1
fi
;;
k )
keepgoing="yes"
echo "Will not stop if errors are encountered"
;;
n )
notoc="--stringparam generate.toc ''"
echo "Suppressing TOC..."
;;
r )
RTFoutput="yes"
echo "Producing RTF output rather than PDF"
;;
\? )
usage
exit 1;;
esac
done
shift $(($OPTIND - 1))
if [ ! -f $1 ] ; then
echo " Input file $1 not found - exiting."
exit
fi
列表 5 這段的作用是:要產生 HTML 時改用 XMLto;要產生 PDF 或 RTF 時,用 xsltproc 從輸入 XML 檔建出 FO 輸出。XML 到 FO 這一步的輸出寫進名為 xsltproc.out 的暫存檔,若 xsltproc 在輸入檔遇到任何錯誤,這個檔案能大幅簡化除錯;一旦偵測到錯誤,腳本會在產生 FO 檔後結束,此時查看 xsltproc.out 通常就能定位並解決問題。與列表 4 一致,也可以加上 -k 選項強制腳本在偵測到錯誤時仍繼續。
列表 5. 從輸入 XML 檔產生 FO 輸出
doc_base=`basename $1 .XML`
echo "Processing base name: $doc_base"
if [ x$Htmloutput != "xno" ] ; then
XMLto -o $HTMLdir Html $1
exit
fi
echo " Generating FO file: $doc_base.fo"
$XSLTPROC --output $doc_base".fo" \
--stringparam draft.mode $draft \
--stringparam fop1.extensions 1 \
--xinclude \
$notoc \
$driverfile \
$1 1> xsltproc.out 2> xsltproc.out
probs=`grep -i error xsltproc.out | wc -l | sed -e 's; ;;g'`
if [ x$probs != "x0" ] ; then
echo ""
echo "PROBLEMS:"
echo ""
cat xsltproc.out
echo ""
if [ x$keepgoing = "xno" ] ; then
exit
fi
fi
echo " Fixing FO file references to system images..."
cat $doc_base".fo" | sed -e "s;\"url(\.\./external/;\"url($dir/\.\./external/;g" > $$
mv $$ $doc_base".fo"
列表 6 是腳本的最後一段,用 fop 從 FO 檔產生 PDF 或 RTF。與 XML 到 FO 那步類似,FO 到 PDF/RTF 的輸出寫入 fop.out;當 fop 在 FO 檔遇到錯誤時,這個檔案同樣能協助除錯。若 PDF/RTF 產生失敗,檢查 fop.out 通常就能找到線索。與列表 4 一樣,-k 選項可讓腳本在 xsltproc 階段偵測到錯誤時仍強行前進。
列表 6. 從 FO 檔產生 PDF 或 RTF 輸出
if [ x$RTFoutput = "xno" ] ; then
echo " Generating PDF file: $doc_base"".pdf"
fop -fo $doc_base".fo" -pdf $doc_base".pdf" 1> fop.out 2> fop.out
else
echo " Generating RTF file: $doc_base"".rtf"
fop -fo $doc_base".fo" -rtf $doc_base".rtf" 1> fop.out 2> fop.out
fi
probs=`grep -i Exception fop.out | wc -l | sed -e 's; ;;g'`
if [ x$probs != "x0" ] ; then
echo ""
echo "EXCEPTION OCCURRED DURING PROCESSING:"
echo ""
cat fop.out
echo ""
fi
這支名為 xml-format.sh 的範例腳本可從下載處取得(見 xml-format.zip)。安裝方式是把 XML-format.sh 解壓到 /home/doc/bin,再用下列命令讓它可執行:
chmod 755 /home/doc/bin/XML-format.sh
最後,確定 /home/doc/bin 已在執行路徑中:編輯 ~/.bashrc,在檔尾加上下面這行(也可直接在 shell 提示符執行):
export PATH=/home/doc/bin:${PATH}
若把這行加進 ~/.bashrc,請在目前登入工作階段載入該檔,讓改動立刻生效:
source ~/.bashrc
不帶參數執行 XML-format.sh,會印出使用摘要,如列表 7 所示。
列表 7. 不帶參數執行 XML-format.sh 的輸出
Usage: XML-format.sh [OPTIONS] document-name
-D : produce draft mode document
-d : use specifIEd xsl driver (requires name of XSL file)
-h : generate Html output (requires output directory name)
-k : attempt PDF generation even if xsltproc errors were encountered
-n : suppress TOC
-r : produce RTF output rather than PDF
要產生 DocBook 文件的 PDF 版,直接把文件名稱傳給腳本即可:
xml-format.sh sample-document.XML
要產生 HTML 版,必須加上 -h 並指定輸出目錄。例如相對目前工作目錄,把結果寫進 HTML-output 目錄:
XML-format.sh -h Html-output sample-document.XML
XML-format.sh 預設採用 DocBook XSL 套件內附的輸出樣式表。若想客製,請建立自己的樣式表:先載入預設的 DocBook XSL 樣式表,再覆寫想調整的特定參數。generic-print-driver.xsl 就是這樣一個客製層範例(見 generic-print-driver.zip)。
要讓腳本改用別的樣式表,可用 -d 選項指定該樣式表的路徑(絕對或相對皆可),或直接修改腳本裡 driverfile 變數的值。範例腳本中已放好一行可改用 generic-print-driver.xsl 的設定,只要把原本 driverfile 的那行註解掉、並取消下一行的註解即可。
XML 強大又靈活,加上現成的多組標準,以及處理與轉換 XML 文件的豐富工具,讓「自建一套工具鏈、從 XML 文件生成各種格式輸出」變得相當容易。市面上雖有不少商業工具可編輯與格式化 XML 文件,但自己動手組一套不僅成本更低,也能讓你真正理解整個流程。