Compiling IETF RFCs with Metanorma and LaTeX

Author’s picture Paolo Brasolin on 13 Dec 2019

We have made great progress with the LaTeX backend of Metanorma since we announced alpha support. Most features of the AsciiDoc backend are now supported by Metanorma-flavoured LaTeX!

The time is ripe to for a tutorial to get you up and running.

In fact, we dedicate this post to celebrate the recent official adoption at IETF of RFC XML v3 (RFC 7991) — writing an IETF RFC using LaTeX!

Setup

Metanorma

First of all, you need to install the Metanorma toolchain. Our installation guide covers in detail all supported environments so we won’t dwell on that here.

LaTeX

The second step is setting up a LaTeX distribution. Since you’re reading this you probably have one already, but if that’s not the case you can find one at getting LaTeX.

Glue 1: LaTeXML

A required dependency for our toolchain is LaTeXML. Most LaTeX distributions include it, but we need a very recent version. Many ways to install it are described in its documentation.

If you are on a recent version of Linux, try snap which is a snap-pier way to install LaTeXML!

# the latexml `edge` channel provides the earliest compatible version
snap install latexml --edge

Otherwise, simply use Perl’s cpanm package manager:

# to get the latest _bleeding edge_ version
cpanm git://github.com/brucemiller/LaTeXML.git

# to get the earliest compatible version
cpanm git://github.com/brucemiller/LaTeXML.git@9a0e7dc5

Glue 2: tex2mn

The final step is getting tex2mn, the tool we built as a bridge from LaTeX to Metanorma. This is as simple as cloning a git repository, which will also get you the sample we’ll compile:

git clone git@github.com:metanorma/tex2mn.git

Usage

General

Take a look inside `tex2mn’s folder. You will find these files:

Metanorma.cls

This is the LaTeX class implementing the Metanorma LaTeX flavour; it allows you to compile Metanorma LaTeX directly to PDF.

Metanorma.cls.ltxml and Metanorma.xsl

These are the beating heart of tex2mn and encode how Metanorma LaTeX is translated to Metanorma AsciiDoc.

Just copy these three files into the working folder of your projects and you’re ready to go.

Compiling a sample file

The conclusive ASCII-cast

Let’s compile a sample file!

As you see, there are a few commands to run so let’s run over the crucial ones.

We are going to use the file showcase.tex located at examples/showcase.tex within the tex2mn directory.

(Optional) Using LaTeX tools with Metanorma LaTeX

For those who can’t stand getting outside of the TeX toolchain, Metanorma LaTeX files are natively LaTeX and are compatible with all the usual tools you use.

For example, you can compile Metanorma LaTeX directly to PDF. You can use pdflatex or go fully automatic with latexmk:

latexmk -pdf showcase.tex

Compiling Metanorma LaTeX into Metanorma AsciiDoc

You can translate Metanorma LaTeX into Metanorma AsciiDoc:

latexml showcase.tex | latexmlpost - --stylesheet=Metanorma.xsl \
  --nocrossref --nodefaultresources --destination=showcase.adoc

Compiling into XML RFC v3

Finally, you can use the Metanorma toolchain to compile the Metanorma AsciiDoc to the desired output.

To target IETF’s RFC XML v3 you can run:

metanorma compile -t ietf showcase.adoc

That’s it! This is all you need to know to get started.

Conclusion and next steps

As outlined in our early roadmap we reached very good feature coverage of Metanorma LaTeX with respect to Metanorma AsciiDoc.

It is now time for battle-testing tex2mn and integrating it seamlessly into the Metanorma toolchain.

On our next announcement running your LaTeX-based document production pipeline will be as easy as:

metanorma -t ietf input.tex

Ciao, for now!