# Pandoc to RFC



This is an follow-up on [this `pandoc` item in Dutch](http://www.sidnlabs.nl/laatste-berichten/nieuwsdetail/article/van-pandoc-naar-rfc/).

When writing [RFC 4641](http://www.ietf.org/rfc/rfc4641.txt) we directly wrote the
XML. Needless to say is was kinda tedious even thought the XML of [xml2rfc](http://xml.resource.org/)
is very "light".

Nowadays I'm a fan of the markdown syntax and especially the syntax as supported (created?)
by [Pandoc](http://johnmacfarlane.net/pandoc/).

So for my next RFC (if ever!) I decided I wanted to use Pandoc. As `xml2rfc` uses XML
I thought the easiest way would be to create `docbook` XML and transform that using
XSLT.

The XML generated is suitable for inclusion in either the `middle` or `back` section
of an RFC. The easiest way is to create a template xml file and include the appropriate
XML:

    <?xml version='1.0' ?>
    <!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>

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

    <middle>
        <?rfc include="middle.xml"?>
    </middle>

    <back>
        <?rfc include="back.xml"?>
    </back>

    </rfc>

See the Makefile for an example of this. In this case you need to edit
3 documents:

1. middle.mdk;
1. back.mkd;
1. template.xml (probably a fairly static file).

The draft (`draft.txt`) is automatically created when you call `make`. 
Note that this `README.mkd` is converted to an RFC-like document when you call `make`.

It needs `xsltproc` and `pandoc` to be installed.

What is supported?

* section with anchor and title attributes, see [README.html](http://johnmacfarlane.net/pandoc/README.html#headers);
* list style=symbols, see [README.html](http://johnmacfarlane.net/pandoc/README.html#lists);
* list style=numbers;
* list style=letters;
* list style=format, both lowercase and uppercase roman numerals;
* list style=hanging, see [README.html](http://johnmacfarlane.net/pandoc/README.html#definition-lists);
* figure/artwork, see [README.html](http://johnmacfarlane.net/pandoc/README.html#indented-code-blocks);
* blockquote - this isn't supported by `xml2rfc`, so this is converted to
    figure/artwork paragraph. See [README.html](http://johnmacfarlane.net/pandoc/README.html#block-quotations);
* refs: external (eref), see [README.html](http://johnmacfarlane.net/pandoc/README.html#inline-links);
* refs: internal (xref) see [README.html](http://johnmacfarlane.net/pandoc/README.html#header-identifiers-in-html);
* spanx style=verb, style=emph, style=strong, see [README.html](http://johnmacfarlane.net/pandoc/README.html#inline-formatting);
* tables, see [README.html](http://johnmacfarlane.net/pandoc/README.html#tables).

What's not?

* list style=empty;
* irefs: index (no pandoc syntax available);
* crefs: for comments (there is no pandoc syntax for this).

The heavy lifting is done by `transform.xsl` that transforms the Docbook XML to xml2rfc XML.

[Check out the pandoc2rfc github repository](https://github.com/miekg/pandoc2rfc).

# Pandoc Constructs

What do you need to type in Pandoc to get the correct output. Note this
is just basic Pandoc format, so you might be better off reading the
[README from Pandoc itself](http://johnmacfarlane.net/pandoc/README.html).

# section
Just use the normal sectioning commands available in Pandoc, I tend to use

    # Section1 One
    Bla

Converts to xml2rfc: `<section title="Section1 One" anchor="section1-one">`
If you have another section that is also named "Section1 One", that
anchor will be called "section1-one-1". Referencing the section
is done with `See [](#section1-one)`, see [](#refs-internal).

 list style symbols

    A symbol list.

    * Item one;
    * Item two.

Converts to xml2rfc: `<list style="symbol">`

 list style numbers

    A numbered list.

    1. Item one;
    2. Item two.

Converts to xml2rfc: `<list style="numbers">`

 list style letters

    A numbered list.

    a. Item one;
    b. Item two.

Converts to xml2rfc: `<list style="letters">`

 list style format

    A roman numbered list.

    I.  Item one;
    II.  Item two.

(note: 2 spaces after the numerals).

Converts to xml2rfc: `<list style="format %I.">`

 list style hanging
This is more like a description list, so we need to use:

    First item that needs clarification

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

    Second item that needs clarification

    :   Explanation two


Converts to xml2rfc: `<list style="hanging">` and `<t hangText="First item...">`

 figure/artwork

Just indent the paragraph with 4 spaces.

Converts to xml2rfc: `<figure><artwork> ...`

 blockquote
This is not supported by xml2rfc, but any paragraph like:

    > quoted text

Converts to xml2rfc: `<figure><artwork> ...`

 refs: external
Any reference like:

    [Click here](URI)

Converts to xml2rfc: `<ulink target="URI">Click here ...`

 refs: internal
Any reference like:

    [Click here](#localid)

Converts to xml2rfc: `<link target="localid">Click here ...` 

For referring to RFCs (for which you manually need add the reference source in the template), 
you can just use:

    [](#RFC2119)

And it does the right thing. Referencing sections is done with:

    See [](#pandoc-constructs)

The word 'Section' is inserted automatically: ... See [](#pandoc-constructs) ...

 spanx style
The verb style can be selected with back-tics:

    `text`

Converts to xml2rfc: `<spanx style="verb"> ...`

And the emphasis style with asterisks:

    *text*

Converts to xml2rfc: `<spanx style="emph"> ...`

And the emphasis style with double asterisks:

    **text**

Converts to xml2rfc: `<spanx style="strong"> ...`