Xml2rfc on Miek Gieben

How to install xml2rfc on Debian

Wed, 13 Nov 2019 07:17:36 +0000

Xml2rfc is the tool the IETF uses to convert the canonical XML for an Internet-Draft into text, HTML or a PDF. This utility has seen many releases while the XML schema was being finalized. It’s important (if you write I-Ds) that you have the latest version of xml2rfc installed.

Installing it as a Debian package is done with:

go to https://pypi.org/project/xml2rfc/#files
download the tar archive (say “xml2rfc-2.35.0.tar.gz”)
execute: py2dsc-deb xml2rfc-2.35.0.tar.gz (“py2dsc-deb” can be found in the “python-stdeb” package)
execute: sudo dpkg -i deb_dist/python-xml2rfc_2.35.0-1_all.deb

Note a py2dsc also exists, but that doesn’t create a Debian package.

Mmark Updates

Mon, 09 May 2016 18:54:21 +0100

Recent bug reports prompted some Mmark development (guess I am into bug-driven development). New releases can be found on Github. Anyway Mmark saw some bug fixes and new features:

A feature/pull request from blackfriday got merged, meaning that two different lists are not merged into one:

* A
* B

1. One
2. Two

Is now correctly seen as two different lists.

Further more a <br/> is converted to a <vspace/> in the XML output. This is especially useful when you want a vertical space after a definition term. See rfc/rfc7511.md for an example on how to use this.

Subfigures in mmark

Sat, 03 Oct 2015 13:24:00 +0000

For XML2RFC version 3 there is a new extended figure element, namely: it can contain multiple <artwork> or <sourcecode> (new in v3) elements. This in turn meant that mmark needed some way to signal “these artworks belong together”. Now Scholarly markdown has a syntax for this. It uses a special section syntax and all images in that section become subfigures of a larger figure. Disadvantage of this syntax is that it can not be used in lists. Hence mmark uses a quote like solution, just like asides (A>), but for figures: we prefix the entire paragraph with F> .

Callouts in Figures in Mmark

Sun, 27 Sep 2015 14:02:00 +0000

The use of callouts in Mmark came from Asciidoc, they are “… a mechanism for annotating verbatim text”. In mmark they work like this.

In a codeblocks you can use <1>, or <2>, etc. to create a callout. After the codeblock/figure you can reference it. An example:

    Code  <1>
    More  <1>
    Not a callout \<3>

As you can see in <1> but not in \<1>. There is no <3>.

This will be rendered as:

Lists in lists with style

Thu, 24 Sep 2015 11:56:00 +0000

Mmark is a markdown dialect for writing RFCs (or books!). The main reason it exists is because the IETF is developing a new XML format (version 3) for writing RFCs. This new format is way more powerful, so sadly Pandoc2rfc does not cut it anymore.

Right now mmark fully supports writing RFCs in XML2RFC version 2, but anything written can also be converted to the (work-in-progress) XML2RFC version 3 format. In a series of blog posts I will detail some of the features, such as list styling while remaining upwards compatible.

Markdown for XML2RFC v3 - Update

Thu, 18 Dec 2014 22:46:00 +0000

And another update (2015-01-12)

This is a follow up the previous article about using markdown for XML2RFC. The syntax has been changed and more features have been implement. And my blackfriday fork has been renamed mmark.

See this document for an up to date syntax of mmark. A short summery will be given here.

New features are:

Include raw XML references
Allow HTML comments to be converted to crefs
Abbreviations (https://michelf.ca/projects/php-markdown/extra/#abbr), this is not used in XML2RFC but seems a relatively standard markdown extension
Example lists (http://johnmacfarlane.net/pandoc/README.html#numbered-example-lists)
Quote attribution

Also the possibility to convert pandoc2rfc documents to mmark has been added (as a quick and dirty perl script + pandoc!):

Markdown for XML2RFC v3

Thu, 27 Nov 2014 22:50:00 +0000

Or… how to write Markdown to generate XML that is valid XML2RFC v3. These are some assorted notes and ideas

Goal:

Self contained file with all information to generate a complete I-D;
CommonMarkdown, with some extension.

I’m working on implementing these ideas in blackfriday. The following has already been implemented:

Abstract;
Citation;
Document divisions;
Index;
File inclusion;
Extra attributes (kramdown’s IAL.) (work-in-progress).

Document meta data

In TOML - much easier than YAML for instance, lines are starting with %. We don’t need to specify the citations here because: