<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc [
  <!ENTITY nbsp    "&#160;">
  <!ENTITY zwsp   "&#8203;">
  <!ENTITY nbhy   "&#8209;">
  <!ENTITY wj     "&#8288;">
]>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902" category="info" docName="draft-gieben-writing-rfcs-pandoc-02" obsoletes="" updates="" submissionType="IETF" xml:lang="en" tocInclude="true" symRefs="true" sortRefs="true" version="3">
  <!-- xml2rfc v2v3 conversion 3.8.0 -->
  <!--generate a table of contents -->
   <!--use anchors instead of numbers for references -->
   <!--alphabetize the references -->
   <!--conserve vertical whitespace -->
   <!--but keep a blank line between list items -->
   <?v3xml2rfc silence="The document date .*? is more than 3 days away from today's date" ?>
   <front>
    <title abbrev="Pandoc2rfc Version 2">Writing I-Ds and RFCs using Pandoc and xml2rfc 2.x</title>
    <seriesInfo name="Internet-Draft" value="draft-gieben-writing-rfcs-pandoc-02"/>
    <author initials="R." surname="Gieben" fullname="R. (Miek) Gieben">
      <organization>Google</organization>
      <address>
        <postal>
          <street>123 Buckingham Palace Road</street>
          <street/>
          <city>London</city>
          <region/>
          <code>SW1W 9SH</code>
          <country>UK</country>
        </postal>
        <phone/>
        <email>miek@miek.nl</email>
        <uri>http://miek.nl/</uri>
      </address>
    </author>
    <date month="January" year="2013" day="1"/>
    <area>General</area>
    <workgroup>RFC Beautification Working Group</workgroup>
    <keyword>RFC</keyword>
    <keyword>Request for Comments</keyword>
    <keyword>I-D</keyword>
    <keyword>Internet-Draft</keyword>
    <keyword>XML</keyword>
    <keyword>Pandoc</keyword>
    <keyword>Extensible Markup Language</keyword>
    <abstract>
      <t>
            This memo presents a technique for using Pandoc syntax as a source
            format for documents in the Internet-Drafts (I-Ds) and Request for
            Comments (RFC) series.  
      </t>
      <t>
            This version is adapted to work with "xml2rfc" version 2.x.  
      </t>
    </abstract>
  </front>
  <middle>
    <!--This document was prepared using Pandoc2rfc https://github.com/miekg/pandoc2rfc -->
      <section anchor="introduction" toc="default" numbered="true">
      <name>Introduction</name>
      <t>
            This document presents a technique for using Pandoc syntax as a
            source format for documents in the Internet-Drafts (I-Ds) and
            Request for Comments (RFC) series.  
      </t>
      <t>
            This version is adapted to work with
            <tt>xml2rfc</tt> version 2.x.  
      </t>
      <t>
            Pandoc is an "almost plain text" format and therefor particularly
            well suited for editing RFC-like documents.  
      </t>
      <ul empty="true" spacing="normal">
        <li>
                  Note: this document is typeset in Pandoc and does not render
                  completely correct when reading it on github.  
               </li>
      </ul>
    </section>
    <section anchor="pandoc-to-rfc" toc="default" numbered="true">
      <name>Pandoc to RFC</name>
      <ul empty="true" spacing="normal">
        <li>
                  Pandoc2rfc -- designed to do the right thing, until it doesn't.  
               </li>
      </ul>
      <t>
            When writing <xref target="RFC4641" format="default"/>
            we directly wrote the XML. Needless to say it was tedious even thought
            the XML of <eref target="http://xml.resource.org/experimental">xml2rfc</eref>
            is very "light". The
            <eref target="http://pypi.python.org/pypi/xml2rfc/">latest version of xml2rfc version 2 can be found here</eref>.  
      </t>
      <t>
            During the last few years people have been developing markup
            languages that are very easy to remember and type. These languages
            have become known as
            <tt>almost plain
            text</tt>-markup languages.  One of the first was the
            <eref target="http://daringfireball.net/projects/markdown/">Markdown</eref>
            syntax. One that was developed later and incorporates Markdown and
            a number of extensions is
            <eref target="http://johnmacfarlane.net/pandoc/">Pandoc</eref>. The
            power of Pandoc also comes from the fact that it can be translated
            to numerous output formats, including, but not limited to: HTML,
            (plain) Markdown and
            <tt>docbook</tt> XML.  
      </t>
      <t>
            So using Pandoc for writing RFCs seems like a sane choice. As
            <tt>xml2rfc</tt> uses XML,
            the easiest way would be to create
            <tt>docbook</tt>
            XML and transform that using XSLT.  Pandoc2rfc does just that. The
            conversions are, in some way amusing, as we start off with
            (almost) plain text, use elaborate XML and end up with plain text
            again.  
      </t>
      <figure anchor="fig-attempt-to">
        <name>Attempt to justify Pandoc2rfc.</name>
        <artwork name="" type="" align="left" alt=""><![CDATA[
+-------------------+   pandoc   +---------+  
| ALMOST PLAIN TEXT |   ------>  | DOCBOOK |  
+-------------------+            +---------+  
              |                       |
non-existent  |                       | xsltproc
  faster way  |                       |
              v                       v
      +------------+    xml2rfc  +---------+ 
      | PLAIN TEXT |  <--------  | XML2RFC | 
      +------------+             +---------+ 
            ]]></artwork>
      </figure>
      <t>
            The XML generated (the output after the
            <tt>xsltproc</tt> step in
            <xref target="fig-attempt-to" format="default"/>)
            is suitable for inclusion in either the
            <tt>middle</tt> or
            <tt>back</tt> section of
            an RFC.  The simplest way is to create a template XML file and
            include the appropriate XML: 
      </t>
      <figure anchor="fig-a-minimal-">
        <name>A minimal template.xml.</name>
        <artwork name="" type="" align="left" alt=""><![CDATA[
<?xml version='1.0' ?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
<!ENTITY pandocMiddle PUBLIC '' 'middle.xml'>
<!ENTITY pandocBack   PUBLIC '' 'back.xml'>
]>

<rfc ipr='trust200902' docName='draft-gieben-pandoc-rfcs-02'>
 <front>
    <title>Writing I-Ds and RFCs using Pandoc v2</title>
</front>

<middle>
    &pandocMiddle;
</middle>

<back>
    &pandocBack;
</back>

</rfc>
            ]]></artwork>
      </figure>
      <t>
            See the Makefile for an example of this. In this case you need to
            edit 3 documents: 
      </t>
      <ol spacing="normal" type="1"><li>
                  middle.pdc - contains the main body of text; 
               </li>
        <li>
                  back.pdc - holds appendices and references; 
               </li>
        <li>
                  template.xml (probably a fairly static file).  
               </li>
      </ol>
      <t>
            The draft
	    (<tt>draft.txt</tt>) you
            are reading now, is automatically created when you call
            <tt>make</tt>. The
            homepage of Pandoc2rfc is
            <eref target="https://github.com/miekg/pandoc2rfc">this github
            repository</eref>.  
      </t>
      <section anchor="dependencies" toc="default" numbered="true">
        <name>Dependencies</name>
        <t>
               It needs <tt>xsltproc</tt>
               and <tt>pandoc</tt> to be
               installed. See the
               <eref target="http://johnmacfarlane.net/pandoc/README.html">Pandoc
               user manual for the details</eref> on how to type in Pandoc style.
               And of course <tt>xml2rfc</tt>
               version two.  
        </t>
        <t>
               When using Pandoc2rfc consider adding the following sentence to
               an Acknowledgements section: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
 This document was produced using the Pandoc2rfc tool.
               ]]></artwork>
      </section>
    </section>
    <section anchor="starting-a-new-project" toc="default" numbered="true">
      <name>Starting a new project</name>
      <t>
            When starting a new project with
            <tt>pandoc2rfc</tt> you'll
            need to copy the following files: 
      </t>
      <ul spacing="normal">
        <li>
          <tt>Makefile</tt>
        </li>
        <li>
          <tt>transform.xslt</tt>
        </li>
        <li>
          <t>
                  And the above mentioned files: </t>
          <ul spacing="normal">
            <li>
              <tt>middle.pdc</tt>
            </li>
            <li>
              <tt>back.pdc</tt>
            </li>
            <li>
              <tt>template.xml</tt>
            </li>
          </ul>
        </li>
      </ul>
      <t>
            After that you can start editing.  
      </t>
    </section>
    <section anchor="supported-features" toc="default" numbered="true">
      <name>Supported Features</name>
      <ul spacing="normal">
        <li>
                  Sections with an anchor and title attributes
		  (<xref target="section" format="default"/>); 
               </li>
        <li>
          <t>
                  Lists </t>
          <ul spacing="normal">
            <li>
                        style=symbols (<xref target="symbol" format="default"/>); 
                     </li>
            <li>
                        style=numbers (<xref target="number" format="default"/>); 
                     </li>
            <li>
                        style=empty (<xref target="empty" format="default"/>); 
                     </li>
            <li>
                        style=format %i, use roman lowercase numerals, (<xref target="roman" format="default"/>); 
                     </li>
            <li>
                        style=format (%d), use roman uppercase numerals (<xref target="roman" format="default"/>); 
                     </li>
            <li>
                        style=letters (lower- and uppercase, <xref target="letter" format="default"/>); 
                     </li>
            <li>
                        style=hanging (<xref target="hanging" format="default"/>); 
                     </li>
          </ul>
        </li>
        <li>
                  Figure/artwork with a title (<xref target="figureartwork" format="default"/>); 
               </li>
        <li>
                  Block quote this is converted to
                  <tt>&lt;list style="empty"&gt;</tt>
                  paragraph (<xref target="block-quote" format="default"/>); 
               </li>
        <li>
          <t>
                  References </t>
          <ul spacing="normal">
            <li>
                        external (eref) (<xref target="external" format="default"/>); 
                     </li>
            <li>
              <t>
                        internal (xref) (<xref target="internal" format="default"/>), you can refer to: </t>
              <ul spacing="normal">
                <li>
                              section (handled by Pandoc, see <xref target="references-1" format="default"/>)); 
                           </li>
                <li>
                              figures (handled by XSLT, see <xref target="references" format="default"/>); 
                           </li>
                <li>
                              tables (handled by XSLT, see <xref target="references-2" format="default"/>).  
                           </li>
              </ul>
            </li>
          </ul>
        </li>
        <li>
                  Citations, by using internal references; 
               </li>
        <li>
                  Spanx style=verb, style=emph and style=strong (<xref target="spanx-styles" format="default"/>); 
               </li>
        <li>
                  Tables with an anchor and title (<xref target="tables" format="default"/>); 
               </li>
        <li>
                  Indexes, by using footnotes (<xref target="indexes" format="default"/>).  
               </li>
      </ul>
    </section>
    <section anchor="unsupported-features" toc="default" numbered="true">
      <name>Unsupported Features</name>
      <ul spacing="normal">
        <li>
                  Lists inside a table (<tt>xml2rfc</tt> doesn't handle this); 
               </li>
        <li>
                  Pandoc markup in the caption for figures/artwork. Pandoc markup for table captions <em>is</em> supported; 
               </li>
        <li>
                  crefs: for comments (no input syntax available), use HTML comments: <tt>&lt;!-- ... --&gt;</tt>; 
               </li>
      </ul>
    </section>
    <section anchor="acknowledgements" toc="default" numbered="true">
      <name>Acknowledgements</name>
      <t>
            The following people have helped to make Pandoc2rfc what it is today: Benno Overeinder, Erlend Hamnaberg, Matthijs Mekking, Trygve Laugstoel.  
      </t>
      <t>
            This document was prepared using Pandoc2rfc.  
      </t>
    </section>
    <section anchor="pandoc-constructs" toc="default" numbered="true">
      <name>Pandoc Constructs</name>
      <t>
            So, what syntax do you need to use to get the correct output? Well, it is
            <em>just</em> Pandoc. The best introduction
            to the Pandoc style is given in this
            <eref target="http://johnmacfarlane.net/pandoc/README.html">README from Pandoc itself</eref>.  
      </t>
      <t>
            For convenience we list the most important ones in the following sections.  
      </t>
      <section anchor="paragraph" toc="default" numbered="true">
        <name>Paragraph</name>
        <t>
               Paragraphs are separated with an empty line.  
        </t>
      </section>
      <section anchor="section" toc="default" numbered="true">
        <name>Section</name>
        <t>
               Just use the normal sectioning commands available in Pandoc, for instance: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
# Section1 One
Bla
               ]]></artwork>
        <t>
               Converts to: <tt>&lt;section title="Section1
               One" anchor="section1-one"&gt;</tt> If you have another section that is also
               named "Section1 One", that anchor will be called "section1-one-1", but
               <em>only</em> when the sections are in
               the <em>same</em> source file! 
        </t>
        <t>
               Referencing the section is done with <tt>see
               [](#section1-one)</tt>, as in see <xref target="section" format="default"/>.  
        </t>
      </section>
      <section anchor="list-styles" toc="default" numbered="true">
        <name>List Styles</name>
        <t>
               A good number of styles are supported.  
        </t>
        <section anchor="symbol" toc="default" numbered="true">
          <name>Symbol</name>
          <artwork name="" type="" align="left" alt=""><![CDATA[
A symbol list.

* Item one;
* Item two.
                  ]]></artwork>
          <t>
                  Converts to <tt>&lt;list style="symbol"&gt;</tt>: 
          </t>
          <ul spacing="normal">
            <li>
                        Item one; 
                     </li>
            <li>
                        Item two.  
                     </li>
          </ul>
        </section>
        <section anchor="number" toc="default" numbered="true">
          <name>Number</name>
          <artwork name="" type="" align="left" alt=""><![CDATA[
A numbered list.

1. Item one;
1. Item two.
                  ]]></artwork>
          <t>
                  Converts to <tt>&lt;list style="numbers"&gt;</tt>: 
          </t>
          <ol spacing="normal" type="1"><li>
                        Item one; 
                     </li>
            <li>
                        Item two.  
                     </li>
          </ol>
        </section>
        <section anchor="empty" toc="default" numbered="true">
          <name>Empty</name>
          <t>
                  Using the default list markers from Pandoc: 
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
A list using the default list markers.

#. Item one;
#. Item two.
                  ]]></artwork>
          <t>
                  Converts to <tt>&lt;list style="empty"&gt;</tt>: 
          </t>
          <ul empty="true" spacing="normal">
            <li>
                        Item one; 
                     </li>
            <li>
                        Item two.  
                     </li>
          </ul>
        </section>
        <section anchor="roman" toc="default" numbered="true">
          <name>Roman</name>
          <t>
                  Use the supported Pandoc syntax: 
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
ii. Item one;
ii. Item two.
                  ]]></artwork>
          <t>
                  Converts to <tt>&lt;list style="format %i."&gt;</tt>: 
          </t>
          <ol spacing="normal" type="%i."><li>
                        Item one; 
                     </li>
            <li>
                        Item two.  
                     </li>
          </ol>
          <t>
                  If you use uppercase Roman numerals, they convert to a different style: 
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
II. Item one;
II. Item two.
                  ]]></artwork>
          <t>
                  Yields <tt>&lt;list style="format (%d) "&gt;</tt>: 
          </t>
          <ol spacing="normal" type="(%d)"><li>
                        Item one; 
                     </li>
            <li>
                        Item two.  
                     </li>
          </ol>
        </section>
        <section anchor="letter" toc="default" numbered="true">
          <name>Letter</name>
          <t>
                  A numbered list.  
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
a.  Item one;
b.  Item two.
                  ]]></artwork>
          <t>
                  Converts to <tt>&lt;list style="letters"&gt;</tt>: 
          </t>
          <ol spacing="normal" type="a"><li>
                        Item one; 
                     </li>
            <li>
                        Item two.  
                     </li>
          </ol>
          <t>
                  Uppercasing the letters works too (note two spaces after the letter.  
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
A.  Item one;
B.  Item two.
                  ]]></artwork>
          <t>
                  Becomes: 
          </t>
          <ol spacing="normal" type="%C."><li>
                        Item one; 
                     </li>
            <li>
                        Item two.  
                     </li>
          </ol>
        </section>
        <section anchor="hanging" toc="default" numbered="true">
          <name>Hanging</name>
          <t>
                  This is more like a description list, so we need to use: 
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
First item that needs clarification:

