Compiling IETF RFCs with Metanorma and LaTeX
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@9a0e7dc5Glue 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.gitUsage
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.ltxmlandMetanorma.xsl-
These are the beating heart of
tex2mnand 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.texCompiling Metanorma LaTeX into Metanorma AsciiDoc
You can translate Metanorma LaTeX into Metanorma AsciiDoc:
latexml showcase.tex | latexmlpost - --stylesheet=Metanorma.xsl \
--nocrossref --nodefaultresources --destination=showcase.adocCompiling 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.adocThat’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.texCiao, for now!