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!
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.
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
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 firstname.lastname@example.org:metanorma/tex2mn.git
Take a look inside `tex2mn’s folder. You will find these files:
This is the LaTeX class implementing the Metanorma LaTeX flavour; it allows you to compile Metanorma LaTeX directly to PDF.
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
(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 -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!