:   Explanation one
More stuff, because item is difficult to explain.
* item1
* item2

Second item that needs clarification:

:   Explanation two
                  ]]></artwork>
          <t>
                  Converts to: <tt>&lt;list style="hanging"&gt;</tt> and <tt>&lt;t hangText="First item that..."&gt;</tt>
          </t>
          <t>
                  If you want a newline after the hangTexts, search for the string <tt>OPTION</tt> in <tt>transform.xsl</tt> and uncomment it.  
          </t>
        </section>
      </section>
      <section anchor="figureartwork" toc="default" numbered="true">
        <name>Figure/Artwork</name>
        <t>
               Indent the paragraph with 4 spaces.  
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
Like this
               ]]></artwork>
        <t>
               Converts to:
               <tt>&lt;figure&gt;&lt;artwork&gt; ...</tt>
               Note that <tt>xml2rfc</tt>
               supports a caption with
               <tt>&lt;artwork&gt;</tt>. Pandoc does not
               support this, but Pandoc2rfc does. If you add a
               <tt>@Figure: some text</tt> as the last
               line, the artwork gets a <tt>title</tt>
               attribute with the text after
               <tt>@Figure:</tt>. It will also be
               possible to reference the artwork. If a caption is supplied the artwork will be
               centered. If a caption is needed but the figure should not be centered use
               <tt>@figure:\</tt>.  
        </t>
        <section anchor="references" toc="default" numbered="true">
          <name>References</name>
          <t>
                  The reference anchor attribute will be: <tt>fig:</tt>
                  + <tt>first 10 (normalized) characters from the caption</tt>.
                  Where normalized means: 
          </t>
          <ul spacing="normal">
            <li>
                        Take the first 10 characters of the caption (i.e. this is the text
                        <em>after</em> the string
                        <tt>@Figure:</tt>); 
                     </li>
            <li>
                        Spaces and single quotes (') are translated to a minus
                        <tt>-</tt>; 
                     </li>
            <li>
                        Uppercase letters translated to lowercase.  
                     </li>
          </ul>
          <t>
                  So the first artwork with a caption will get
                  <tt>fig:a-minimal-</tt>
                  as a reference. See for instance
                  <xref target="fig-a-minimal-" format="default"/>.  
          </t>
          <t>
                  This anchoring is completely handled from within the
                  <tt>xslt</tt>.
                  Note that duplicate anchors are an XML validation error which will make
                  <tt>xml2rfc</tt> fail.  
          </t>
        </section>
      </section>
      <section anchor="block-quote" toc="default" numbered="true">
        <name>Block Quote</name>
        <t>
               Any paragraph like: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
> quoted text
               ]]></artwork>
        <t>
               Converts to: <tt>&lt;t&gt;&lt;list style="empty"&gt; ...</tt>
               paragraph, making it indented.  
        </t>
      </section>
      <section anchor="references-1" toc="default" numbered="true">
        <name>References</name>
        <section anchor="external" toc="default" numbered="true">
          <name>External</name>
          <t>
                  Any reference like: 
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
[Click here](URI)
                  ]]></artwork>
          <t>
                  Converts to: <tt>&lt;ulink target="URI"&gt;Click here ...</tt>
          </t>
        </section>
        <section anchor="internal" toc="default" numbered="true">
          <name>Internal</name>
          <t>
                  Any reference like: 
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
[Click here](#localid)
                  ]]></artwork>
          <t>
                  Converts to: <tt>&lt;link target="localid"&gt;Click here ...</tt>
          </t>
          <t>
                  For referring to RFCs (for which you manually need add the reference source in
                  the template, with an external XML entity), you can just use: 
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
[](#RFC2119)
                  ]]></artwork>
          <t>
                  And it does the right thing. Referencing sections is done with: 
          </t>
          <artwork name="" type="" align="left" alt=""><![CDATA[
See [](#pandoc-constructs)
                  ]]></artwork>
          <t>
                  The word 'Section' is inserted automatically: ... see
                  <xref target="pandoc-constructs" format="default"/>
                  ... For referencing figures/artworks see
                  <xref target="figureartwork" format="default"/>.
                  For referencing tables see <xref target="tables" format="default"/>.  
          </t>
        </section>
      </section>
      <section anchor="spanx-styles" toc="default" numbered="true">
        <name>Spanx Styles</name>
        <t>
               The verb style can be selected with back-tics:
               <tt>`text`</tt>
               Converts to:
               <tt>&lt;spanx style="verb"&gt; ...</tt>
        </t>
        <t>
               And the emphasis style with asterisks:
               <tt>*text*</tt>
               or underscores: <tt>_text_</tt>
               Converts to: <tt>&lt;spanx style="emph"&gt; ...</tt>
        </t>
        <t>
               And the emphasis style with double asterisks:
               <tt>**text**</tt>
               Converts to: <tt>&lt;spanx style="strong"&gt; ...</tt>
        </t>
      </section>
      <section anchor="tables" toc="default" numbered="true">
        <name>Tables</name>
        <t>
               A table can be entered as: 
        </t>
        <figure anchor="fig-a-caption-">
          <name>A caption describing the figure describing the table.</name>
          <artwork name="" type="" align="left" alt=""><![CDATA[
  Right     Left     Center     Default                                                                  
  -------   ------ ----------   -------                                                                  
       12     12        12        12                                                                   
      123     123       123       123                                                                   
        1     1         1         1       

  Table: A caption describing the table.
               ]]></artwork>
        </figure>
        <t>
               Is translated to <tt>&lt;texttable&gt;</tt>
               element in <tt>xml2rfc</tt>.
               You can choose multiple styles as input, but they all are converted to the same style (plain
               <tt>&lt;texttable&gt;</tt>) table in
               <tt>xml2rfc</tt>. The column alignment
               is copied over to the generated XML.  
        </t>
        <section anchor="references-2" toc="default" numbered="true">
          <name>References</name>
          <t>
                  The caption is <em>always</em>
                  translated to a <tt>title</tt>
                  attribute. If a table has a caption, it will
                  <em>also</em> get a reference.
                  The reference anchor attribute will be:
                  <tt>tab-</tt>
                  + <tt>first 10 (normalized) characters from the caption</tt>.
                  Where normalized means: 
          </t>
          <ul spacing="normal">
            <li>
                        Take the first 10 characters of the caption (i.e. this is the text
                        <em>after</em> the string
                        <tt>Table:</tt>); 
                     </li>
            <li>
                        Spaces and single quotes (') are translated to a minus
                        <tt>-</tt>; 
                     </li>
            <li>
                        Uppercase letters translated to lowercase.  
                     </li>
          </ul>
          <t>
                  So the first table with a caption will get
                  <tt>tab-a-caption-</tt>
                  for reference use. See for instance 
          </t>
          <t>
                  This anchoring is completely handled from within the
                  <tt>xslt</tt>.
                  Note that duplicate anchors are an XML validation error which will make
                  <tt>xml2rfc</tt> fail.  
          </t>
        </section>
      </section>
      <section anchor="indexes" toc="default" numbered="true">
        <name>Indexes</name>
        <t>
               The footnote syntax of Pandoc is slightly abused to support an index. Footnotes are entered in two steps, you have a marker in the text, and later you give actual footnote text. Like this: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
[^1]

[^1]: footnote text
               ]]></artwork>
        <t>
               We re-use this syntax for the <tt>&lt;iref&gt;</tt> tag.  The above text translates to: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
