This is an follow-up on this pandoc item in Dutch.

When writing RFC 4641 we directly wrote the XML. Needless to say is was kinda tedious even thought the XML of xml2rfc is very “light”.

Nowadays I’m a fan of the markdown syntax and especially the syntax as supported (created?) by 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;
  2. back.mkd;
  3. 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;
  • list style=symbols, see README.html;
  • list style=numbers;
  • list style=letters;
  • list style=format, both lowercase and uppercase roman numerals;
  • list style=hanging, see README.html;
  • figure/artwork, see README.html;
  • blockquote - this isn’t supported by xml2rfc, so this is converted to figure/artwork paragraph. See README.html;
  • refs: external (eref), see README.html;
  • refs: internal (xref) see README.html;
  • spanx style=verb, style=emph, style=strong, see README.html;
  • tables, see README.html.

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.

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.

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 .

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 …

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"> ...