<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Writing I-Ds and RFCs using XML</title>
    <style type="text/css">
        .style1
        {
            width: 100%;
        }
        .style2
        {
            height: 26px;
        }
        </style>
</head>
<body>

<h1 class="title">
    Writing I-Ds and RFCs using XML
</h1>



    <p>
        This memo presents a technique for using HTML
     
        as a source format for documents in the Internet-Drafts (I-Ds) and Request for 
        Comments (RFC) series.</p>
    <dl>
        <dt>Author</dt>
        <dd>
            Phillip Hallam-Baker</dd>
        <dt>Organization</dt>
        <dd>
            Comodo Group Inc.</dd>
        <dt>Email</dt>
        <dd>
            philliph@comodo.com</dd>
    </dl>
    <p>
    </p>
    <dl>
        <dt>Area</dt>
        <dd>
            General</dd>
        <dt>Keyword</dt>
        <dd>
            RFC</dd>
        <dt>Keyword</dt>
        <dd>
            Request For Comments</dd>
        <dt>Keyword</dt>
        <dd>
            I-D</dd>
        <dt>Keyword</dt>
        <dd>
            Internet-Draft</dd>
        <dt>Keyword</dt>
        <dd>
            XML</dd>
        <dt>Keyword</dt>
        <dd>Extensible Markup Language</dd>
        <dt>IPR</dt>
        <dd>full</dd>
    </dl>
    <h1>
        Introduction</h1>
    <p>
        Why are we kidding ourtselves? The current options for editing Internet drafts 
        suck.</p>
    <p>
        The existing XML format described in [RFC2629] was a big improvement on 
        authoring drafts in nroff but there are almost no tools capable of editing the 
        format at the document level. Editing the raw document tags is an excrutiating 
        process. There is no consistency in the DTD, sometimes a property is expressed 
        as an attribute, sometimes an element is used. The choice of element tags is 
        capricious and the only rule that appears to be consistently followed is that on 
        no account should the DTD make use of existing conventions in HTML. 
    </p>
    <p>
        HTML is the most widely used document format in recorded history with unrivalled 
        support in text editing tools. There are more documents archived in HTML than 
        any other format including paper. There is no circumstance short of a complete 
        collapse of modern civilization in which loss of the ability to read HTML files 
        is conceivable. And even if such a loss were to occur, the decoding of Linear B, 
        Myan hieroglyphs and the ENIGMA codes were successfully completed with vastly 
        fewer examples to work from.</p>
    <h2>
        Editing in Limited HTML</h2>
    <p>
        The main objection to using HTML to edit RFCs is that the HTML specification is 
        very large and complicated. It is a presentation format and not limited to use 
        as a source format.</p>
    <p>
        The solution to this objection is simple: Use a document preparation tool that 
        ignores all the unnecessary material that many HTML editors see fit to insert. 
        These may mean that there are some document preparation tools that are 
        unsuitable but the important criteria for choosing a document format is that 
        there should be plenty of tools available that support editing in that format 
        and not that every tool capable of emitting that format be capable of being used 
        as an editor.</p>
    <p>
        The format described in this document uses a limited subset of HTML tags to
        write a source format that may be converted to [RFC2629] format by automated 
        tools and might in furture also generate the plaintext and other formats 
        accepted by the IETF. The tags used in the limited subset are:</p>
    <dl>
        <dt>&lt;h1&gt;, &lt;h2&gt;, ... &lt;h6&gt;</dt>
        <dd>
            Section delimeters</dd>
        <dt>&lt;p&gt;</dt>
        <dd>
            Paragraph section</dd>
        <dt>&lt;em&gt;, &lt;i&gt;, &lt;b&gt;</dt>
        <dd>
            Emphasis</dd>
        <dt>&lt;dl&gt;, &lt;dt&gt;, &lt;dd&gt;</dt>
        <dd>
            Identify document attributes when occuring in the front matter and tagged lists 
            elsewhere.</dd>
        <dt>&lt;ul&gt;, &lt;ol&gt;, &lt;li&gt;</dt>
        <dd>
            Bulleted and ordered lists</dd>
        <dt>&lt;table&gt;, &lt;tr&gt; &lt;td&gt;</dt>
        <dd>
            Tables</dd>
        <dt>&lt;pre&gt;</dt>
        <dd>
            Figures</dd>
    </dl>
    <p>
        Using these tags without additional markup is sufficient to support 80% of the 
        functionality of the XML2RFC format and 90% of the functionality that is useful. 
        The main missing functionality is support for citations in other documents.
    </p>
    <h3>
        Citations</h3>
    <p>
        Any text occuring in square brackets [[] is a citation label. To use square 
        brackets that do not declare a citation, the first bracket is doubled thus [[[[ 
        this is not a citation ].</p>
    <p>
        If the citation label is preceded by an exclamation point, the reference is 
        normative, otherwise the reference is not-normative.</p>
    <p>
        The following citation label forms are recognized as special and are interpreted 
        by the tool directly:</p>
    <dl>
        <dt>RFC&lt;number&gt;</dt>
        <dd>
            Request for Comments RFC &lt;number&gt;</dd>
        <dt>draft-&lt;name&gt;</dt>
        <dd>
            Internet Draft draft-&lt;name&gt;</dd>
    </dl>
    <p>
        All other citation labels are resolved by reference to an external bibliography 
        which should support all popular citation formats, i.e. scribe, XML2RFC.</p>
    <p>
        Adding this limited internal markup is sufficient to support all the 
        functionality I have used in the 30+ Internet drafts I have written in the past 
        five years.</p>
    <h3>
        External Files</h3>
    <p>
        Many documents contain examples, schemas, example code, etc. that are edited or 
        generated separately from the document source. XML processing directives are 
        used to incorporate material from external files:</p>
    <dl>
        <dt>&lt;?include html=&quot;filename.html?&quot;&gt;</dt>
        <dd>
            Include material from the specified html source file. The source material will 
            be read as if it was text occuring in the input document.</dd>


                <dt>&lt;?include xml=&quot;filename.xml?&quot;&gt;</dt>
        <dd>
            Include material from the specified xml source file into the output document.
        </dd>


        <dt>&lt;?bibliography xml=&quot;filename.xml&quot;&gt;</dt>
        <dd>
            Use the specified file as a source of references in xml2rfc format.</dd>


        <dt>&lt;?bibliography bibtex=&quot;filename.xml&quot;&gt;</dt>
        <dd>
            Use the specified file as a source of references in scribe/bibtex format.</dd>


        <dt>&lt;?bibliography csl=&quot;filename.xml&quot;&gt;</dt>
        <dd>
            Use the specified file as a source of references in CSL format.</dd>
    </dl>
    <h1>
        HTML2RFC for XML2RFC users</h1>
    <p>
        HTML2RFC follows the same front/middle/back organization as XML2RFC except that 
        the boundaries between these sections are defined using H1 tags as follows:</p>
    <ul>
        <li>The first H1 element marks the start of the front matter</li>
        <li>The second H1 element marks the start of the middle matter</li>
        <li>The first H1 element with a class attribute of &quot;Appendix&quot; marks the start of 
            the back matter</li>
    </ul>
    <h2>
        Front</h2>
    <p>
        The first element in the body of the document MUST be the H1 element that marks 
        the start of the front matter. The only valid toplevel elements in the front 
        section are &lt;h1&gt;, &lt;p&gt; and &lt;dl&gt;. These elements are interpreted as follows</p>
    <p>
        The content of the &lt;H1&gt; specifies the title of the document.</p>
    <p>
        All &lt;p&gt; elements in the front matter specify the document abstract unless they 
        contain only empty space in which case they are ignored.</p>
    <p>
        The &lt;dl&gt; element specifies a list of tag value pairs that define the document 
        authors, keywords, etc. Each &lt;dt&gt; element contains a case insensitive label that 
        defines a document property that is set by the following &lt;dd&gt; element(s) as 
        follows:</p>
    <table class="style1">
        <tr>
            <td>
                dt</td>
            <td>
                XML2RFC Equivalent</td>
            <td>
                dd</td>
        </tr>
        <tr>
            <td>
                author</td>
            <td>
                &lt;author&gt;</td>
            <td>
                Author&#39;s Name</td>
        </tr>
        <tr>
            <td>
                organization</td>
            <td>
                &lt;author&gt;&lt;organization&gt;</td>
            <td>
                Author&#39;s Organization</td>
        </tr>
        <tr>
            <td>
                street</td>
            <td>
                &lt;author&gt;&lt;postal&gt;&lt;street&gt;</td>
            <td>
                Author&#39;s Address</td>
        </tr>
        <tr>
            <td>
                city</td>
            <td>
                &lt;author&gt;&lt;postal&gt;&lt;city&gt;</td>
            <td>
                Author&#39;s Address</td>
        </tr>
        <tr>
            <td>
                code</td>
            <td>
                &lt;author&gt;&lt;postal&gt;&lt;code&gt;</td>
            <td>
                Author&#39;s Address</td>
        </tr>
        <tr>
            <td class="style2">
                country</td>
            <td class="style2">
                &lt;author&gt;&lt;postal&gt;&lt;country&gt;</td>
            <td class="style2">
                Author&#39;s Address</td>
        </tr>
        <tr>
            <td>
                phone</td>
            <td>
                &lt;author&gt;&lt;phone&gt;</td>
            <td>
                Author&#39;s Contact</td>
        </tr>
        <tr>
            <td>
                email</td>
            <td>
                &lt;author&gt;&lt;email&gt;</td>
            <td>
                Author&#39;s Email</td>
        </tr>
        <tr>
            <td>
                uri</td>
            <td>
                &lt;author&gt;&lt;uri&gt;</td>
            <td>
                Author&#39;s URI</td>
        </tr>
        <tr>
            <td class="style2">
                area</td>
            <td class="style2">
                &lt;area&gt;</td>
            <td class="style2">
                IETF area</td>
        </tr>
        <tr>
            <td>
                workgroup</td>
            <td>
                &lt;workgroup&gt;</td>
            <td>
                IETF Working Group (optional)</td>
        </tr>
        <tr>
            <td>
                ipr</td>
            <td>
                &lt;rfc ipr=&quot;&quot;&gt;</td>
            <td>
                IPR, valid values are those specified in xml2rfc</td>
        </tr>
        <tr>
            <td>
                docname</td>
            <td>
                &lt;rfc docName=&quot;&quot;&gt;</td>
            <td>
                Document name</td>
        </tr>
        <tr>
            <td>
                abrrev</td>
            <td>
                &lt;title abbrev=&quot;&quot;&gt;</td>
            <td>
                Abrreviated title</td>
        </tr>
    </table>
    <p>
        The organization, street, city, etc. properties are only valid when following an 
        author property and apply only to the preceeding author.</p>
    <h2>
        Middle</h2>
    <p>
        The second H1 element marks the start of the middle matter. HTML headings &lt;h1&gt; 
        through &lt;h6&gt; in the middle section cause the processor to emit the requisite 
        nested &lt;section&gt; elements. </p>
    <h3>
        Anchors</h3>
    <p>
        The Id attribute may be used to declare anchors within the document. Cross 
        references within the document are created using HTML anchors with the 
        traditional fragment syntax &lt;a href=&quot;#whatever&quot;&gt;Whatever&lt;/a&gt;. Text occurring 
        inside such anchors is considered to be a comment for the benefit of the 
        document author and is ignored. </p>
    <h3>
        Lists</h3>
    <p>
        The HTML list elements &lt;dl&gt;, &lt;ul&gt; and &lt;ol&gt; replace the list styles &quot;numbers&quot;, 
        &quot;symbols&quot; and &quot;hanging&quot;. The content of a &lt;dt&gt; element becomes the value of the 
        hangText element in the corresponding paragraph.</p>
    <h3>
        Tables</h3>
    <p>
        The standard HTML table tags are used for the normal purposes but the rowspan 
        and colspan attributes are not supported.</p>
    <h3>
        Emphasis in text</h3>
    <p>
        <strong>&lt;strong&gt; elements (Bold font) MAY be used to identify normative language 
        inside the document</strong>. If the processing tool encounters &lt;strong&gt; 
        elements, it will add an appendix that contains a list of all the normative text 
        sections broken down according to MUST/SHALL, SHOULD, RECOMMENDED and MAY types.</p>
    <p>
        &lt;i&gt; elements (italic font) MAY be used to identify terms with a meaning defined 
        in the text.</p>
    <h2>
        Back</h2>
    <p>
        The first &lt;h1&gt; element with a class attribute of &quot;Appendix&quot; marks the start of 
        the back matter. Marking the end of the middle section is only necessary if a 
        document has appendices. The tool will automatically insert a references section 
        in any document where citations are found.</p>
    <p>
        It is only necessary to mark the first appendix with the class attribute. The 
        text in the back section is processed in the same way as material in the middle 
        except that sections will be numbered as Appendix A, Appendix B, etc. instead of 
        numbered sections.</p>
    <h2>
        Formatting options</h2>
    <p>
        HTML2RFC provides the author with no (zero) control over the formatting of the 
        result whatsoever. The document will have a table of contents whether the author 
        wants one or not because I find documents without one impossible to read. 
        Citations in the text will use symbolic references because following references 
        of the form [[1] in a large online document is painful in the extreme.</p>
    <p>
        Apart from the class=&quot;appendix&quot; attribute mentioned earlier, HTML style in the 
        document is ignored.</p>

        
 

</body>
</html>