<iref item="footnote text"/>
               ]]></artwork>
        <t>
               Sub items are also supported. Use an exclamation mark (<tt>!</tt>) to separate them: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
[^1]: item!sub item
               ]]></artwork>
      </section>
    </section>
    <section anchor="usage-guidelines" toc="default" numbered="true">
      <name>Usage guidelines</name>
      <section anchor="working-with-multiple-files" toc="default" numbered="true">
        <name>Working with multiple files</name>
        <t>
               As an author you will probably break up a draft in multiple files, each dealing
               with a subject or section. When doing so sections with the same title will clash
               with each other. Pandoc can deal with this situation, but only if the different
               sections are in the <em>same</em> file or
               processed in the same Pandoc run. Concatenating the different section files
               before processing them is a solution to this problem. You can, for instance,
               amend the <tt>Makefile</tt> and add
               something like this: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
allsections.pdc: section.pdc.1 section.pdc.2 section.pdc.3
        cat $@ > allsections.pdc
               ]]></artwork>
        <t>
               And then process <tt>allsection.pdc</tt> in the normal way.  
        </t>
      </section>
      <section anchor="setting-the-title" toc="default" numbered="true">
        <name>Setting the title</name>
        <t>
               If you use double quotes in the documents title in the
               <tt>docName</tt> attribute, like: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
