在本系列前三篇文章中,我論述了 XML/RDF 詞彙表 DOAP 的開發——DOAP 用於描述開放原始碼專案及相關資源。透過 DOAP,軟體維護人員不必再到多個網站重複註冊自己的程式;他們只需給出一個 DOAP 描述的 URL 即可。隨著越來越多應用程式成為「DOAP 感知」的工具,參與與管理開放原始碼專案將開啟全新的可能性。
為達成這些目標,除了建立詞彙表本身,還有更多事情要做,這一點很重要。在這篇總結性的文章裡,我從文件、工具與社群三個層面,考察推行 DOAP 所需要具備的條件。
為了喚起你的記憶,清單 1 展示了一個用於 DOAP 專案本身的精簡 DOAP 檔。
清單 1. DOAP 專案本身的簡單 DOAP 描述
<Project xmlns="https://usefulinc.com/ns/doap#"
xmlns:rdf="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:foaf="https://xmlns.com/foaf/0.1/">
<name>DOAP</name>
<homepage rdf:resource="https://usefulinc.com/doap" />
<created>2004-05-04</created>
<shortdesc xml:lang="en">
Tools and vocabulary for describing community-based
software projects.
</shortdesc>
<description xml:lang="en">
DOAP (Description of a Project) is an RDF vocabulary and
associated set of tools for describing community-based software
projects. It is intended to be an interchange vocabulary for
software directory sites, and to allow the decentralized
expression of involvement in a project.
</description>
<maintainer>
<foaf:Person>
<foaf:name>Edd Dumbill</foaf:name>
<foaf:homepage rdf:resource="https://usefulinc.com/edd" />
</foaf:Person>
</maintainer>
</Project>
DOAP 使用者最先、最基本的需求,是取得該資料的一個「使用者友善檢視」。如果沒有其他編輯機制,那麼使用者只能手動編輯檔案,再用檢視器檢查結果——很多網站至今仍在用這種古老而公認有問題的方式來建立內容。建立檢視器最快的做法,或許是撰寫一份 XSLT 樣式表,把傳入的 RDF/XML 轉換成 HTML。
然而,DOAP 不僅僅是一個 XML 詞彙表,也就是說,採用 XSLT 並不是一個輕率的決定。檢視器能服務的不止一個目的:它不僅提供 DOAP 資料的檢視,同時也是 DOAP 處理應用程式的第一個範例。因此,初次接觸 DOAP 的實作者常拿它當參考。基於這個理由,如果 DOAP 檢視器本身就是一個「RDF 感知」的應用程式,會有幫助得多。
為了建立這個檢視器,我使用 Redland RDF Application 函式庫,把 DOAP 檔讀進一個駐留於記憶體中的 RDF 儲存庫,再從該儲存庫把資料萃取成 XML,最後用 XSLT 格式化這份 XML。這種中間 XML 表示可以轉換成伺服器端應用程式上的 HTML,也可用來驅動客戶端 DOAP 檢視器的圖形介面。圖 1 展示了檢視器轉換後的 HTML 輸出。
圖 1. 轉換後的 DOAP 輸出

