mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-21 16:55:07 -05:00
tweaks
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1925 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre
parent
9f6dee1b78
commit
ef894946ff
34
xep-0143.xml
34
xep-0143.xml
@ -78,7 +78,7 @@
|
||||
<ol>
|
||||
<li>Contact the &EDITOR; so that he knows to expect your submission.</li>
|
||||
<li>Write your proposal following the guidelines described herein.</li>
|
||||
<li>Make sure you read, understand, and agree to the &XSFIPR; before you submit your proposal.</li>
|
||||
<li>Make sure that you read, understand, and agree to the &XSFIPR; before you submit your proposal.</li>
|
||||
<li>Send your XML file (or a URL for the file) to the XMPP Extensions Editor.</li>
|
||||
</ol>
|
||||
</section1>
|
||||
@ -94,20 +94,19 @@
|
||||
<section2 topic='File Metadata' anchor='format-metadata'>
|
||||
<p>This section describes the metadata elements contained in the <header/> element of a XEP file (see below for the file contents).</p>
|
||||
<p>The XML character data of the <title/> element is the title of your XEP. Choose a descriptive title that is less than five words long. The XMPP Extensions Editor may change this in consultation with the author.</p>
|
||||
<p>The XML character data of the <abstract/> element SHOULD be one sentence that captures the essence of your proposal (usually beginning "This document defines a protocol that..."). The XMPP Extensions Editor has been known to modify the abstract so that it accurately describes the proposal.</p>
|
||||
<p>The XML character data of the <legal/> element MUST be as follows:</p>
|
||||
<p class='indent'>This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy (<http://www.xmpp.org/extensions/ipr-policy.shtml>). This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).</p>
|
||||
<p>The XML character data of the <number/> element SHOULD be "xxxx"; this will be changed to the next sequential XEP number by the XMPP Extensions Editor if the XMPP Council accepts the proposal as an XMPP Extensions Protocol.</p>
|
||||
<p>The XML character data of the <status/> element SHOULD be "ProtoXEP" since all proposals start out as "proto-XEPs"; this will be changed to "Experimental" if the XMPP Council accepts the proposal as an XMPP Extensions Protocol.</p>
|
||||
<p>The XML character data of the <type/> element SHOULD be either "Standards Track" or "Informational" (there are also Historical, Humorous, and Procedural XEPs, but these are uncommon and usually written by the XMPP Extensions Editor). A Standards Track XEP defines a XMPP extension intended to be used as a common part of Jabber/XMPP technologies. An Informational XEP defines best practices or a usage profile related to XMPP or an XMPP Extension Protocol (e.g., &xep0175;).</p>
|
||||
<p>The XML character data of the <abstract/> element SHOULD be one sentence that captures the essence of your proposal (usually beginning "This specification defines an XMPP protocol extension that..."). The XMPP Extensions Editor has been known to modify the abstract so that it accurately describes the proposal.</p>
|
||||
<p>The XML character data of the <legal/> element MUST be as defined in the XSF IPR Policy and reflected in both the xep.ent file and the XEP template.</p>
|
||||
<p>The XML character data of the <number/> element SHOULD be "xxxx"; this will be changed to the next sequential XEP number by the XMPP Extensions Editor if the XMPP Council accepts the proposal as an XMPP Extension Protocol.</p>
|
||||
<p>The XML character data of the <status/> element SHOULD be "ProtoXEP" since all proposals start out as "proto-XEPs"; this will be changed to "Experimental" if the XMPP Council accepts the proposal as an XMPP Extension Protocol.</p>
|
||||
<p>The XML character data of the <type/> element SHOULD be either "Standards Track" or "Informational" (there are also Historical, Humorous, and Procedural XEPs, but these are uncommon and usually written by the XMPP Extensions Editor). A Standards Track XEP defines an XMPP extension intended to be used as a common part of Jabber/XMPP technologies. An Informational XEP defines best practices or a usage profile related to XMPP or an XMPP Extension Protocol (e.g., &xep0175;).</p>
|
||||
<p>The XML character data of the <approver/> element SHOULD be "Council".</p>
|
||||
<p>The <dependencies/> element is used to specify RFCs, XMPP Extension Protocols, and other specifications on which your proposal depends in a normative fashion (i.e., specifications that MUST or SHOULD be understood in order to implement your proposed protocol). Each specification MUST be identified by a distinct <spec/> child element (see existing XEP specifications for clues regarding document identifiers, or consult with the XMPP Extensions Editor).</p>
|
||||
<p>The <supersedes/>, <supersededby/>, <shortname/>, and <schemaloc/> elements are for use by the XMPP Extensions Editor; however, if your document supersedes an existing XMPP Extension Protocol, feel free to include a <spec/> child element specifying the document identifier (e.g., XEP-0093) for the protocol that is being superseded.</p>
|
||||
<p>Include one <author/> element for each co-author. Note well that the <firstname/>, <surname/>, <email/>, and <jid/> elements are all REQUIRED per XEP-0001.</p>
|
||||
<p>Include one <revision/> element for each revision of your document. The XML character data of the <version/> element SHOULD be "0.0.1" for your initial submission to the XMPP Extensions Editor, and the <remark/> SHOULD be "Initial version."; for each revision, you will include another <revision/> element (place it before the existing <revision/> elements) and iterate the <version/> element (e.g., "0.2" after "0.1"). The format for the <date/> element is yyyy-mm-dd. Please do not include the characters ' or " in your revision remarks.</p>
|
||||
<p>Include one <author/> element for each co-author. Note well that the <firstname/> and <surname/> elements are REQUIRED per XEP-0001, as is some combination of the <email/>, <jid/>, and <uri/> elements so that appropriate contact information is available.</p>
|
||||
<p>Include one <revision/> element for each revision of your document. The XML character data of the <version/> element SHOULD be "0.0.1" for your initial submission to the XMPP Extensions Editor, and the <remark/> SHOULD be "First draft."; for each revision, you will include another <revision/> element (place it <em>before</em> the existing <revision/> elements) and iterate the <version/> element (e.g., "0.0.2" after "0.0.1" or "0.7" after "0.6"). The format for the <date/> element is yyyy-mm-dd. Please do not include the characters ' or " in your revision remarks.</p>
|
||||
</section2>
|
||||
<section2 topic='File Contents' anchor='format-contents'>
|
||||
<p>Aside from the metadata in the <header/> element (see above), a XEP file is a series of sections, arranged in a hierarchy (<section1/> is a top-level section, within which you can nest <section2/> sections, and so on down to <section4/>). The title of a section is captured in the 'topic' attribute. You should also include an 'anchor' element so that you can link to page fragments from within your document. The allowable elements within a section element probably look familiar from XHTML: <p/> for paragraphs, <ol/> and <ul/> for ordered and unordered lists, and so on.</p>
|
||||
<p>Aside from the metadata in the <header/> element (see above), a XEP file is a series of sections, arranged in a hierarchy (<section1/> is a top-level section, within which you can nest <section2/> sections, and so on down to <section4/>). The title of a section is captured in the 'topic' attribute. You should also include an 'anchor' attribute so that you can link to page fragments from within your document. The allowable elements within a section element probably look familiar from XHTML: <p/> for paragraphs, <ol/> and <ul/> for ordered and unordered lists, and so on.</p>
|
||||
<p>The <example/> and <code/> elements are used to show protocol snippets; the <example/> element SHOULD possess a 'caption' attribute that describes the example, whereas the <code/> element does not. Define an XML CDATA section within both of these elements so that you do not need to escape the '<' and '>' characters in your sample XML stanzas, since this makes life much easier for author and editor alike (see the markup in existing XEP specifications).</p>
|
||||
<p>The <p/> and <li/> elements can also contain more markup that is familiar from XHTML, such as the <img/> element. Note that hyperlinks are of the form <link url='foo'>bar</link> rather than <a href='foo'>bar</a>; the reasons for this are lost in the mists of time and it is too late to change it now, so you'll just have to adjust. If needed, you can also use inline structural and presentational markup such as <em/>, <strong/>, <tt/>, <cite/>, and <span/> within the <p/> and <li/> elements. </p>
|
||||
<p>You may also include tables (these are helpful for listing error codes and such). The <table/> element SHOULD possess a 'caption' attribute that describes the table's contents. Standard XHTML table structure applies (<tr/> defines a row, which contains <th/> elements for header rows and <td/> elements for data rows), and the 'colspan' and 'rowspan' attributes are also available if you need them. Table presentation (such as cellpadding and cellspacing) is handled by the XSLT and CSS stylesheets.</p>
|
||||
@ -138,7 +137,7 @@
|
||||
<ul>
|
||||
<li>Clearly define the success scenarios, alternate flows, and possible errors.</li>
|
||||
<li>Describe the expected behavior of Jabber/XMPP clients, servers, and components when using this protocol.</li>
|
||||
<li>Include lots of protocol examples.</li>
|
||||
<li>Include lots of protocol examples. <note>Our mantra is: "We put the example in example.com!"</note></li>
|
||||
</ul>
|
||||
<p>We just said so, but we will repeat ourselves: include lots of protocol examples. Examples help not only implementors but also those who will review your proposal in the Standards SIG and XMPP Council. You get extra credit with the XMPP Extensions Editor if you follow Jabber tradition by using characters and situations from the plays of Shakespeare:</p>
|
||||
<example caption='An Example from Shakespeare'><![CDATA[
|
||||
@ -169,7 +168,7 @@
|
||||
<p>This section is REQUIRED. The IANA is the Internet Assigned Numbers Authority, the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. Most proposals do not require interaction with the IANA, in which case the text of this section SHOULD read "This document requires no interaction with the Internet Assigned Numbers Authority (IANA)." If your proposal requires interaction with the IANA, discuss the matter with the XMPP Extensions Editor. Do not contact the IANA on your own!</p>
|
||||
</section2>
|
||||
<section2 topic='XMPP Registrar Considerations' anchor='sections-registrar'>
|
||||
<p>This section is REQUIRED. The XMPP Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the XMPP Standards Foundation. If your proposal does not require interaction with the XMPP Registrar, the text of this section SHOULD read "No namespaces or parameters need to be registered with the XMPP Registrar as a result of this document." Refer to Draft or Final XEPs for appropriate text in other cases, or consult with the XMPP Extensions Editor.</p>
|
||||
<p>This section is REQUIRED. The XMPP Registrar maintains a list of reserved Jabber/XMPP protocol namespaces as well as registries of parameters used in the context of protocols approved by the XMPP Standards Foundation. If your proposal does not require interaction with the XMPP Registrar, the text of this section SHOULD read "No namespaces or parameters need to be registered with the XMPP Registrar as a result of this document." Refer to Draft or Final XEPs for appropriate text in other cases, or consult with the XMPP Extensions Editor.</p>
|
||||
</section2>
|
||||
<section2 topic='XML Schema' anchor='sections-schema'>
|
||||
<p>An XML Schema is required in order for protocols to be approved by the XMPP Council. The XMPP Extensions Editor can assist you in defining an XML Schema for the protocol you are proposing.</p>
|
||||
@ -180,7 +179,7 @@
|
||||
</section1>
|
||||
<section1 topic='XEP Styleguide' anchor='styleguide'>
|
||||
<p><em>Note: Authors of XMPP Extension Protocol specifications can consider this section as a kind of "Implementation Notes". :-)</em></p>
|
||||
<p>XMPP Extension Protocols are written in English. It is not expected that you will be a fine prose writer, but try to write in a clear, easily-understood fashion. The XMPP Extensions Editor will correct any errors of grammar, spelling <note>With all due respect to authors in other parts of the world, XMPP Extension Protocols follow American spelling conventions; thus "authorisation" will be changed to "authorization" and such.</note>, punctuation, and usage he may find in your proposal, but may not do so until your proposal is in the XMPP Council's queue for consideration. In addition, the XMPP Extensions Editor reserves the right to improve phrases that are unclear or infelicitous, move sections around, modify examples to use Shakespearean characters, and otherwise improve the argument and logical flow of your proposal (naturally, without changing the meaning).</p>
|
||||
<p>XMPP Extension Protocols are written in English. It is not expected that you will be a fine prose writer, but try to write in a clear, easily-understood fashion. The XMPP Extensions Editor will correct any errors of grammar, spelling <note>With all due respect to authors in other parts of the world, XMPP Extension Protocols follow American spelling conventions; thus "authorisation" will be changed to "authorization" and such.</note>, punctuation, and usage he may find in your proposal, but may not do so until your proposal is in the XMPP Council's queue for advancement to Draft or Active. In addition, the XMPP Extensions Editor reserves the right to improve phrases that are unclear or infelicitous, move sections around, modify examples to use Shakespearean characters, and otherwise improve the argument and logical flow of your proposal (naturally, without changing the meaning).</p>
|
||||
<p>The following styleguide is provided to supplement the standard English styleguides, such as <cite>The Elements of Style</cite> <note>See <<link url='http://en.wikipedia.org/wiki/The_Elements_of_Style'>http://en.wikipedia.org/wiki/The_Elements_of_Style</link>>.</note> and <cite>The Chicago Manual of Style</cite> <note>See <<link url='http://en.wikipedia.org/wiki/The_Chicago_Manual_of_Style'>http://en.wikipedia.org/wiki/The_Chicago_Manual_of_Style</link>>.</note>; please refer to those resources for information about common English (especially American English) usage and to this styleguide for XEP-specific guidelines.</p>
|
||||
<section2 topic='Attributes' anchor='style-attr'>
|
||||
<p>When talking about an attribute by name, refer to it in single quotes. Example: the 'to' attribute.</p>
|
||||
@ -190,6 +189,7 @@
|
||||
<section2 topic='Code Examples' anchor='style-ex'>
|
||||
<p>In examples, use single quotes rather than double quotes; they are more readable.</p>
|
||||
<p>To show the hierarchy of XML elements, indent two spaces for every level.</p>
|
||||
<p>If an element possesses multiple attributes, please show them in the order dictated by &w3canon;.</p>
|
||||
<p>If an element possesses a large number of attributes, include a line break before each attribute and indent them so that they are vertically aligned for readability.</p>
|
||||
<p>If the XML character data of an element is long, include line breaks and indent by two spaces.</p>
|
||||
<p>Examples are the major source of right-scrolling in our HTML output files. Right-scrolling is evil. Therefore, adjust your example layouts accordingly (line widths should be no more than 110 characters or so).</p>
|
||||
@ -207,9 +207,7 @@
|
||||
of your room; to add room owners and administrators, use the
|
||||
appropriate room commands rather than this form.
|
||||
</instructions>
|
||||
<field
|
||||
type='hidden'
|
||||
var='FORM_TYPE'>
|
||||
<field type='hidden' var='FORM_TYPE'>
|
||||
<value>http://jabber.org/protocol/muc#roomconfig</value>
|
||||
</field>
|
||||
</query>
|
||||
@ -225,11 +223,11 @@ echo -n 'bard@shakespeare.lit' | openssl dgst -sha1
|
||||
</code>
|
||||
</section2>
|
||||
<section2 topic='Conformance Terms' anchor='style-conf'>
|
||||
<p>Conformance terms (e.g,, "MUST" and "SHOULD") are specified in RFC 2119. Use them. When such terms are not in ALL CAPS, the special conformance sense does not apply (this should be obvious but may not be to all authors).</p>
|
||||
<p>Conformance terms (e.g,, "MUST" and "SHOULD") are specified in RFC 2119. Use them. When such terms are not in ALL CAPS, the special conformance sense does not apply. <note>This point should be obvious but may be confusing to some XEP authors, so we must mention it explicitly. ;-)</note></p>
|
||||
</section2>
|
||||
<section2 topic='Elements' anchor='style-elem'>
|
||||
<p>When talking about an element by name, refer to it as an empty XML element. Example: the <query/> element.</p>
|
||||
<p>The top-level &MESSAGE;, &PRESENCE;, and &IQ; elements are actually XML stanzas (see <cite>RFC 3920</cite>); refer to them as such.</p>
|
||||
<p>The top-level &MESSAGE;, &PRESENCE;, and &IQ; elements are actually XML stanzas (see <cite>RFC 3920</cite>); please refer to them as stanzas, not elements.</p>
|
||||
<p>Elements <em>possess</em> attributes and <em>contain</em> character data and/or child elements; do not confuse these terms.</p>
|
||||
<p>Do not use the term "tag" when you mean "element".</p>
|
||||
<p>Do not add a possessive to the element itself. Negative example: the <body/>'s character data. Positive example: the <body/> element's character data.</p>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user