<rfc ipr="trust200902" docName="draft-gieben-writing-rfcs-pandoc-02">
               ]]></artwork>
        <t>
               The Makefile will pick this up automatically and make a symbolic link: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
draft-gieben-writing-rfcs-pandoc-00.txt -> draft.txt
               ]]></artwork>
        <t>
               This makes uploading the file to the i-d tracker a bit easier.  
        </t>
      </section>
      <section anchor="uploading-the-xmltxt" toc="default" numbered="true">
        <name>Uploading the XML/txt</name>
        <t>
               The <tt>draft.xml</tt> target will
               generate an XML file with all XML included, so you can upload just one file to
               the I-D tracker.  
        </t>
      </section>
      <section anchor="vim-syntax-highlighting" toc="default" numbered="true">
        <name>VIM syntax highlighting</name>
        <t>
               If you are a VIM user you might be interested in a syntax highlighting file (see
               <xref target="VIM" format="default"/>) that slightly lightens up
               your reading experience while viewing a draft.txt from VIM.  
        </t>
      </section>
    </section>
    <section anchor="security-considerations" toc="default" numbered="true">
      <name>Security Considerations</name>
      <t>
            This document raises no security issues.  
      </t>
    </section>
    <section anchor="iana-considerations" toc="default" numbered="true">
      <name>IANA Considerations</name>
      <t>
            This document has no actions for IANA.  
      </t>
    </section>
  </middle>
  <back>
    <references>
      <name>References</name>
      <references>
        <name>Informative References</name>
        <reference anchor="VIM" target="http://github.com/miekg/rfc">
          <front>
            <title abbrev="Syntax file for RFCs">VIM syntax file for RFCs and I-Ds</title>
            <author initials="R." surname="Gieben" fullname="R. (Miek) Gieben">
              <organization>Atoom Inc.</organization>
              <address>
                <email>miek@miek.nl</email>
              </address>
            </author>
            <date year="2012" month="October"/>
          </front>
        </reference>
      </references>
      <references>
        <name>Normative References</name>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4641.xml"/>
      </references>
      <references>
        <name>Informative References (by reference)</name>
        <!-- bibxml reference -->
        <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4941.xml"/><!-- bibxml-misc reference -->
        <reference anchor="ISO.8327.1990" xml:base="https://bib.ietf.org/public/rfc/bibxml-misc/reference.ISO.8327.1990.xml">
