级别： 中级 Edd Dumbill (edd@xml.com), 编辑兼发行人, xmlhack.com
2004 年 8 月 01 日 在这一期的
XML 观察中，Edd Dumbill 总结了用于描述开放源代码软件项目的词汇表的开发，同时考察了对于 DOAP 的成功启动必不可少的文档、工具和社区。文章中所采用的步骤源于他在开放源代码项目和词汇表方面的经验，例如 FOAF 和 RSS。
在本系列的前面三篇文章中，我论述了 XML/RDF 词汇表 DOAP 的开发，DOAP 用于描述开发源代码项目以及相关的一些资源。通过使用 DOAP，软件维护人员不再需要在多个 Web 站点注册他们的程序。相反，他们可以简单地给出 DOAP 描述的 URL。随着更多的应用程序成为 DOAP 感知的应用程序，参与和管理开放源代码项目开启了新的可能性。
为达到这些目标，除了创建词汇表外，还要做更多的事情，这一点很重要。在这篇总结性的文章中，我从文档、工具和社区这几个方面考察了采用 DOAP 所需要的一些东西。
查看 DOAP
为了唤起您的记忆，这里有一个简单的 DOAP 文件 -- 清单 1 展示了用于 DOAP 项目本身的一个很小的 DOAP 文件。
清单 1. DOAP 项目本身的简单 DOAP 描述
<Project xmlns="http://usefulinc.com/ns/doap#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:foaf="http://xmlns.com/foaf/0.1/">
<name>DOAP</name>
<homepage rdf:resource="http://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="http://usefulinc.com/edd" />
</foaf:Person>
</maintainer>
</Project>
|
DOAP 用户的最先需求也是最基本的需求是，获得该数据的一个用户友好的视图。如果不存在其他的编辑机制，那么可以手工编辑一个文件，然后使用查看器检查该文件 -- 很多 Web 站点都采用这种古老而又公认有问题的方法创建。创建查看器最快捷的方法可能是编写一个 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 Web 浏览器中的 RDF 呈现支持，并创建一个基于 XUL 的 DOAP 查看器。这种方法可能导致一种在浏览器中扩展的设想，例如 Firefox。
验证 DOAP
验证 DOAP 文件的能力是处理这些文件时必不可少的一部分。不管 DOAP 的创建还是使用，验证都是有用的。对于创建者，不管他们是手工编写 DOAP 还是通过创建工具输出 DOAP，验证程序（validator）都会保持与规范的一致性。对于 DOAP 的消费者，必需进行验证，确保软件不去处理无用的数据。
最基本的验证只是对输入文件是否满足规范这类问题报告 "yes" 或者 "no" 的过程。更有帮助的验证程序可以报告错误并给出建议。也许最著名的验证程序是 W3C HTML Validator （请参阅
参考资料），它可以返回各种帮助信息，以改善 Web 站点与 W3C 规范的一致性。
因为 DOAP 是 RDF/XML，所以我们可以在各种级别上对它进行验证：
-
XML： DOAP 必须是格式良好的 XML。
-
RDF： DOAP 必须是合法的 RDF。
-
语义： 要使文档有意义，文档必须包含足够的 DOAP 术语。例如，一个 DOAP 文件如果没有名称、描述和主页属性，那么根本没用。
传统上，纯 XML 验证技术只达到了对
语法的验证 -- 即元素和属性的存在或不存在，以及它们的顺序。虽然这种验证能捕获很多错误，但是对于需要进行数据处理以判断是否编写了不合情理而语法正确的内容这样的场景，这种验证就毫无帮助了。然而，某些语义约束可以表达为语法约束。例如，一条 DOAP 需求说，必须有一个 "homepage" 属性，那么您可以用一个 XML 模式来捕获那些错误。
使用 XML 模式验证 RDF 的问题是，RDF 有非常灵活的 XML 语法，在编写同样的东西时可以有多种方法。实际上，用 W3C XML Schema 来验证 RDF 是不可能的。而通过一个 RDF 解析器（例如 Redland 的
raptor）来运行 RDF，以检查其 RDF 合法性，这种方法要更容易一些。如果知道一个传入的 DOAP 文件是合法的 RDF，那么就可以应用一系列的语义测试来判断该文件其余部分的质量。
只要每个人都可以使用 RDF 处理工具，或者只要您愿意提供免费的 Web 服务来验证 DOAP，这种策略就可以用得很好。不过，您可以牺牲 RDF 的一些语法灵活性，以便通过提供一个 XML 模式来获得更大的普遍性，这个 XML 模式完成验证过程的前面 70%，并使用语法方法验证一定数量的语义完整性。这样，再加上一点常识，便足以满足很多人的要求了。
按照以上几条，我为 DOAP 的受限 RDF/XML 语法版本构造了一个 RELAX NG 模式。注意，该模式不会验证所有的 DOAP 文件，但是它所验证的文件肯定是 DOAP 应用程序可以处理的。清单 3 展示了 RELAX NG Compact 符号中的模式。
清单 3. 用于 DOAP 的受限 XML 配置文件的 RELAX NG 模式
default namespace = "http://usefulinc.com/ns/doap#"
namespace foaf = "http://xmlns.com/foaf/0.1/"
namespace rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
namespace rdfs = "http://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文本编辑器的 James Clark 的
nxml
模式（mode），Emacs 文本编辑器用于编辑 DOAP 本身的 DOAP 描述。
nxml 模式（mode）使用 RELAX NG
Compact 模式。注意打了下划线的有效性错误。在手工编辑（hand-authoring）级别上，失去语法的部分表达能力和获得编辑工具支持之间的折衷是值得的。
图 2. 以 nxml 模式（mode）编辑 DOAP 文件的 Emacs
通过使用模式进行验证，可以同时确保 XML 的格式良好性和一定的语义完整性。然而，这是不够的，我们还必须求助于 RDF 处理来执行验证过程剩下的步骤。这些步骤可能包括检查给出的许可 URI 以便发现 DOAP 工具是否承认它们，在适当的地方对文本进行拼写检查，等等。
我已经开始了关于基于以上几条的验证程序的工作，该验证程序
以类似于查看器应用程序的方式给出 XML 输出。这样一来，验证程序代码便可同时用于 Web GUI 应用程序和客户端 GUI 应用程序。验证程序执行四种级别的检查：
- XML 格式良好性。
- 基于 RELAX NG 模式的有效性（可以选择禁用该选项）。
- RDF 有效性。
- 一系列特定于 DOAP 的语义检查。
清单 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 =
http://xmlns.com/foaf/0.1/. line 26, column 3</Detail>
</Problem>
</Problems>
|
您可以在 DOAP 主页获得该验证程序的代码（请参阅
参考资料）。在 Web 上将建立一个公共访问实例。应确保 DOAP 的采纳者能够在较早的阶段检查它们的输出，这一点很重要。此外，我建议，所有 DOAP 处理应用程序都首先验证它们的输入 -- 至少要用 RELAX NG 模式 -- 以使 Web 上 DOAP 内容的质量出现最少的异常。只需简单地看看对 Web 上 RSS feed 的松散解析所带来的混乱，就足以让您相信一定程度的严格性是有益的。为提供帮助，验证程序和查看器的代码将获得一个宽松的开放源代码许可，以便能够放心地将它们集成到其他程序中。
创建 DOAP
如何首先创建 DOAP 文件呢？最初的采纳者将在一个文本编辑器中手工编写该文件。而验证程序和 XML 模式文件则一起帮助确保那些文件不包含错误。如前所述，遵从模式的 DOAP 文件将失去一些 RDF 表达能力，但是对于大多数人来讲，这点损失关系不大。
大多数创建 DOAP 文件的人对 DOAP 词汇表本身不感兴趣。他们只是想要最终的功能，同时允许他们通过软件注册来注册他们的项目。他们很可能会找到一个例子文件，然后通过修改使其包括他们自己的数据。由于这个原因，关键是确保能提供足够的教学材料、好的例子以及验证工具，使不好的例子不至于蔓延。一旦糟糕的剪切-粘贴版本传了出去，其蔓延之势便难于阻止了。
DOAP 创建过程的剪切-粘贴阶段应该尽可能地短。您可以通过引入对 DOAP 文件创建的一定程度的工具支持来做到这一点。大多数软件开发人员已经在使用某些打包和配置系统，这些系统至少包含为软件生成 DAOP 文件时所需的部分元数据。这样的系统包括用于 C 语言编程的 GNU
Autoconf、Python
distutils、Perl 的
MakeMaker文件等等。如果对于开发人员所选择的系统有一个容易的 DOAP 生成方案，那么就可以增加获得 DOAP 文件权利的机会。
此外，您可以使用不同的创建 DOAP 文件的有向导的方法：
-
DOAP-a-matic： Leigh Dodds 的
FOAF-a-matic 是一种支持 JavaScript 的 Web 页面，它使得 FOAF（Friend-of-a-friend）文件的创建变得容易。其 DOAP 版本很有用，所以开发人员只需回答一些问题。
-
Freshmeat-to-DOAP 转换：Freshmeat 软件注册或许是在周围最大的，它提供了 Freshmeat 内容的 XML 输出。编写一个从 Freshmeat 内容生成 DOAP 描述的程序将变得相当容易。
-
GUI 应用程序：图形应用程序可以集成到一个 IDE（例如 Eclipse 或
MonoDevelop）中，并将 DOAP 所需的元数据与项目的构建信息存储在一起。然后，DOAP 文件就成了最终的 build 的一部分。
这里虽然创建了 DOAP，但应该达到两个重要的目标，即 DOAP 应该尽可能易于开发人员使用，并且其创建的输出应尽可能的丰富和高质量。可用数据的普遍性和质量都是 DOAP 前景的关键所在。
社区
即使有了工具，如果没有集结在 DOAP 项目周围的社区，那么它也不大可能长久。引入新技术时，沟通是至高无上的。像约定的规则一样清晰地表达项目的目标，这一点很重要。沟通中最基本的步骤是构造一个 Web 站点，该 Web 站点应包含所有相关文档，并指向在项目中可以使用的那些相关资源。
图 3 展示了 DOAP 主页的一个屏幕快照。注意两个重要特征：清楚的导航和新闻。静态 Web 站点常常给人以沉闷的印象，而定时地更新新闻则可以满足通知人们和使项目看上去生动的双重需要。现今，为项目新闻使用 RSS feed 也是必要的。
图 3. DOAP 主页的屏幕快照
虽然没有必要一开始就回答所有可以想像到的问题，但是项目 Web 站点需要在添加文档和教程材料方面的反应尽可能地迅速。
How-to 问题以及 FAQ 常常出现在新采纳者第一眼就可以看到的地方。
然而，沟通不会总是单方向的。我们需要有一个论坛，让那些有兴趣使用和采纳 DOAP 的人能够互相碰面并问一些问题。对于开放源代码项目，邮件列表曾经是最成功的实现这一点的媒介，而 DOAP 也确实有这样的东西
（请参阅
参考资料）。 随着社区的增长，使用 DOAP 的第三方可以在那里宣布他们自己的产品和成就，以促进他们的产品或成就被采纳并得到进一步的发展。
最后，必须向那些可能感兴趣的人展示项目，使得项目植根于群众。除了在 XML 会议上展示 DOAP 以外，我还将在各种邮件列表中宣传它，并向开放源代码领域内的一些关键人物作宣传。
结束语
虽然本文是关于 DOAP 的创建的系列文章（分为 4 个部分）中的最后一篇，但它也标志着公众眼里项目生命周期的开始。我相信，DOAP 在利用 Web 技术语义上的威力，和保留足够的 "Webby" 以获得大规模的支持这两者之间将达到一个适当的平衡。几个月之后，我将在本专栏中回访这个项目，看看这些决定在中长期内表现如何。
参考资料
关于作者
对本文的评价
| 
