Quick Start

3 minute read Published:

The easiest way to get started is to download one of the precompiled binaries. And familiarize yourself with markdown and it’s syntax and read our syntax document.

Xml2rfc should have a package for your operating system, otherwise it can be found on pypi. For version 3 output you’ll need at least 2.10.3, but newer is better.


Getting Xml2rfc for Debian/Ubuntu (assuming you’ve hunted down any dependencies), with going to https://pypi.org/project/xml2rfc/#files, downloading the Xml2rfc files there and then running py2dsc-deb xml2rfc-<version>.tar.gz. py2dsc is part of the python-stdeb package.


% wget https://github.com/mmarkdown/mmark/releases/download/v1.9.93/mmark_1.9.93_linux_amd64.tgz
% tar xvf mmark_1.9.93_linux_amd64.tgz
% ./mmark -version

Now with ./mmark test.md you render test.md to RFC 7991 XML (xml2rfc version 3), let’s take a look at test.md. For xml2rfc version 2, just use the -2 flag.

Title = "Mmark Document"

.# Abstract

This is a small test document.


# First Section

Hi! *from* Mmark.

The text between %%% is the title block. For a real I-D this needs to be expanded quite considerably, but for now it will suffice. Next is the abstract of the document, which is started with .# to signal a “special” heading. The title block and abstract are part of the front matter of the document which is opened. To start the main matter of the doc we use {mainmatter} And lastly we start a “real” section with some text.

If we render this (./mmark test.md), we get this XML:

<?xml version="1.0" encoding="utf-8"?>
<!-- name="GENERATOR" content="github.com/mmarkdown/mmark markdown processor for Go" -->
<rfc version="3" ipr="trust200902" submissionType="IETF" xml:lang="en" consensus="false" xmlns:xi="http://www.w3.org/2001/XInclude">

<title>Mmark Document</title><seriesInfo></seriesInfo>
<date year="2018" month="8" day="22"></date>

<abstract anchor="abstract">
<t>This is a small test document.</t>



<section anchor="first-section"><name>First Section</name>
<t>Hi! <em>from</em> Mmark.</t>



Note that this can’t be converted with xml2rfc --v3 because we’re missing various front matter elements, notable the <seriesInfo> and there are no authors specified.

Full I-D

We need to fill out the seriesInfo and add an author to the title block:

Title = "Mmark Document"
area = "Internet"
workgroup = "Network Working Group"

name = "Internet-Draft"
value = "draft-gieben-00"
stream = "IETF"
status = "informational"

date = 2018-08-21T00:00:00Z

fullname="R. (Miek) Gieben"

And then generate the XML again and give it to xml2rfc --v3:

% ./mmark test.md > x.xml
% xml2rfc --v3 x.xml
Parsing file x.xml
x.xml(4): Warning: Expected a category, one of exp,info,std,bcp,historic, but found none
Created file x.txt

Where x.txt is the generated text of the I-D (showing small excerpt):

Network Working Group                   R. Gieben
Internet-Draft                     21 August 2018
Expires: 22 February 2019

                      Mmark Document


   This is a small test document.

Status of This Memo


Table of Contents

   1.  First Section

1.  First Section

   Hi! _from_ Mmark.

The rfc directory has a couple of (older) RFCs that have been converted to Mmark for (syntax) inspiration, or take a look at the syntax document.