<front>
<title>Information processing systems - Open Systems Interconnection - Basic connection oriented session protocol specification</title>
<author>
<organization>International Organization for Standardization</organization>
</author>
<date month="April" year="1990"/>
</front>

<seriesInfo name="ISO" value="Standard 8327"/>

</reference><!-- bibxml-ids reference -->
        <xi:include href="https://datatracker.ietf.org/doc/bibxml3/draft-ietf-6lo-ap-nd.xml"/><!-- bibxml-w3c reference -->
        <reference anchor="W3C.CR-accelerometer-20191212" target="https://www.w3.org/TR/2019/CR-accelerometer-20191212/" xml:base="https://bib.ietf.org/public/rfc/bibxml-misc/reference.W3C.CR-accelerometer-20191212.xml">
  <front>
    <title>Accelerometer</title>
    <author fullname="Anssi Kostiainen" role="editor"/>
    <date day="12" month="December" year="2019"/>
  </front>
  <seriesInfo name="W3C CR" value="CR-accelerometer-20191212"/>
  <seriesInfo name="W3C" value="CR-accelerometer-20191212"/>
</reference><!-- bibxml-ieee reference -->
        <reference anchor="IEEE.802-1Y.1990" xml:base="https://bib.ietf.org/public/rfc/bibxml-misc/reference.IEEE.802-1Y.1990.xml">
