= 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
https://www.metanorma.org/author/topics/install/[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`.

[source,console]
----
# 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
https://www.ruby-lang.org/en/documentation/installation[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
https://www.ruby-lang.org/en/documentation/installation[Ruby installation guide])

If you prefer an automated way to install, we recommend using
https://chocolatey.org/install[Chocolatey] with commands below:

[source,console]
----
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
https://www.ruby-lang.org/en/documentation/installation[Ruby installation guide].



== Installing the Metanorma CLI gem

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

[source,console]
----
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 https://www.java.com/en/download/help/linux_install.html[official instructions]

Windows:: Run `choco install -y javaruntime`

=== PlantUML

*If your documents include link:/author/topics/document-format/diagrams/[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
https://graphviz.org/download/#linux[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:

[source,console]
----
pip3 install xml2rfc
----


=== Inkscape

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

macOS:: Run `brew install inkscape`

Linux:: See Linux instructions https://inkscape.org/release/[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
https://metacpan.org/dist/App-cpanminus/view/bin/cpanm[`cpanm` package manager]

[source,console]
----
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`