建立這個檢視器時,我使用了來自 Redland 的 Mono/.Net 繫結(請參閱「參考資料」)。清單 2 的程式碼片段展示了一個迴圈,用來處理 DOAP 檔中的每個專案(通常只有一個),並把資料輸出到 XML 文件中由 <project> 元素框起的內容。rdf["type"] 與 doap["Project"] 這兩個變數,是帶有 URI 的資源節點的快捷方式,分別對應 RDF 與 DOAP 模式中的術語。
清單 2. 用於從 DOAP 檔中萃取專案的 Redland C# 程式碼片段
foreach (Node proj in model.GetSources(rdf["type"], doap["Project"])) {
w.WriteStartElement(null, "project", null);
Node name = model.GetTarget(proj, doap["name"]);
w.WriteStartElement("name");
w.WriteString(name.Literal);
w.WriteEndElement();
...
w.WriteEndElement();
}
建立 DOAP 檢視器的另一個有趣選項,是利用 Mozilla 網頁瀏覽器中的 RDF 呈現支援,打造一個基於 XUL 的 DOAP 檢視器。這種做法可能催生出一款可擴充於瀏覽器(例如 Firefox)內的構想。
驗證 DOAP 檔的能力,是處理這類檔案時不可或缺的一環。無論是 DOAP 的建立還是使用,驗證都很有用。對建立者而言,無論他們是手寫 DOAP 還是透過工具輸出 DOAP,驗證程式都能幫助他們與規範保持一致;對 DOAP 的消費者而言,驗證更是必須——以確保軟體不去處理無效資料。
最基本的驗證,只是對「輸入檔是否滿足規範」這類問題回報 yes 或 no。更有幫助的驗證程式,則能回報錯誤並給出建議。或許最著名的驗證程式莫過於 W3C HTML Validator(請參閱「參考資料」),它能回傳各種提示,幫助改善網站與 W3C 規範的一致性。
因為 DOAP 是 RDF/XML,我們可以在多個層次上對它進行驗證:
傳統上,純 XML 驗證技術只能做到「語法驗證」——也就是檢查元素與屬性的存在與否,以及它們的順序。這種驗證雖能攔下不少錯誤,但對於「需要進行資料處理才能判斷是否寫出了語法正確卻不合情理的內容」這類場景,就幫不上忙了。不過,某些語意約束可以表達為語法約束。舉例來說,一條 DOAP 需求規定「必須有一個 homepage 屬性」,那你就能用一個 XML 模式來攔下這類錯誤。
用 XML 模式驗證 RDF 的問題在於:RDF 的 XML 語法非常靈活,表達同樣的東西可以有好幾種寫法。實際上,用 W3C XML Schema 來驗證 RDF 是不可能的。相對地,透過一個 RDF 解析器(例如 Redland 的 raptor)來跑一遍 RDF、檢查其 RDF 合法性,反而更容易。一旦確認傳入的 DOAP 檔是合法 RDF,就能套用一系列語意測試來判斷該檔其餘部分的品質。
只要人人都能使用 RDF 處理工具,或者只要你願意提供免費的網路服務來驗證 DOAP,這種策略就能運作良好。不過,你也可以「犧牲」RDF 的部分語法靈活性,換取更大的普遍性——提供一個 XML 模式,完成驗證過程的前 70%,並用語法方法驗證一定程度的語意完整性。如此一來,再加上一點常識,就足以滿足很多人的需求了。
按照以上思路,我為 DOAP 的「受限 RDF/XML 語法版本」構造了一個 RELAX NG 模式。請注意,該模式不會驗證所有的 DOAP 檔,但凡是它能驗證通過的檔案,肯定是 DOAP 應用程式能處理的。清單 3 展示了以 RELAX NG Compact 語法寫成的模式。
清單 3. 用於 DOAP 受限 XML 設定檔的 RELAX NG 模式
default namespace = "https://usefulinc.com/ns/doap#"
namespace foaf = "https://xmlns.com/foaf/0.1/"
namespace rdf = "https://www.w3.org/1999/02/22-rdf-syntax-ns#"
namespace rdfs = "https://www.w3.org/2000/01/rdf-schema#"
grammar {
rdf-resource = attribute rdf:resource { text }
xml-lang = attribute xml:lang { text }
literal = xml-lang?, text
Person-element = element foaf:Person {
element foaf:name { literal }
& (
element foaf:homepage { rdf-resource } |
element foaf:mbox { rdf-resource } |
element foaf:mbox_sha1sum { text }
)+ &
element rdfs:seeAlso { rdf-resource}*
}
cvs-repository = element CVSRepository {
element anon-root { text },
element module { text },
element browse { rdf-resource }?
}
svn-repository = element SVNRepository {
element location { rdf-resource },
element browse { rdf-resource }?
}
bk-repository = element BKRepository {
element location { rdf-resource },
element module { text },
element browse { rdf-resource }?
}
arch-repository = element ArchRepository {
element location { rdf-resource },
element module { text },
element browse { rdf-resource }?
}
start = element Project {
element name { literal } &
element homepage { rdf-resource } &
element old-homepage { rdf-resource }* &
element created { text } &
element shortdesc { literal }+ &
element description { literal }+ &
element mailing-list { rdf-resource }* &
element maintainer { Person-element }+ &
element developer { Person-element }* &
element documenter { Person-element }* &
element translator { Person-element }* &
element tester { Person-element }* &
element helper { Person-element }* &
element category { rdf-resource }* &
element release {
element Version {
element name { text },
element created { text },
element revision { text }
}
}* &
element license { rdf-resource }* &
element download-page { rdf-resource }? &
element download-mirror { rdf-resource }* &
element repository { ( cvs-repository | svn-repository
| bk-repository | arch-repository ) }* &
element bug-database { rdf-resource }? &
element screenshots { rdf-resource }* &
element wiki { rdf-resource }* &
element programming-language { text }* &
element os { text }*
}
}
構造這個模式還有一個非常好用的附帶成果:現在你可以用 XML 編輯工具來編寫合法的 DOAP 檔。圖 2 展示了用 Emacs 的 nxml 模式(James Clark 開發)編輯 DOAP 自身描述的情形。nXML 模式使用 RELAX NG Compact 模式,圖中可以看到帶有底線的驗證錯誤提示。在手寫層次上,「犧牲部分語法表達能力、換取編輯工具支援」的取捨是值得的。
圖 2. 以 nXML 模式編輯 DOAP 檔的 Emacs