<front>
<title>Source Routing Tutorial for End System Operation</title>
<author>
<organization>Institute of Electrical and Electronics Engineers</organization>
</author>
<date month="September" year="1990"/>
</front>

<seriesInfo name="IEEE" value="Standard 802.1Y"/>

</reference></references>
    </references>
    <!--This document was prepared using Pandoc2rfc https://github.com/miekg/pandoc2rfc -->
      <section anchor="tests" toc="default" numbered="true">
      <name>Tests</name>
      <t>
            This appendix consists out of a few tests that should all render to proper
            <tt>xml2rfc</tt> XML.  
      </t>
      <section anchor="a-very-long-title-considerations-with-regards-to-the-already-deployed-routing-policy" toc="default" numbered="true">
        <name>A Very Long Title Considerations With Regards to the Already Deployed Routing Policy</name>
        <t>
               Test a very long title.  
        </t>
      </section>
      <section anchor="markup-in-heading" toc="default" numbered="true">
        <name>Markup in heading</name>
        <t>
               This is discarded by <tt>xml2rfc</tt>.  
        </t>
      </section>
      <section anchor="blockquote" toc="default" numbered="true">
        <name>Blockquote</name>
        <ul empty="true" spacing="normal">
          <li>
                     This is a blockquote, how does it look? 
                  </li>
        </ul>
      </section>
      <section anchor="verbatim-code-blocks" toc="default" numbered="true">
        <name>Verbatim code blocks</name>
        <artwork name="" type="" align="left" alt=""><![CDATA[
A verbatim code block
jkasjksajassjasjsajsajkas
               ]]></artwork>
      </section>
      <section anchor="reference-tests" toc="default" numbered="true">
        <name>Reference Tests</name>
        <t>
               Refer to <xref target="RFC2119" format="default">RFC 2119</xref> if you will. Or maybe you want to inspect <xref target="fig-a-minimal-" format="default"/> in <xref target="pandoc-to-rfc" format="default"/> again. Or you might want to <eref target="http://miek.nl">Click here</eref>.  
        </t>
      </section>
      <section anchor="spanx-tests" toc="default" numbered="true">
        <name>Spanx Tests</name>
        <ul empty="true" spacing="normal">
          <li>
                     underscores: <em>underscores</em>
          </li>
          <li>
                     asterisks: <em>asterisks</em>
          </li>
          <li>
                     double asterisks: <strong>double asterisks</strong>
          </li>
          <li>
                     backticks: <tt>backticks</tt>
          </li>
        </ul>
      </section>
      <section anchor="list-tests" toc="default" numbered="true">
        <name>List Tests</name>
        <ol spacing="normal" type="1"><li>
                     First we do 
                  </li>
          <li>
            <t>
                     And then </t>
            <ul spacing="normal">
              <li>
                           item 1 
                        </li>
              <li>
                           item 2 
                        </li>
            </ul>
          </li>
        </ol>
        <t>
               And the other around.  
        </t>
        <ul spacing="normal">
          <li>
                     First we do 
                  </li>
          <li>
            <t>
                     Then </t>
            <ol spacing="normal" type="1"><li>
                           Something 
                        </li>
              <li>
                           Another thing 
                        </li>
            </ol>
          </li>
        </ul>
        <t>
               Description lists: 
        </t>
        <dl newline="false" spacing="normal">
          <dt>Item to explain:</dt>
          <dd>It works because of herbs.  
                  </dd>
          <dt>Another item to explain:</dt>
          <dd>
            <t>More explaining.  </t>
            <t> Multiple paragraphs in such a list.  
            </t>
          </dd>
        </dl>
        <t>
               lists in description lists.  
        </t>
        <dl newline="false" spacing="normal">
          <dt>Item to explain:</dt>
          <dd>
            <t>It works because of </t>
            <ol spacing="normal" type="1"><li>
                        One 
                     </li>
              <li>
                        Two 
                     </li>
            </ol>
          </dd>
          <dt>Another item to explain:</dt>
          <dd>More explaining 
                  </dd>
          <dt>Item to explain:</dt>
          <dd>
            <t>It works because of </t>
            <ol spacing="normal" type="1"><li>
                        One1 
                     </li>
              <li>
                <t>
                        Two1 </t>
                <ul spacing="normal">
                  <li>
                              Itemize list 
                           </li>
                  <li>
                              Another item 
                           </li>
                </ul>
              </li>
            </ol>
          </dd>
          <dt>Another item to explain again:</dt>
          <dd>More explaining 
                  </dd>
        </dl>
        <t>
               list with description lists.  
        </t>
        <ol spacing="normal" type="1"><li>
            <t>
                     More </t>
            <dl newline="false" spacing="normal">
              <dt>Item to explain:</dt>
              <dd>Explanation ...  
                        </dd>
              <dt>Item to explain:</dt>
              <dd>Another explanation ...  
                        </dd>
            </dl>
          </li>
          <li>
                     Go'bye 
                  </li>
        </ol>
        <t>
               Multiple paragraphs in a list.  
        </t>
        <ol spacing="normal" type="1"><li>
            <t>
                     This is the first bullet point and it needs multiple paragraphs...
            </t>
            <t> ... to be explained properly.  
            </t>
          </li>
          <li>
                     This is the next bullet. New paragraphs should be indented with 4 four spaces.  
                  </li>
          <li>
            <t>
                     Another item with some artwork, indented by 8 spaces.
            </t>
            <artwork name="" type="" align="left" alt=""><![CDATA[
Artwork
                        ]]></artwork>
          </li>
          <li>
                     Final item.  
                  </li>
        </ol>
        <t>
               xml2rfc does not allow this, so the second paragraph is faked with a 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
