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 may not be pre-installed on your Linux distribution.

Please follow the official Ruby installation guide.

Windows

Ruby is not pre-installed on Windows.

The easiest way to install Ruby is with RubyInstaller, as recommended by the official Ruby installation guide)

If you prefer an automated way to install, we recommend using Chocolatey with commands below:

choco install -y msys2 ruby
refreshenv
ridk install 3

Those commands will work with both PowerShell and CMD.exe.

Other

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