Installation

The metanorma command-line executable is installed by this Ruby gem.

Important

Users of the Metanorma suite should install Metanorma according to the steps at the Metanorma installation guide.

The instructions provided here are intended for Metanorma developers, since a number of third-party dependencies will also need to be installed manually.

Install Ruby

macOS

While macOS provides a default installation of Ruby, it is restricted in a number of ways.

We strongly recommend installing a Ruby outside of the system Ruby using rbenv.

# Install Xcode and associated development tools
$ xcode-select --install

# Install GCC and development tools
$ brew install autoconf gcc make

# Install rbenv to manage Ruby versions
# Remember to follow the setup steps by running `rbenv init`!
$ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash

# Install Ruby 2.7.4 through rbenv
$ rbenv install 2.7.4

# Set Ruby 2.7.4 as your global version
$ rbenv global 2.7.4

# Then restart Terminal.app

Linux

Ruby is sometimes included with Linux. To see if you already have it (and check the version):

Open a console/terminal
Type ruby -v

If Ruby is installed, you’ll see something like the following

ruby 3.1.0p0 (2021-12-25 revision fb4df44d16) [x86_64-linux]

If not, follow the official Ruby installation guide.

Windows

Ruby is not pre-installed on Windows. There are several ways to install it:

For an easy experience, use RubyInstaller, via the official Ruby installation guide)
For a more developer-friendly experience, install Ruby via a Linux distribution (like Ubuntu) hosted in the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/). [Install WSL2]((https://docs.microsoft.com/en-us/windows/wsl/install), and then [Install Ruby](https://gorails.com/setup/ubuntu/21.04).
For a simpler command-line experience, first install the [Chocolatey](https://chocolatey.org/install) package manager, then add Ruby packaged with [the MSYS2 build tools](https://www.msys2.org/). This process is explained below:
1. Open a command prompt (cmd.exe) or PowerShell console.
2. Type choco install -y msys2 ruby. (If you have a firewall, you may be prompted to allow dirmngr.exe and pacman.exe. These are part of Ruby and are safe).
3. When the installation completes, type refreshenv to make Ruby available to you.
4. Type ridk install 3 to complete the installation of Ruby version 3. This make take a while.

Other Ruby Resources

Further details (or FAQ) on Ruby installation please visit the official Ruby installation guide.

Installing the Metanorma CLI gem

Once Ruby is installed, you can install metanorma-cli as a gem:

gem install metanorma-cli

Installing the gem will also install all officially supported Metanorma flavors (such as ISO, CalConnect, IETF, etc).

Dependencies

Java

You will have to have a Java runtime installed.

Use the following commands on various platforms:

macOS: Run brew cask install java
Linux: Follow official instructions
Windows: Run choco install -y javaruntime

PlantUML

If your documents include PlantUML diagrams, PlantUML will have to be installed.

macOS: Run brew install plantuml.
Linux: Link the PlantUML jar file into a command line executable; see .travis.yml for an example.
Windows: Run choco install -y plantuml.

If PlantUML diagrams used within a document but there PlantUML is not installed, the PlantUML diagram source will be incorporated into the output document as source code (i.e. [source] style).

Graphviz

Graphviz is required by LutaML (and PlantUML) to draw diagrams.

macOS: Run brew install graphviz.
Linux: Install the appropriate available packages (apt or yum)
Windows: Run choco install -y graphviz

xml2rfc

Metanorma IETF requires usage of the xml2rfc Python package.

To install Python:

macOS: brew install python3
Windows: choco install -y python

Then install xml2rfc with:

pip3 install xml2rfc

Inkscape

Optional dependency. Inkscape is needed for SVG-to-EMF conversion functionality.

macOS: Run brew install inkscape
Linux: See Linux instructions here
Windows: Run choco install -y inkscape

LaTeXML

Optional dependency. LaTeXML is needed for Metanorma for LaTeX functionality.

Most of the packages from various package manager listed on https://dlmf.nist.gov/LaTeXML/get.html are outdated.

Since LaTeXML is a perl module, a reliable way to install it is with the cpanm package manager

curl -L https://cpanmin.us | perl - --sudo App::cpanminus
cpanm --notest LaTeXML
# or
cpanm --notest git://github.com/brucemiller/LaTeXML.git@9a0e7dc5

Alternative, it also can be installed in the following ways (always check the version, because the packages may be outdated):

macOS: Run brew install latexml
Linux (with Snap installed): Run snap install latexml
Windows: choco install -y latexml