<vspace blankLines='1'>
               ]]></artwork>
        <t>
               Ordered lists.  
        </t>
        <ol spacing="normal" type="1"><li>
                     First item 
                  </li>
          <li>
                     Second item 
                  </li>
        </ol>
        <t>
               A lowercase roman list: 
        </t>
        <ol spacing="normal" type="%i."><li>
                     Item 1 
                  </li>
          <li>
                     Item 2 
                  </li>
        </ol>
        <t>
               An uppercase roman list.  
        </t>
        <ol spacing="normal" type="(%d)"><li>
                     Item1 
                  </li>
          <li>
                     Item2 
                  </li>
          <li>
                     Item 3 
                  </li>
        </ol>
        <t>
               And default list markers.<iref item="list" subitem="default markers" primary="false"/>
        </t>
        <t>
               Some surrounding text, to make it look better.  
        </t>
        <ul empty="true" spacing="normal">
          <li>
                     First item. Use lot of text to get a real paragraphs sense.
		     First item. Use lot of text to get a real paragraphs sense.
		     First item. Use lot of text to get a real paragraphs sense.
		     First item. Use lot of text to get a real paragraphs sense.  
                  </li>
          <li>
                     Second item. So this is the second para in your list. Enjoy; 
                  </li>
          <li>
                     Another item.  
                  </li>
        </ul>
        <t>
               Text at the end.  
        </t>
        <t>
               Lowercase letters list.  
        </t>
        <ol spacing="normal" type="a"><li>
                     First item 
                  </li>
          <li>
                     Second item 
                  </li>
        </ol>
        <t>
               Uppercase letters list.  
        </t>
        <ol spacing="normal" type="%C."><li>
                     First item 
                  </li>
          <li>
                     Second item 
                  </li>
        </ol>
        <t>
               <iref item="list" subitem="Uppercase Letters" primary="false"/>
        </t>
        <t>
               And artwork in a description list.  
        </t>
        <dl newline="false" spacing="normal">
          <dt>Item1:</dt>
          <dd>
            <t>
                     Tell something about it. Tell something about it. Tell something about
		     it. Tell something about it. Tell something about it. Tell something about it.
            </t>
            <artwork name="" type="" align="left" alt=""><![CDATA[
miek.nl.    IN  NS  a.miek.nl.                             
a.miek.nl.  IN  A   192.0.2.1    ; <- this is glue            
                     ]]></artwork>
            <t>
                     Tell some more about it. Tell some more about it. Tell some more about it.  
            </t>
          </dd>
          <dt>Item2:</dt>
          <dd>Another description 
                  </dd>
        </dl>
        <t>
               List with a sublist with a paragraph above the sublist 
        </t>
        <ol spacing="normal" type="1"><li>
                     First Item 
                  </li>
          <li>
                     Second item 
                  </li>
          <li>
            <t>
                     Third item </t>
            <t> A paragraph that comes first </t>
            <ol spacing="normal" type="a"><li>
                           But what do you know 
                        </li>
              <li>
                           This is another list 
                        </li>
            </ol>
          </li>
        </ol>
      </section>
      <section anchor="anchor-table-tests" toc="default" numbered="true">
        <name>Table Tests</name>
        <table anchor="tab-demonstrat" align="center">
          <name>Demonstration of simple table
        syntax.</name>
          <thead>
            <tr>
              <th align="right">Right </th>
              <th align="left">Left </th>
              <th align="center">Center </th>
              <th align="left">Default </th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td align="right">12 </td>
              <td align="left">12 </td>
              <td align="center">12 </td>
              <td align="left">12 </td>
            </tr>
            <tr>
              <td align="right">123 </td>
              <td align="left">123 </td>
              <td align="center">123 </td>
              <td align="left">123 </td>
            </tr>
            <tr>
              <td align="right">1 </td>
              <td align="left">1 </td>
              <td align="center">1 </td>
              <td align="left">1 </td>
            </tr>
          </tbody>
        </table>
        <table anchor="tab-here-s-the" align="center">
          <name>Here's the caption. It, too, may span multiple lines. This is a
        multiline table. This is verbatim text.</name>
          <thead>
            <tr>
              <th align="center">Centered Header </th>
              <th align="left">Default Aligned </th>
              <th align="right">Right Aligned </th>
              <th align="left">Left Aligned </th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td align="center">First </td>
              <td align="left">row </td>
              <td align="right">12.0 </td>
              <td align="left">Example of a row that spans multiple lines.  </td>
            </tr>
            <tr>
              <td align="center">Second </td>
              <td align="left">row </td>
              <td align="right">5.0 </td>
              <td align="left">Here's another one. Note the blank line between rows.  </td>
            </tr>
          </tbody>
        </table>
        <t>
               <iref item="table" subitem="simple" primary="false"/>
        </t>
        <table anchor="tab-sample-gri" align="center">
          <name>Sample grid table.</name>
          <thead>
            <tr>
              <th align="left">Fruit </th>
              <th align="left">Price </th>
              <th align="left">Advantages </th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td align="left">Bananas </td>
              <td align="left">$1.34 </td>
              <td align="left">built-in wrapper </td>
            </tr>
            <tr>
              <td align="left">Oranges </td>
              <td align="left">$2.10 </td>
              <td align="left">cures scurvy </td>
            </tr>
          </tbody>
        </table>
        <t>
               Grid tables without a caption 
        </t>
        <table align="center">
          <thead>
            <tr>
              <th align="left">Fruit </th>
              <th align="left">Price </th>
              <th align="left">Advantages </th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td align="left">Bananas </td>
              <td align="left">$1.34 </td>
              <td align="left">built-in wrapper </td>
            </tr>
            <tr>
              <td align="left">Oranges </td>
              <td align="left">$2.10 </td>
              <td align="left">cures scurvy </td>
            </tr>
          </tbody>
        </table>
        <t>
               This table has no caption, and therefor no reference. But you can refer to some of the other tables, with for instance: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
