Metanorma now supports LaTeX input (`tex2mn` in alpha!)

Paolo Brasolin

Ronald Tse on 08 Oct 2019

Standards authors, especially those who have been writing exclusively in LaTeX/TeX in their lives (you know who you are, cryptographers), have long requested for the ability to create Metanorma output using LaTeX syntax instead of our beloved AsciiDoc.

This has been particularly challenging for us since they have been constant in their feedback: comments, suggestions, recommendations, and eventually the very strongly worded demands…

Today we finally acknowledge their request with actions and finally free ourselves from TeXtual abuse (just kidding).

Introducing tex2mn

tex2mn, as you would have guessed, stands for LaTeX to Metanorma.

With this new tool we will help LaTeX authors write Metanorma documents without abandoning the comforts of their beloved language.

The function of tex2mn is twofold:

mapping the semantics of the Metanorma standard onto a LaTeX document class, and
providing a simple command to convert LaTeX documents to Metanorma-flavoured AsciiDoc.

Effectively, this means that LaTeX will become a first-class citizen among Metanorma input formats — on par with AsciiDoc!

We just released version 0.1.0. It’s an alpha but you can already compile simple documents. Watch the screencast below to take a quick peek before we delve into the details.

Figure 1. Generating a Metanorma document using tex2mn

Note	See the full screencast at YouTube!

Usage of LaTeX Metanorma

To start, get the Metanorma LaTeX document class Metanorma.cls from the repository. Once it’s in your work folder, you can start writing your document:

\documentclass{Metanorma}

\title{Sample document}
\set{author}{John Doe}
\set{author-phonetic}{jän dō}

\begin{document}
  \maketitle
  \tableofcontents
  \bigskip

  This is the beginning of our sample document.
  The author is \get{author}, which is pronounced \get{author-phonetic}.

  % ...

\end{document}

There are only two surprising macros:

\set{<attribute>}{<value>} sets the value for a document attribute which will get passed to Metanorma.
Using \get{<attribute>} you can read the value of an attribute and use it in the document.

To write the document contents, many customary macros and environments are available:

all sectioning macros from \section downwards,
\label and \ref to place anchor and reference them,
\footnote to render footnotes,
quote environment to render quotes,
\textbf, \textit, \textsc and \textst (strikethrough) macros for text formatting,
flushleft, center and flushright environments for paragraph alignment,
itemize, enumerate and description environments for lists,
equation, gather and align environments for display math,
\ref, \hyperref, \url and \hyperref for cross referencing.

Figures and tables can be also be captioned, labelled and \referred to as usual:

\begin{figure}
  \label{fig:example}
  \caption{This is an example figure}
  \includegraphics{example-figure}
\end{figure}

\begin{table}
  \label{tab:example}
  \caption{This is an example table}
  \begin{tabular}{ll} A & B \\ C & D \end{tabular}
\end{table}

New environments introduced by Metanorma LaTeX include:

tip, note, important, warning and caution environments to render color coded admonition boxes
requirement, recommendation, permission, specification, measurement-target, verification and import environments to render boxes with the relative meaning (note that all of them can be nested in the first three)

Bibliographies are currently supported only in the embedded form:

\cite{latexcompanion} is an essential book about \LaTeX,
while \cite{ISO7301} gives the minimum specifications
for rice subject to international trade.

\begin{thebibliography}{2}
  \bibitem{latexcompanion} Michel Goossens, Frank Mittelbach,
    and Alexander Samarin. \textit{The \LaTeX\ Companion}.
    Addison-Wesley, Reading, Massachusetts, 1993.
  \bibitem[ISO 7301]{ISO7301} Rice -- Specification
\end{thebibliography}

Note that the optional label provided to \bibitem[<label>]{<key>} will be used by Metanorma to automatically fetch the citation from online databases if it references any standard known to have one.

Most of what’s listed above is either standard LaTeX or very simple extensions. Metanorma LaTeX is designed to be as close as possible to standard LaTeX while being faithful to the structures the Metanorma standard needs to represent.

Document compilation

Your Metanorma LaTeX document can be compiled directly to PDF just like any other LaTeX document (we recommend latexmk -pdf input.tex if your distribution includes it).

To run tex2mn and use your document as an input for metanorma, you first need to install latexml:

sudo cpanm git://github.com/brucemiller/LaTeXML.git

Note	Or if you want to pinpoint the earliest compatible version, do this: `sudo cpanm git://github.com/brucemiller/LaTeXML.git@9a0e7dc5`

After that, get Metanorma.cls.ltxml and Metanorma.xsl from the repository and put them into your project folder.

You’re now ready to convert input.tex to output.adoc with this one liner representing the core function of tex2mn:

latexml input.tex  --nocomments | \
  latexmlpost - --stylesheet=Metanorma.xsl --nocrossref --nodefaultresources --destination=output.adoc

Finally, you can use Metanorma to target any output type and file format you want:

$ metanorma -t iec output.adoc

Conclusion and next steps

tex2mn is still in alpha but we’re confident it’s a solid approach to the problem. We have a clear roadmap to maximize the value this tool will bring to the community:

extend Metanorma LaTeX until it is feature-complete with respect to Metanorma AsciiDoc
seamlessly integrate tex2mn into metanorma-cli so you can run it with a single, simple command.

Ciao, for now!