《XML Hacks》是一本談 XML 技巧與竅門的書。它是一份很有用的參考資料,涵蓋範圍相當廣;但其中有些素材若能再展開或改寫,效果會更好。Uche Ogbuji 在本篇給出他的實用報告。
上一期我評了 Elliotte Rusty Harold 的《Effective XML》——那是一本所有 XML 專業人員都該讀的好書。這一次我把目光轉向另一本實用取向的 XML 書:Michael Fitzgerald 編纂的《XML Hacks》(O'Reilly and Associates,2004)。它的跨度很大,從入門基礎、中階與高階的設計與實作技術,一路到工具的用法技巧。本專欄與其他 developerWorks 文章的讀者,大概更希望我聚焦在 XML 設計與 XML 詞彙表的問題上;《XML Hacks》談的更多是實作細節與工具操作,但這些同樣重要。以下是我把書中內容拿到實際專案裡用過之後的一些觀察。和寫《Effective XML》那篇一樣,本文不是書評,而是受這本書啟發想到的一些東西——寫給還不具備這些知識的讀者。
書中第 26 章〈Include External Documents with XInclude〉說明了如何以類似 XML 內建外部已解析實體的方式使用 XInclude。書裡的範例文件插入了一份由 HTTP URL 指定的外部 XML 文件。XInclude 確實為這種混合加上了一些小技巧,例如退路支援(出錯時提供替代內容),以及處理器發出 HTTP 請求時指定內容協商方式的機制。但相較於已解析實體,我認為 XInclude 最關鍵的兩個優勢是:
第二點在撰寫含程式碼或範例的 XML 文件時特別好用。假設您要寫的文件裡得放進清單 1 這段 Python 程式碼。
def game_show(contestant_guess, prices):
if prices[contestant_guess] < 1000:
print "you win!"
else:
print "you lose!"
這些程式應該在獨立檔案裡開發,這樣才能在放進文件之前先測過、確認行為符合預期。最直接的做法是把它剪貼進 XML 文件,如清單 2。
<?xml version='1.0' encoding='iso-8859-1'?>
<!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN"
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<title>On-line game show programming in Python</title>
</head>
<body>
<div class="section">
<h3>A simple example</h3>
<p>Examine the following code:</p>
<div class="code-listing">
<div class="caption">example 1</div>
<!-- paste Python code here -->
</div>
</div>
</body>
</html>
這麼做會出錯,因為 if prices[contestant_guess] < 1000: 這一行裡有一個沒有轉義的小於號。您可以手動把它改成 <,但這太累人,而且一改程式就可能引入錯誤;接著您還得同步修改外部檔案與測試檔案,最後再改剪貼進來的那份,並重新轉義回文件中。
一個解法是用 CDATA 區段,如清單 3:把程式直接貼進這個區塊,就不必再做任何轉義。
<?xml version='1.0' encoding='iso-8859-1'?>
<!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN"
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<title>On-line game show programming in Python</title>
</head>
<body>
<div class="section">
<h3>A simple example</h3>
<p>Examine the following code:</p>
<div class="code-listing">
<div class="caption">example 1</div>
<![CDATA[
<!-- paste Python code here -->
]]>
</div>
</div>
</body>
</html>
這招確實避開了轉義錯誤,但您得時時提防字串「]]>」——它估計很少出現,可一旦出現就麻煩,如清單 4。
def game_show(guesses, contestant, prices):
if prices[guesses[contestant]]>1000:
print "you win!"
else:
print "you lose!"
要在 CDATA 區段裡正確放上這一行,至少得寫成 if prices[guesses[contestant]]]]><![CDATA[>1000: 這種怪物。另外也別忘了,我這裡用的是 Python,多數情況下需要轉義的地方已經算少;若您寫的是關於 XML 的文件,手動轉義根本撐不住,而且出現「]]>」這個組合的機率還高出許多(例如 XML 範例本身可能就含 CDATA 區段)。
當然您可以自創一套方法繞過障礙,但我發現處理文章裡的程式碼最省事的做法,是用 XInclude 的 parse="text"。只要在 xi:include 元素上加這個屬性,內容就會自動當成 XML CDATA 處理,轉義交給工具完成。清單 5 就是這樣用的:
<?xml version='1.0' encoding='iso-8859-1'?>
<!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN"
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US"
xmlns:xi="https://www.w3.org/2001/XInclude"
>
<head>
<title>On-line game show programming in Python</title>
</head>
<body>
<div class="section">
<h3>A simple example</h3>
<p>Examine the following code:</p>
<div class="code-listing">
<div class="caption">example 1</div>
<xi:include href="gameshow1.py" parse="text" encoding="iso-8859-1"/>
</div>
</div>
</body>
</html>
此時 xi:include 元素會被替換成 gameshow1.py(也就是清單 1 那樣的內容)完全轉義後的文字,檔案路徑相對於該元素的基底 URI 解析。多虧 parse="text",轉義自動完成。我一律會加上 encoding 屬性(用 parse="xml" 時偶爾可以省)。我的環境裡,Python 檔通常是 iso-8859-1,XML 檔則是 utf-8,您的環境大概另有一套。
我在為 developerWorks 寫稿時用的就是這招——它要求作者以精心設計的 XML 格式交稿——可以說大幅提升了編輯速度。
另外提醒一件事:這本書用的是當時還在制訂中的 XInclude 命名空間 https://www.w3.org/2003/XInclude,但那個命名空間現在已經不存在了。在 2004 年 4 月 13 日發布的 Candidate Recommendation 裡,W3C 工作小組回到了原本的 https://www.w3.org/2001/XInclude。據我了解,多數工具只支援後者(2001)那種形式,這大概也是 W3C 決定回頭的原因;但這場命名空間的擺盪確實造成了一些混亂,作者成了無辜的受害者,我已就此向出版社提供了勘誤表。
第 37 章〈Generate an XSLT Identity Stylesheet with Relaxer〉談的是一種相當複雜的「產生恆等轉換」的方法——所謂恆等轉換,就是輸出與來源文件等價的 XML 的 XSLT 轉換。照那個做法,詞彙表裡每個元素都要有一個模板,篇幅自然龐大。這樣寫或許是為了提供一份可改造的樣本,方便往後寫更專門的轉換;但書中並沒有先給出那個簡單得多的恆等轉換——而 XSLT 規範本身,就是拿它當範例的。後一章(38)〈Pretty-Print XML Using a Generic Identity Stylesheet and Xalan〉才談到這種簡潔版本,其中包含為了整齊輸出而常見的 <xsl:output method="xml" indent="yes"/>。我的建議是:先讀第 38 章,把簡單的恆等轉換弄熟,再回頭研究第 37 章那套繁複做法。這麼做還有一個附帶好處——理解簡單的恆等轉換,是掌握幾個關鍵 XSLT 片語的敲門磚,包括把來源節點複製到輸出的 xsl:copy-of,以及幾個常見 XPath 節點測試之間的細微差別:*、@* 與 node()。
第 45 章〈Generate Multiple Output Documents with XSLT 2.0〉示範如何用 XSLT 2.0 的 xsl:result-document,在一次轉換中序列化多棵結果樹。整章寫得不錯,只有最後那句話讓我皺眉頭:
如果您仍在使用 XSLT 1.0,也還是能產生多份結果文件,但只能透過擴充功能做到,而擴充功能會因處理器而異。
這句話並不正確,而這要感謝 EXSLT——它是一套為 XSLT 1.0 處理器制訂的標準擴充集合。EXSLT 提供了 exsl:document 擴充,並獲得幾個熱門 XSLT 處理器的支援。相較於 XSLT 2.0 裡的等價機制,這個做法更簡單,在我看来也更好看(它源自 XSLT 2.0 Working Draft 早期草案中對這個特性的一項提案)。我不打算重複書中那個長例子,清單 6 是個更精簡的版本:把 XHTML 來源文件裡的每個段落元素,各自寫進一份新的結果文件。
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="https://www.w3.org/1999/XSL/Transform"
xmlns:exsl="https://exslt.org/common"
xmlns:html="https://www.w3.org/1999/xhtml"
extension-element-prefixes="exsl">
<xsl:template match="html:p">
<exsl:document href="para-{generate-id()}.xml" method="xml" indent="yes">
<xsl:copy-of select="."/>
</exsl:document>
</xsl:template>
</xsl:stylesheet>
關鍵是 exsl:document 元素:它通知處理器準備一棵新的輸出樹,通常就是開一個新檔案。href 屬性是要寫出的資源名稱,會依擴充元素所在的基底 URI 解析;我這裡用 generate-id() 函式確保每個檔名都不重複。method="xml" 與 indent="yes" 只是 xsl:output 的常見屬性,在這個擴充元素裡,任何相關屬性都能用。
書中第 58 章才介紹 EXSLT(〈Use EXSLT Extensions〉),但想扭轉「要一次產出多份結果文件,唯一簡便途徑就是轉向 XSLT 2.0」這個印象,已經太遲了。我建議您盡可能留在 XSLT 1.0,因為 XSLT 2.0 所依賴的 XPath 2.0 帶進了一些不必要的複雜性。EXSLT 幾乎把 XSLT 2.0 裡所有好用的功能都提供給了 XSLT 1.0 用戶,有些甚至更多。
《XML Hacks》是一本把許多便利技巧與竅門收攏在一起的書。但它對某些特定工具似乎帶有相當強烈、也相當不必要的偏好;加上有些地方行文不夠順暢(多人合寫的書並不罕見),以致某些章節的主旨不易看清。本文嘗試替書中幾處交代得不清楚、但實際上相當重要的地方做點補充;下一期我會再往下看一些。