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.
Xml2rfc
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.
Mmark
% 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
% ./mmark -version
1.9.93
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.
{mainmatter}
# 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">
<front>
<title>Mmark Document</title><seriesInfo></seriesInfo>
<date year="2018" month="8" day="22"></date>
<area>Internet</area>
<workgroup></workgroup>
<abstract anchor="abstract">
<t>This is a small test document.</t>
</abstract>
</front>
<middle>
<section anchor="first-section"><name>First Section</name>
<t>Hi! <em>from</em> Mmark.</t>
</section>
</middle>
</rfc>
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"
[seriesInfo]
name = "Internet-Draft"
value = "draft-gieben-00"
stream = "IETF"
status = "informational"
date = 2018-08-21T00:00:00Z
[[author]]
initials="R."
surname="Gieben"
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
Abstract
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.