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中的讨论以决定是否过去已经讨论过或目前正在讨论类似的功能.

在完成这些研究之后, 潜在的作者可以断定是否需要新的协议扩展. 如果需要, 强烈建议该作者做以下事情:

1. 查看 XEP-0001 和 XMPP设计准则 8.
2. 理解提交过程.
3. 熟悉XEP的XML格式.
4. 然后只写一个提案包含所有适当的XEP章节.
5. 查看内容并确保它遵循XEP Styleguide.

提交提案

提交一个提案成为XEP的过程很简单:

1. 联系XMPP Extensions Editor 9 让他知道等待你的提案.
2. 遵循本文描述的指南写下你的提案.
3. 确保你在提交你的提案之前阅读, 理解, 并同意XSF IPR Policy 10.
4. 把你的XML文件(或一个指向该文件的URL)发给XMPP扩展编辑.

维护XEP

如果你的提案被接受成为一个XEP, 你可能需要定期更新这个协议以整合反馈以及实现和部署的经验. XMPP扩展编辑将分配一个号码给你的文档并添加到源文件控制中.

XMPP扩展编辑比较喜欢你按以下步骤工作:

1. 遵循<http://xmpp.org/about-xmpp/xsf/xsf-source-control/> 的指引从XSF的git仓库检出一份拷贝
2. 对文档做出你期望的修改, 包括一个如下所属的新 <revision/> 元素.
3. 使用命令 git format-patch HEAD^生成一个补丁
4. 使用命令 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 文件.