mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-26 19:22:15 -05:00
adjustments to address https://github.com/xsf/xeps/issues/281
This commit is contained in:
Peter Saint-Andre
Sam Whited
parent
0cb3edcdb3
commit
475fa51d7e
58
xep-0143.xml
58
xep-0143.xml
@ -22,6 +22,12 @@
|
||||
<supersededby/>
|
||||
<shortname>N/A</shortname>
|
||||
&stpeter;
|
||||
<revision>
|
||||
<version>1.1.2</version>
|
||||
<date>2016-12-02</date>
|
||||
<initials>psa</initials>
|
||||
<remark><p>Reflect preference for GitHub pull requests to maintain existing XEPs; update terminology to refer to XMPP Extensions Editor team.</p></remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>1.1.1</version>
|
||||
<date>2016-08-27</date>
|
||||
@ -92,23 +98,23 @@
|
||||
<section1 topic='Submitting a Proposal' anchor='submit'>
|
||||
<p>The process for submitting a proposal for consideration as a XEP is straightforward:</p>
|
||||
<ol>
|
||||
<li>Contact the &EDITOR; so that he knows to expect your submission.</li>
|
||||
<li>Write your proposal following the guidelines described in this document.</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 pointing to the file) to the XMPP Extensions Editor.</li>
|
||||
<li>Send your XML file (or a URL pointing to the file) to the &EDITOR; team via email to editor@xmpp.org (make sure that the email subject includes the string "XEP" somewhere in it!)..</li>
|
||||
</ol>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Maintaining a XEP' anchor='maintain'>
|
||||
<p>If your proposal is accepted as a XEP, you will probably need to update the specification periodically to incorporate feedback as well as implementation and deployment experience. The XMPP Extensions Editor will assign a XEP number to your document and add it to source control.</p>
|
||||
<p>The XMPP Extensions Editor prefers that you work as follows:</p>
|
||||
<p>If your proposal is accepted as a XEP, you will probably need to update the specification periodically to incorporate feedback as well as implementation and deployment experience. The XMPP Extensions Editor team will assign a XEP number to your document and add it to source control.</p>
|
||||
<p>The XMPP Extensions Editor team prefers that you work as follows:</p>
|
||||
<ol>
|
||||
<li>Check out a copy of the XSF's git repository by following the instructions at &SOURCECONTROL;</li>
|
||||
<li>Make your desired changes to the document, including an updated <revision/> element as described below.</li>
|
||||
<li>Generate a patch using the command <strong>git format-patch HEAD^</strong></li>
|
||||
<li>Send the patch using the command <strong>git send-email --to=editor@xmpp.org NAMEOF.patch</strong></li>
|
||||
<li>Create your own fork of the XSF's git repository (the address of the GitHub mirror can be found at &SOURCECONTROL;).</li>
|
||||
<li>Create a dedicated branch for these changes in your forked repository.</li>
|
||||
<li>Make your desired changes to the document or documents, including an updated <revision/> element as described below.</li>
|
||||
<li>Commit and push the changes to your branch.</li>
|
||||
<li>Create a pull request from your fork to the master branch at the GitHub mirror.</li>
|
||||
</ol>
|
||||
<p>The XMPP Extensions Editor will then apply your patch and publish an updated version of your XEP.</p>
|
||||
<p>The XMPP Extensions Editor team will then process your pull request, seek Council approval if necessary, and publish an updated version of your XEP.</p>
|
||||
<p>NOTE: As explained in <cite>XEP-0001</cite>, updated versions of XEPs in the Experimental state are published without the need for approval by the XMPP Council. However, updated versions of XEPs in the Active, Draft, or Final state must be approved by the XMPP Council to ensure proper change control regarding approved protocols.</p>
|
||||
</section1>
|
||||
|
||||
@ -117,23 +123,23 @@
|
||||
<section2 topic='Working with XEP Files' anchor='format-work'>
|
||||
<p>The best way to start working on your proposal is to retrieve all of the existing XEP files and associated stylesheets from source control. These files are stored using the git system as described at &SOURCECONTROL;. The document structure is formally defined by both a DTD and an XML schema, but you do not need to understand the formal descriptions in order to author a XEP. In addition, a handy template file is included as the 'xep-template.xml' file in the 'extensions' directory, providing a quick starting point for XEP authoring.</p>
|
||||
<p>To create your proposal, do a git clone of the 'xeps' repository, go to the 'xeps/' directory you just cloned (e.g., 'cd xeps'), copy the template file (e.g., 'cp xep-template.xml xep-foo.xml'), and start editing the file using either a basic text editor or a specialized XML editing application such as XML Spy or XMLmind.</p>
|
||||
<p>Even if you use a basic text editor, you should be able to view your document in most modern web browsers as an XML file as long as you have xep.xsl and xep.dtd in the 'xeps' directory. Because of inconsistencies in browser XSLT implementations, certain formatting (e.g., table layouts and the numbering of tables, examples, and footnotes) might not be perfect. Don't panic; it will look fine in the HTML output produced by the XMPP Extensions Editor. If your XML file doesn't render at all (i.e., it's just one big text blob), you are using a bad browser. If you see only the bare outline generated by xep.xsl but none of your text, you have an error in your XML. You can check your XML syntax at xml.com <note><<link url="http://www.xml.com/pub/a/tools/ruwf/check.html">http://www.xml.com/pub/a/tools/ruwf/check.html</link>></note>.</p>
|
||||
<p>To programatically convert your XML file into HTML, we recommend using Daniel Veillard's <link url='http://xmlsoft.org/XSLT/'>xsltproc</link> program, which will give you helpful error messages regarding XML syntax problems. However, the XMPP Extensions Editor will complete the final rendering of XML into HTML as well as posting of your HTML file to www.xmpp.org, so you do not need to generate HTML files for submission to the XMPP Extensions Editor (in fact, the XMPP Extensions Editor requires that you submit your proposal in the XEP XML format, not HTML).</p>
|
||||
<p>Finally, the xep.ent file contains convenient "external entities" that provide shortcuts for including references to XMPP Extension Protocols, RFCs, and other common strings. Unfortunately, most browsers do not correctly process external entities, so you cannot include entities from xep.ent if you need to view your XML source file in a browser. However, the XMPP Extensions Editor reserves the right to convert your markup to external entities, since it makes his life easier. Also, please do not add items to the xep.ent file; instead, add them as inline entities within your document and then ask the XMPP Extensions Editor to add them to the xep.ent file.</p>
|
||||
<p>Even if you use a basic text editor, you should be able to view your document in most modern web browsers as an XML file as long as you have xep.xsl and xep.dtd in the 'xeps' directory. Because of inconsistencies in browser XSLT implementations, certain formatting (e.g., table layouts and the numbering of tables, examples, and footnotes) might not be perfect. Don't panic; it will look fine in the HTML output produced by the XMPP Extensions Editor team. If your XML file doesn't render at all (i.e., it's just one big text blob), you are using a bad browser. If you see only the bare outline generated by xep.xsl but none of your text, you have an error in your XML. You can check your XML syntax at xml.com <note><<link url="http://www.xml.com/pub/a/tools/ruwf/check.html">http://www.xml.com/pub/a/tools/ruwf/check.html</link>></note>.</p>
|
||||
<p>To programatically convert your XML file into HTML, we recommend using Daniel Veillard's <link url='http://xmlsoft.org/XSLT/'>xsltproc</link> program, which will give you helpful error messages regarding XML syntax problems. However, the XMPP Extensions Editor team will complete the final rendering of XML into HTML as well as posting of your HTML file to www.xmpp.org, so you do not need to generate HTML files for submission to the XMPP Extensions Editor team (in fact, the XMPP Extensions Editor team requires that you submit your proposal in the XEP XML format, not HTML).</p>
|
||||
<p>Finally, the xep.ent file contains convenient "external entities" that provide shortcuts for including references to XMPP Extension Protocols, RFCs, and other common strings. Unfortunately, most browsers do not correctly process external entities, so you cannot include entities from xep.ent if you need to view your XML source file in a browser. However, the XMPP Extensions Editor team reserves the right to convert your markup to external entities, since it makes their life easier. Also, please do not add items to the xep.ent file; instead, add them as inline entities within your document and then ask the XMPP Extensions Editor team to add them to the xep.ent file.</p>
|
||||
</section2>
|
||||
<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 ten 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 or two sentences that capture 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 <title/> element is the title of your XEP. Choose a descriptive title that is less than ten words long. The XMPP Extensions Editor team may change this in consultation with the author.</p>
|
||||
<p>The XML character data of the <abstract/> element SHOULD be one or two sentences that capture the essence of your proposal (usually beginning "This specification defines an XMPP protocol extension that..."). The XMPP Extensions Editor team 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 <number/> element SHOULD be "xxxx"; this will be changed to the next sequential XEP number by the XMPP Extensions Editor team 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 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 <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 team). A Standards Track XEP defines an XMPP extension intended to be used as a common part of 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., <cite>XEP-0093</cite>) for the protocol that is being superseded.</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 team).</p>
|
||||
<p>The <supersedes/>, <supersededby/>, <shortname/>, and <schemaloc/> elements are for use by the XMPP Extensions Editor team; however, if your document supersedes an existing XMPP Extension Protocol, feel free to include a <spec/> child element specifying the document identifier (e.g., <cite>XEP-0093</cite>) for the protocol that is being superseded.</p>
|
||||
<p>Include one <author/> element for each co-author. Note well that the <firstname/> and <surname/> elements are REQUIRED per <cite>XEP-0001</cite>, 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.10" after "0.9"). The format for the <date/> element is yyyy-mm-dd.</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 team, 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.10" after "0.9"). The format for the <date/> element is yyyy-mm-dd.</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' 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>
|
||||
@ -141,12 +147,12 @@
|
||||
<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. However keep in mind that tables weren't meant to display a huge amount of text.</p>
|
||||
<p>The xep.xsl file performs all sorts of magic in converting your XML file into HTML, including creation of the front matter, table of contents, section numbering, notes, and revision history. Feel free to submit patches for this file, but do not commit your modified version to source control.</p>
|
||||
<p>Although HTML is the primary publishing format for XEPs, since 2009 the XMPP Extensions Editor has also published XEPs in the form of PDF file. Keeping that in mind, try to avoid tables with too many columns, which might require wider paper than is normal.</p>
|
||||
<p>Although HTML is the primary publishing format for XEPs, since 2009 the XMPP Extensions Editor team has also published XEPs in the form of PDF file. Keeping that in mind, try to avoid tables with too many columns, which might require wider paper than is normal.</p>
|
||||
</section2>
|
||||
</section1>
|
||||
|
||||
<section1 topic='The Sections of a XEP Document' anchor='sections'>
|
||||
<p>Most XEP specifications will have most of the following sections, usually in something like the order shown. Other sections may be appropriate (e.g., &xep0071; has a section for W3C Considerations). Use your best judgment regarding the sections you need in order to make your argument, or consult with the XMPP Extensions Editor regarding your needs.</p>
|
||||
<p>Most XEP specifications will have most of the following sections, usually in something like the order shown. Other sections may be appropriate (e.g., &xep0071; has a section for W3C Considerations). Use your best judgment regarding the sections you need in order to make your argument, or consult with the XMPP Extensions Editor team regarding your needs.</p>
|
||||
<section2 topic='Introduction' anchor='sections-intro'>
|
||||
<p>The introduction to a XEP document is quite important since it provides the rationale for considering the proposal. In particular, the introduction SHOULD include information such as the following:</p>
|
||||
<ol>
|
||||
@ -172,7 +178,7 @@
|
||||
<li>Describe the expected behavior of XMPP clients, servers, and components when using this protocol.</li>
|
||||
<li>Include lots of protocol examples. <note>Our mantra is: "We put the example in example.com!"</note></li>
|
||||
</ul>
|
||||
<p>We repeat: include lots of protocol examples. Examples help not only implementers 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>
|
||||
<p>We repeat: include lots of protocol examples. Examples help not only implementers but also those who will review your proposal in the Standards SIG and XMPP Council. You get extra credit with the XMPP Extensions Editor team if you follow Jabber tradition by using characters and situations from the plays of Shakespeare:</p>
|
||||
<example caption='An Example from Shakespeare'><![CDATA[
|
||||
<message
|
||||
from='juliet@capulet.com/balcony'
|
||||
@ -198,13 +204,13 @@
|
||||
<p>Your proposal MUST include a section entitled "Security Considerations". Even if there are no security features or concerns related to your proposal, you MUST note that fact. For helpful guidelines, refer to &rfc3552;; the core XMPP specification (<cite>RFC 6120</cite>) also includes a very thorough security considerations section that can be used as an examplar.</p>
|
||||
</section2>
|
||||
<section2 topic='IANA Considerations' anchor='sections-iana'>
|
||||
<p>This section is REQUIRED. The IANA is &IANA;, 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 in his role as the XMPP Registrar. Do not contact the IANA on your own!</p>
|
||||
<p>This section is REQUIRED. The IANA is &IANA;, 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 team in their role as the XMPP Registrar. Do not contact the IANA on your own!</p>
|
||||
</section2>
|
||||
<section2 topic='XMPP Registrar Considerations' anchor='sections-registrar'>
|
||||
<p>This section is REQUIRED. The ®ISTRAR; maintains a list of reserved 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 in his role as the XMPP Registrar.</p>
|
||||
<p>This section is REQUIRED. The ®ISTRAR; maintains a list of reserved 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 team in their role as the XMPP Registrar.</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>
|
||||
<p>An XML Schema is required in order for protocols to be approved by the XMPP Council. The XMPP Extensions Editor team can assist you in defining an XML Schema for the protocol you are proposing.</p>
|
||||
</section2>
|
||||
<section2 topic='Acknowledgements' anchor='sections-ack'>
|
||||
<p>Most XEP documents end with a section thanking non-authors who have made significant contributions or who have provided feedback regarding the specification.</p>
|
||||
@ -212,7 +218,7 @@
|
||||
</section1>
|
||||
|
||||
<section1 topic='XEP Styleguide' anchor='styleguide'>
|
||||
<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 might 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>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 team 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 they may find in your proposal, but might 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 team 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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user