XEP-0143
本文的英文原文来自XEP-0143
XEP-0143: XMPP扩展协议作者指南
| 摘要: | 本文对XMPP扩展协议的作者提供帮助信息. |
|---|---|
| 作者: | Peter Saint-Andre |
| 版权: | © 1999 - 2013 XMPP标准化基金会(XSF). 参见法律通告. |
| 状态: | 活跃 |
| 类型: | 程序 |
| 版本: | 1.1 |
| 最后更新日期: | 2011-07-08 |
注意: 这个程序文档定义了一个已经被XMPP委员会和/或XSF董事会批准的XMPP标准基金会(XSF)的流程或活动. XSF目前正是遵循这里定义的流程或活动并且将继续这么做，直到本文档被取消或废除.
目录 |
简介
XMPP标准基金会(XSF) 1 收到大量的提案为XMPP Core 2中定义的核心XMPP协议定义扩展. 然而, 作者们并不总是清楚怎样最佳地结构化一个提案以让它能作为一个XMPP扩展(XEP)被接受并从而进一步通过XSF的标准流程. 所以, 本文提供指南来帮助作者写出更好的XMPP扩展协议定义.
这些指南假定读者们对XMPP扩展协议 3所定义的XEP系列文档和XSF处理它们的流程很熟悉, .
提交提案之前
强烈鼓励一个可能的作者在提交一个提案成为一个XEP之前完成一些研究. 特别是, 该作者应该做以下几件事:
- 查看XMPP RFCs和实验性的, 活跃的, 草案, 和最终XEPs以决定是否真的为了填补现有的XMPP技术和协议的空白而需要该建议的协议扩展.
- 查看被拒绝的和被延期的XEPs, 以及那些永远不会被接受的提案(见 <http://xmpp.org/extensions/inbox/>)来决定是否过去已经有类似的扩展提案但是没有被XMPP理事会 4 批准.
- 查看其他标准开发组织开发的协议, 例如互联网工程工作组(IETF) 5和万维网联盟(W3C) 6, 来决定是否它们比在一个新的XMPP扩展里更合适.
- 查看Standards SIG 7中的讨论以决定是否过去已经讨论过或目前正在讨论类似的功能.
在完成这些研究之后, 潜在的作者可以断定是否需要新的协议扩展. 如果需要, 强烈建议该作者做以下事情:
- 查看 XEP-0001 和 XMPP设计准则 8.
- 理解提交过程.
- 熟悉XEP的XML格式.
- 然后只写一个提案包含所有适当的XEP章节.
- 查看内容并确保它遵循XEP Styleguide.
提交提案
提交一个提案成为XEP的过程很简单:
- 联系XMPP Extensions Editor 9 让他知道等待你的提案.
- 遵循本文描述的指南写下你的提案.
- 确保你在提交你的提案之前阅读, 理解, 并同意XSF IPR Policy 10.
- 把你的XML文件(或一个指向该文件的URL)发给XMPP扩展编辑.
维护XEP
如果你的提案被接受成为一个XEP, 你可能需要定期更新这个协议以整合反馈以及实现和部署的经验. XMPP扩展编辑将分配一个号码给你的文档并添加到源文件控制中.
XMPP扩展编辑比较喜欢你按以下步骤工作:
- 遵循<http://xmpp.org/about-xmpp/xsf/xsf-source-control/> 的指引从XSF的git仓库检出一份拷贝
- 对文档做出你期望的修改, 包括一个如下所属的新 <revision/> 元素.
- 使用命令 git format-patch HEAD^生成一个补丁
- 使用命令 git send-email --to=editor@xmpp.org NAMEOF.patch发送该补丁
XMPP扩展编辑将应用你的补丁并发布一个你的XEP的更新版本.
注意: 如XEP-0001解释的一样, 实验状态的XEPs的更新版本的发布不需要XMPP理事会的批准. 无论如何, 活跃,草案,或最终状态的XEPs的更新版本必须由XMPP理事会批准以确保对于已批准的协议的正确的变更控制.
XEP的XML格式
XEP的XML格式实质上类似于XHTML的精简集. 这是有意的: 这使XEPs作者更易使用. 实际上, 如果你使用模版文件以及和它相关的XSLT样式表, 你应该能够在大多数现代浏览器中查看你的提案(见下文). 以下章节解释了如何开始XEP的写作并描述了用于XEPs的XML格式(正式的描述参见 xep.xsd 或 xep.dtd 文件).
和XEP文件一起工作
在你的提案上开始工作的最好的办法是从源文件控制获取所有现有的XEP文件和相关的样式表. 这些文件使用git存储，如 <http://xmpp.org/about-xmpp/xsf/xsf-source-control/> 所述. 文档结构同时被DTD和XML schema正式地定义, 但是你不需要为了写一个XEP而理解正规的描述. 此外, 在 'extensions' 目录有一个方便的模版文件 'xep-template.xml' , 提供了XEP写作的快速起点.
为了创建你的提案, 做一次'xmpp' 模块的 git checkout , 变更目录到 'extensions/' 目录, 拷贝模板文件 (例如, 'cp xep-template.xml xep-foo.xml'), 然后开始使用基本编辑器或专业的XML编辑器应用例如 XML Spy 或 XMLmind来编辑文件.
即使你使用一个基本的编辑器, 你也应该能在大多数现代的web浏览器上以XML文件方式查看你的文档，只要在'extensions/'目录有xep.xsl和xep.dtd文件 . 因为浏览器中的XSLT实现不一致, 特定的格式(例如, 表布局和表编号, 示例, 以及脚注)可能不完美. 不用着急; 它在XMPP扩展编辑制作的HTML输出中会看起来不错. 如果你的XML文件根本不能展现(即, 它只是一个大的文本块), 表明你使用的是一个坏的浏览器. 如果你只看到xep.xsl生成的很少几行而没有看到你的文本, 表明你的XML有错误. 你可以 xml.com 11检查你的XML语法在.
要用程序来把你的XML文件转成HTML, 我们推荐使用Daniel Veillard的xsltproc]程序, 它会给出一些关于XML语法问题的有用的错误信息. 无论如何, XMPP扩展编辑将完成最终的把XML转成HTML以及把你的HTML文件投递到 www.xmpp.org, 所以你不需要为了提交个哦XMPP扩展编辑而生成HTML文件(实际上, XMPP扩展编辑要求你以XEP XML格式而不是HTML格式提交提案).
最后, xep.ent 文件包含了方便的 "外部实体" 来提供快捷方式去包含对XMPP扩展协议, RFCs, 和其他通用字符串的参考. 不幸的是, 大部分浏览器不能正确地处理外部实体, 所以如果你需要在一个浏览器中查看你的XML源文件，那么你不能从xep.ent包含实体. 无论如何, XMPP扩展编辑保留把你的标记转换成外部实体的权力, 因为这使他的工作容易一些. 而且, 请不要添加条目到 xep.ent 文件; 反之, 把它们作为inline实体添加到你的文档中然后请XMPP扩展编辑把它们添加到 xep.ent 文件.
文件元数据
本章描述包含在XEP文件的<header/>元素中的元数据元素(文件内容请见下文).
<title/>元素的XML字符串数据是你的XEP的标题. 选择一个少于十个单词长度的描述性标题. XMPP扩展编辑可能在和作者讨论后修改它.
<abstract/>元素的XML字符串数据应该是一个或两个句子关于你的提案的摘要(通常开始于"本协议定义了一个XMPP协议扩展..."). XMPP扩展编辑将会修改这个摘要以使它准确地描述该提案.
<legal/>元素的XML字符串数据必须如 XSF IPR Policy 中那样定义并且同时反映在xep.ent文件和XEP模板中.
<number/>元素的XML字符串数据应该是"xxxx"; 如果XMPP理事会接受该提案成为一个XMPP扩展协议，它将由XMPP扩展编辑修改成下一个顺序的XEP编号.
<status/>元素的XML字符串数据应该是"ProtoXEP"，因为所有提案开始都是"proto-XEPs"; 如果XMPP理事会接受该提案成为一个XMPP扩展协议，它将被改为"Experimental".
<type/>元素的XML字符串数据应该要么是"Standards Track"要么是"Informational" (也有 Historical, Humorous, 和 Procedural XEPs, 但是那些是不通用并且常见是由XMPP扩展编辑写的). 一个Standards Track XEP 定义一个打算用作XMPP技术的通用部分的XMPP扩展. 一个Informational XEP 定义最佳实践或一个和XMPP或XMPP扩展协议相关的范本的使用(例如, Best Practices for Use of SASL ANONYMOUS 12).
<approver/>元素的XML字符串数据应该是"Council".
<dependencies/>元素用于以一个规范性的方法定义你的提案所依赖的RFCs, XMPP扩展协议, 和其他协议(即, 为了实现你提议的协议，这些协议必须或应该被理解). 每个协议必须由一个唯一的<spec/>子元素来标识(关于文档标识符的线索请参考现有的XEP协议, 或询问XMPP扩展编辑).
<supersedes/>, <supersededby/>, <shortname/>, 和<schemaloc/>元素由XMPP扩展编辑使用; 无论如何, 如果你的文档取代一个现有的XMPP扩展协议, 可以把要取代的那个协议包含在一个定义该文档标识符的<spec/>子元素中(例如, XEP-0093).
为每一个合著者包含一个<author/>元素. 注意，根据XEP-0001的要求<firstname/>和<surname/>元素是必需的, 然后是一些<email/>, <jid/>, 和<uri/>元素的组合， 这样就有了适当的可用的联系人信息.
为你的文档的每一个修订包含一个<revision/>元素.你给XMPP编辑的初始提交文档的<version/>元素的XML字符串数据应该是"0.0.1", 并且<remark/>元素应该是"First draft."; 对每一个修订, 你将包含一个新的<revision/>元素(把它放在现有的<revision/>元素的前面)并且重复<version/>元素(例如, "0.0.2"在"0.0.1"后面或"0.10"在"0.9"后面). <date/>元素的格式为 yyyy-mm-dd.
文件内容
除了<header/>元素（见上文）里的元数据，XEP文件是一系列的章节，以层次结构来排版（<section1/>是一个顶层章节，您可以在其中嵌套<section2/>章节，一直到<section4/>）。一个章节的标题是其“topic”属性。你也应该包括一个'anchor'属性，让您可以在您的文档链接到页面中的片段。章节元素内允许的元素可能看起来类似XHTML：<p/>为段落，<ol/>和<ul/>为有序和无序列表，依此类推。
<example/>和<code/>元素是用来显示协议片段; <example/>元素应具备“caption”属性以描述示例，而<code/>元素没有这个属性。在这些元素内都定义了一个XML CDATA章节，这样你就不需要在你的示例XML节中避免“<”和“>”字符，因为这使作者和编辑的生活变得更容易（见现有XEP协议的标记）。
<p/>和