See [](#tab-here-s-the)
               ]]></artwork>
        <t>
               Which will become "See <xref target="tab-here-s-the" format="default"/>".  
        </t>
        <t>
               <iref item="table" subitem="grid" primary="false"/>
        </t>
        <t>
               We should also be able to refer to the table numbers directly, to say things like 
               'Look at Tables
               <xref target="tab-demonstrat" format="counter"/>,
               <xref target="tab-here-s-the" format="counter"/>
               and <xref target="tab-sample-gri" format="counter"/>.'
        </t>
      </section>
      <section anchor="numbered-examples" toc="default" numbered="true">
        <name>Numbered examples</name>
        <t>
               This is another example: 
        </t>
        <ol spacing="normal" type="1"><li>
                     Another bla bla..  
                  </li>
        </ol>
        <t>
               as (1) shows...  
        </t>
      </section>
      <section anchor="anchor-figure-tests" toc="default" numbered="true">
        <name>Figure tests</name>
        <figure anchor="fig-this-is-th">
          <name>This is the caption, with text in `typewriter`. Which isnt converted to a &lt;spanx&gt; style, because this is copied as-is.</name>
          <artwork name="" type="" align="left" alt=""><![CDATA[
This is a figure
This is a figure
This is a figure
This is a figure
               ]]></artwork>
        </figure>
        <t>
               And how a figure that is not centered, do to using <tt>figure</tt> and not <tt>Figure</tt>.  
        </t>
        <figure anchor="fig-a-non-cent">
          <name>A non centered figure.</name>
          <artwork name="" type="" align="left" alt=""><![CDATA[
This is a figure
This is a figure
               ]]></artwork>
        </figure>
        <t>
               Test the use of <tt>@title</tt>: 
        </t>
        <artwork name="" type="" align="left" alt=""><![CDATA[
This is a figure with a title
This is a figure with a title
@title: and here it is: a title, don't mess it up *
               ]]></artwork>
      </section>
      <section anchor="verse-tests" toc="default" numbered="true">
        <name>Verse tests</name>
        <t>
               This is a verse text This is another line 
        </t>
      </section>
    </section>
  </back>
</rfc>