miekg/pandoc2rfc

Use pandoc to create XML suitable for xml2rfc

NOTE NOTE

Pandoc2rfc will not be able to generate XML2RFC v3 documents, as pandoc syntax lacks the power to do so. For this reason mmark exists.

README

Pandoc2rfc translates text written in the Markdown variant Pandoc to documents in xml2rfc format. It's an easy way to write RFCs.

The documentation for Pandoc2rfc can be found at: http://www.rfc-editor.org/rfc/rfc7328.txt.

Note that I consider mmark the logical successor of Pandoc2rfc. Pandoc2rfc can't output XML2RFC v3 XML, so when the IETF switches over to that format, you'll need something else. Mmark can output v3 (and v2 for that matter).

Differences with Pandoc

Although you can type Pandoc just fine, there are two things that differ

• Using Pandoc citations is not supported, you must use internal references for this;

• Referencing figures and tables is done by abusing inline footnotes, which are typeset directly after the figure or table. Like so:

    ^[tab:simple::Demonstration of **simple** table syntax.]
  

  Where tab:simple will be the anchor and the text after :: as used for the title.

• List with style=format REG%d are typeset with strikethrough text in the first element, as such:

    1. ~~REQ%d~~ First REQ1 item;
    2. Second REQ2 item.
  

• An index is done by (yet again) by using a foonote, but the first item is a superscript:

    ^[ ^list^ format styles]
  

  The rest of the content is the "subitem"

As said, more extensive docs are here: http://www.rfc-editor.org/rfc/rfc7328.txt. But after some setup, it is just typing Pandoc syntax in $EDITOR.

Bare install

Just copy transform.xsl and template.xml to your I-D directory. Modify template.xml according to your needs and run:

pandoc -t docbook -s <yourfile>.mkd | \
xsltproc --nonet transform.xsl - > <yourfile>.xml

And to create a draft.txt

xml2rfc template.xml -f draft.txt --text

And/or create a Makefile.

Packages

Or you can install Pandoc2rfc on your system. Then copy template.xml to your I-D directory. Modify according to your needs and run:

pandoc2rfc *.mkd

Packages can be found for Debian/Ubuntu at:

https://launchpad.net/~miek/+archive/pandoc2rfc, they should also install in previous Ubuntu versions.

Or see http://pandoc2rfc.implementers.org/ for proper Debian packages.

XSLT 1.0

Note that you don't even need xsltproc per se, just an XSLT transformer program. Also note that only xsltproc is tested.

Pandoc2rfc v2 works with xml2rfc version 2.x.

Miek Gieben - 2012

pandoc2rfc's Issues

Pandoc is a converter, not a format

The RFCs aren't 'written in pandoc', they're written in markdown and you use pandoc to convert it.

Is GitHub Flavored Markdown supported?

Does this support transform from GitHub Flavored Markdown to IETF RFC format? The squb at IETF's page just says "wiki" markup/markdown. If not, do you happen to know of any tool that does? Thanks!

Upgrade XML2RFC to new version

http://pypi.python.org/pypi/xml2rfc

I've done this in my fork. I can update to your latest and incorporate the changes if you want.

XML files not created correctly anymore (DTD not being followed)

Hello miekg (or whoever knows)

I'm getting strange errors when trying to create Internet-Drafts:

pandoc2rfc -T abstract.mkd middle.mkd back.mkd
ERROR: Unable to validate the XML document: template.xml
 <string>: Line 61: Element abstract content does not follow the DTD, expecting (t)+, got (CDATA)
 <string>: Line 66: Element middle content does not follow the DTD, expecting (section)+, got (CDATA)

That didn't happen before, such that I suspect it might have to do with updates of xsltproc or something else, as pandoc2rfc didn't change lately: that being tried on Debian.

Indeed, if you look at abstract.xml and middle.xml being created: the required elements are missing.

What could be wrong?

rfc2html instead of rfcmarkup

You probably want to use https://github.com/ietf-tools/rfc2html rather than an old copy of rfcmarkup.