透過模式進行驗證,能同時確保 XML 的格式良好性與一定的語意完整性。然而這還不夠,我們仍得借助 RDF 處理來完成驗證流程剩下的步驟。這些步驟可能包括:檢查所給的許可證 URI、看 DOAP 工具是否承認它們,以及在適當處對文字進行拼字檢查等等。
我已著手開發一款驗證程式,它會像檢視器應用程式那樣輸出 XML。如此一來,驗證程式碼便能同時服務於網頁 GUI 與客戶端 GUI 應用程式。這款驗證程式執行四個層次的檢查:
清單 4 展示了驗證程式的兩次範例執行結果,分別攔下了 XML 格式良好性與語法有效性錯誤。由於 <Test> 元素中的測試名稱可作索引,因此能對應到更詳細的解釋與建議。
清單 4. 驗證程式輸出
<Problems>
<Problem>
<Test>ParseXML</Test>
<Title>Not well-formed XML</Title>
<Description>DOAP files must follow the rules of XML syntax.</Description>
<Detail>unmatched closing element: expected name but found Project
Line 27, position 10.</Detail>
</Problem>
</Problems>
<Problems>
<Problem>
<Test>Doap.Tests.XML.RelaxValidate</Test>
<Title>XML syntax validation</Title>
<Description>This test checks to see that the DOAP file validates
against a restricted XML syntax, which guarantees its validity.</Description>
<Detail>Invalid start tag found. LocalName = Person, NS =
https://xmlns.com/foaf/0.1/. line 26, column 3</Detail>
</Problem>
</Problems>
你可以在 DOAP 首頁取得這款驗證程式的程式碼(請參閱「參考資料」),網路上也將建立一個公開存取的實例。確保 DOAP 的採用者能在較早階段檢查其輸出,這一點很重要。此外,我建議所有 DOAP 處理應用程式都先驗證輸入——至少要用 RELAX NG 模式——以讓網路上 DOAP 內容的品質出現最少的異常。只需看看網路上 RSS feed 因寬鬆解析而招致的混亂,就足以讓你相信「一定程度的嚴格」是有益的。為提供幫助,驗證程式與檢視器的程式碼將以寬鬆的開放原始碼授權發布,讓人能放心地把它們整合進其他程式。
那麼,究竟該如何建立 DOAP 檔?最初的採用者會在文字編輯器中手寫該檔,再靠驗證程式與 XML 模式檔一起確保內容無誤。如前所述,遵循模式的 DOAP 檔會失去一些 RDF 表達能力,但對大多數人而言,這點損失無關痛癢。
大多數建立 DOAP 檔的人,其實對 DOAP 詞彙表本身並不感興趣。他們只想要最終的功能,好讓自己也能透過軟體註冊來登記專案。他們很可能找一個範例檔,再改造它納入自己的資料。正因如此,確保能提供足夠的教學材料、優良範例與驗證工具,以免糟糕的範例蔓延開來,就顯得格外關鍵。一旦劣質的複製貼上流傳出去,其蔓延之勢便難以遏止。
DOAP 建立流程中的「複製貼上」階段,應該盡可能縮短。你可以透過引入一定程度的工具支援來做到這點。大多數軟體開發者已在用某種打包與設定系統,這些系統至少包含了生成 DOAP 檔所需的部分元資料。這類系統包括用於 C 語言的 GNU Autoconf、Python 的 distutils、Perl 的 MakeMaker 檔等等。如果開發者所用的系統有一套簡便的 DOAP 生成方案,那麼取得 DOAP 檔的機會就會大增。
此外,你也可以採用不同的「有向導」的建立方式:
這裡雖然建立了 DOAP,但應達到兩個重要目標:DOAP 要盡可能易於開發者使用,其輸出的內容也要盡可能豐富且高品質。可用資料的普遍性和品質,都是 DOAP 前景的關鍵所在。
即使有了工具,若沒有集結在 DOAP 專案周圍的社群,它也不太可能長久。推廣新技術時,溝通至高無上。像約定規則一樣清晰地表述專案目標,這一點很重要。溝通中最基本的一步,是建立一個網站,收錄所有相關文件,並指向專案中可用的各項資源。
圖 3 展示了 DOAP 首頁的螢幕截圖。請注意兩個重點:清楚的導覽與新聞。靜態網站常給人沉悶的印象,而定期更新新聞則能滿足「通知使用者」與「讓專案看起來充滿活力」的雙重需求。如今,為專案新聞提供 RSS feed 也是必須的。
圖 3. DOAP 首頁的螢幕截圖

雖然不必一開始就回答所有想得到的問題,但專案網站添加文件與教學材料的速度,應盡可能快。How-to 問題與 FAQ,往往就出現在新採用者一眼可見的位置。
然而,溝通不會總是單向的。我們需要一個論壇,讓有興趣使用與採用 DOAP 的人能彼此碰面、互相提問。對於開放原始碼專案,郵件列表一直是最成功的媒介,而 DOAP 確實也有這樣的郵件列表(請參閱「參考資料」)。隨著社群成長,使用 DOAP 的第三方能在那裡宣布自己的產品與成果,藉此推動它們被採用並得到進一步發展。
最後,必須向那些可能感興趣的人展示這個專案,讓它植根於群眾。除了在 XML 會議上展示 DOAP 之外,我還會在各種郵件列表中宣傳它,並向開放原始碼領域的一些關鍵人物推廣。
雖然本文是本系列關於 DOAP 建立的四部曲中的最後一篇,但它同時標誌著這個專案在公眾眼前的生命週期正式開始。我相信,DOAP 在「善用以 Web 技術語意上的威力」與「保留足夠的『Webby』以贏得大規模支持」這兩者之間,將取得一個適當的平衡。幾個月後,我會在本專欄回訪這個專案,看看這些決策在中長期內表現如何。