no more CVS

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@970 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-06-18 22:00:00 +00:00
parent bf3318d4a1
commit 3101af385a
1 changed files with 3 additions and 3 deletions

View File

@ -85,8 +85,8 @@
<section1 topic='XEP XML Format' anchor='format'>
<p>The XEP XML format is substantially similar to a reduced set of XHTML. This is intentional: it makes authoring XMPP Extension Protocol specifications easier. In fact, if you use the template file with its associated XSLT stylesheet, you should be able to view your proposal in most modern web browsers (see below). The following subsections explain how to get started with XEP authoring and describe the XML format used for XMPP Extension Protocols (see the xep.xsd or xep.dtd file for a formal description).</p>
<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 XMPP Extension Protocol specifications and associated stylesheets from source control. These files are stored using Subsversion, in a CVS module labelled 'xmpp' and subdirectory labelled 'extensions' at xmpp.org. Instructions for accessing these files are provided at &lt;<link url='http://www.xmpp.org/extensions/sourcecontrol.shtml'>http://www.xmpp.org/extensions/sourcecontrol.shtml</link>&gt;. 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 an XMPP Extension Protocol. 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 CVS checkout of the 'xmpp' module, change directories to the 'extensions/' directory, 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>The best way to start working on your proposal is to retrieve all of the existing XMPP Extension Protocol specifications and associated stylesheets from source control. These files are stored using Subsversion (SVN), in a module labelled 'xmpp' and subdirectory labelled 'extensions' at xmpp.org. Instructions for accessing these files are provided at &lt;<link url='http://www.xmpp.org/extensions/sourcecontrol.shtml'>http://www.xmpp.org/extensions/sourcecontrol.shtml</link>&gt;. 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 an XMPP Extension Protocol. 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 an SVN checkout of the 'xmpp' module, change directories to the 'trunk/extensions/' directory, 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 'extensions/' directory. Because of inconsistencies in browser XSLT implementations, certain formatting (e.g., table layouts and the numbering of tables, examples, and footnotes) may 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>&lt;<link url="http://www.xml.com/pub/a/tools/ruwf/check.html">http://www.xml.com/pub/a/tools/ruwf/check.html</link>&gt;</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 do 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, ask the XMPP Extensions Editor to add them for you.</p>
@ -111,7 +111,7 @@
<p>The &lt;example/&gt; and &lt;code/&gt; elements are used to show protocol snippets; the &lt;example/&gt; element SHOULD possess a 'caption' attribute that describes the example, whereas the &lt;code/&gt; element does not. Define an XML CDATA section within both of these elements so that you do not need to escape the '&lt;' and '&gt;' 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 &lt;p/&gt; and &lt;li/&gt; elements can also contain more markup that is familiar from XHTML, such as the &lt;img/&gt; element. Note that hyperlinks are of the form &lt;link url='foo'&gt;bar&lt;/link&gt; rather than &lt;a href='foo'&gt;bar&lt;/a&gt;; 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 &lt;em/&gt;, &lt;strong/&gt;, &lt;tt/&gt;, &lt;cite/&gt;, and &lt;span/&gt; within the &lt;p/&gt; and &lt;li/&gt; elements. </p>
<p>You may also include tables (these are helpful for listing error codes and such). The &lt;table/&gt; element SHOULD possess a 'caption' attribute that describes the table's contents. Standard XHTML table structure applies (&lt;tr/&gt; defines a row, which contains &lt;th/&gt; elements for header rows and &lt;td/&gt; 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>
<p>In fact, 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 CVS.</p>
<p>In fact, 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>
</section2>
</section1>
<section1 topic='The Sections of a XEP Document' anchor='sections'>