moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 23:28:51 -05:00
Code Issues Releases Wiki Activity

Use of definition list for glossary, best practice on table usage and reminder on PDF publications.

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@4102 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Tobias Markmann 2010-03-18 17:31:08 +00:00
parent 3b7b75503a
commit 732073d306
1 changed files with 10 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
xep-0143.xml
View File

@ -11,6 +11,7 @@
&LEGALNOTICE;
<number>0143</number>
<status>Active</status>
<interim/>
<type>Procedural</type>
<sig>Standards</sig>
<approver>Council</approver>
@ -21,6 +22,12 @@
<supersededby/>
<shortname>N/A</shortname>
&stpeter;
<revision>
<version>1.1rc1</version>
<date>2010-02-12</date>
<initials>tm</initials>
<remark><p>Use of definition list for glossary, best practice on table usage and reminder on PDF publications.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2004-12-09</date>
@ -109,8 +116,9 @@
<p>Aside from the metadata in the &lt;header/&gt; element (see above), a XEP file is a series of sections, arranged in a hierarchy (&lt;section1/&gt; is a top-level section, within which you can nest &lt;section2/&gt; sections, and so on down to &lt;section4/&gt;). 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: &lt;p/&gt; for paragraphs, &lt;ol/&gt; and &lt;ul/&gt; for ordered and unordered lists, and so on.</p>
<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>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. However keep in mind that tables weren't mend to display huge amount of text.</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>
<p>While HTML being the primary publishing format for XEPs, the XSF Editor also publishes XEPs in form of PDF since 2010. Keeping that in mind you should try to avoid tables with too much columns which require more width available on paper.</p>
</section2>
</section1>
<section1 topic='The Sections of a XEP Document' anchor='sections'>
@ -130,6 +138,7 @@
</section2>
<section2 topic='Glossary' anchor='sections-glossary'>
<p>If your XEP document uses terms that may not be familiar to the reader, please define them in a glossary.</p>
<p>The preferred layout for a glossary is a definition list using the HTML &lt;dl&gt;-tag.</p>
</section2>
<section2 topic='Use Cases' anchor='sections-usecases'>
<p>It is recommended that document authors structure their proposals according to the use cases that the proposal will address. <note>A good introduction to use cases may be found at &lt;<link url="http://www.pols.co.uk/usecasezone/">http://www.pols.co.uk/usecasezone/</link>&gt;.</note> We have found that use cases force authors to focus on functionality rather than "protocol for the sake of protocol". It is also helpful to sort use cases by actor, as is done in &xep0045;, for example. Include one subsection for each use case.</p>