Metanorma command-line interface (CLI)

Installation

Tip	To use Metanorma, normally you don’t manually install this gem. Depending on your setup, you may find quicker ways to get started: please refer to Getting Started instead.

To install this gem, simply run:

gem install metanorma-cli

This will install the metanorma executable, which you can use with all officially supported Metanorma flavors (such as ISO, CalConnect, IETF, etc).

However, a number of dependencies are not installed with this gem, and have to be installed separately. The process of installing the full suite can be a little more complex.

Generally, we recommend you to follow steps given at Metanorma Installation.

But if you aren’t afraid of tinkering deeply, please see the Developer Installation Notes for advanced details regarding dependencies and Windows installation notes.

Usage

Setting up

Metanorma CLI helps you install necessary fonts used by particular flavors, as long as those fonts have a license that allow you to install them.

For example, ISO relies on Cambria while ITU relies on Arial, which are both not supplied by default on Linux. Due to licensing terms, you are allowed to install them yourself.

By running the metanorma setup command, Metanorma will identify fonts not available on your system, and helps you install them once you agree to the license terms presented by those fonts.

Typically run the command below.

metanorma setup

If you are sure you want to agree with all the font licensing terms, such as during non-interactive runs for continuous integration, you can explicitly agree to all terms using the --agree-to-terms option.

metanorma setup --agree-to-terms

External dependencies

The Metanorma toolchain supports certain features when optional dependencies are installed. Please refer to the following table for them.

Dependency	Mandatory?	Target component / purpose
`git`	✅	`metarnoma-cli` (templates), `fontist`
`java`	✅	`mn2pdf`, `metanorma-standoc`
`xml2rfc` (`python`)	⬜	`metanorma-ietf`
`inkscape`	⬜	`isodoc`, SVG to EMF functionality (for inserting SVGs into Word)
`graphviz`	✅	`lutaml` generation of LutaML diagrams
`plantuml`	⬜	`metanorma-standoc` generation of PlantUML diagrams

Generate a new Metanorma document using a template (`metanorma new`)

Metanorma CLI allows you to create a new document using an official template, or a user-specified custom template.

To see what options are available under the new command, run metanorma help new.

Generate a new document from an official Metanorma template (from an official Metanorma template repository)

The metanorma new command allows you to create a document by running a single command.

To create a new document using an official template you simply invoke the command with the mandatory options type and doctype, then Metanorma will find and load the official template to create your document.

For example, if you want to create a new CSD document (type: csd) called csd-foo-standard, using the standard template type, run the following command:

metanorma new -d standard -t csd csd-foo-standard

This will create your barebones document and will also print out all files created during generation.

Currently, the supported Metanorma template types are csd, ogc and iso.

Generate a new document from a custom Metanorma template repository

The CLI allows using custom or unofficial template repositories, meaning you could also generate a new document using your own custom template.

Metanorma supports two types of template repositories:

Git: a Git repository (local or remote, public or private)
Local: a directory

Once a template repository and a template within is specified, Metanorma will automatically download and generate the new document using your custom template.

For example, if you want to create a new CSD document with the following parameters:

Document name: my-custom-csd-document
Flavor: csd
Doctype: standard
Template: https://gitfoo.com/foobar/mn-templates-foobar (fictitious example)

You could execute the following command to do so:

metanorma new -d standard -t csd \
  -l https://gitfoo.com/foobar/mn-templates-foobar my-custom-csd-document

Here’s an example of using a local directory:

metanorma new -d standard -t csd \
  -l ~/shared/mn-templates my-custom-csd-document

Compile a document (`metanorma compile` or just `metanorma`)

The key functionality of this CLI is to allow compilation of a Metanorma document. The command metanorma help compile will display all usage instructions of the compile command shown with available options.

Usage:
  metanorma compile FILENAME [..options]

Options:
  -t, [--type=TYPE]                   # Type of standard to generate
  -x, [--extensions=EXTENSIONS]       # Type of extension to generate per type
  -f, [--format=FORMAT]               # Format of source file: eg. asciidoc
                                      # Default: asciidoc

  -r, [--require=one two three]       # Require LIBRARY prior to execution
  -w, [--wrapper], [--no-wrapper]     # Create wrapper folder for HTML output
  -a, [--asciimath], [--no-asciimath] # Keep Asciimath in XML output instead of converting it to MathM
  -R, [--relaton=RELATON]             # Export Relaton XML for document to nominated filename
  -e, [--extract=EXTRACT]             # Export sourcecode fragments from this document to nominated directory
  -v, [--version=VERSION]             # Print version of code (accompanied with -t)

So, let’s put this in use. For example we have a document my-iso-document.adoc and we want to compile this using iso and html as extension, then we can use the following command.

metanorma compile --type iso -x html my-iso-document.adoc
# or just
metanorma --type iso -x html my-iso-document.adoc

This should compile any valid document, but if there are some issues then it will also print those out in the terminal. Currently, the supported flavors are ietf, iso, gb, csd, csand, m3d and rsd.

Compile a document collection (`metanorma collection`)

This functionality compiles collections of Metanorma documents. It compiles the individual documents comprising the collection; then it compiles a document acting as a container for those collections. See https://github.com/metanorma/metanorma/wiki/Metanorma-collections, https://github.com/metanorma/metanorma-cli/blob/master/spec/fixtures/collection1.yml

The file argument to the collection command is a Metanorma Collections YAML file, which contains:

Directives on how the collection should be generated
Metadata about the collection
A manifest listing the documents contained in the collection, in nested hierarchy
Content to put at the beginning of the collection container
Content to put at the ending of the collection container

Documents within a collection may cross-reference each other using the syntax * [], as proposed in metanorma/metanorma#57, where mydoc is be the value of docref/identifier corresponding to the target document, as set in the YAML manifest.

The output directory will contain:

The documents referenced in the manifest, with any citations of other documents in the collection resolved, in the output formats requested
If xml or presentation are requested as formats, a concatenated collection.xml and/or collection.presentation.xml file, containing all the documents in the collection.
If html is requested as a format, an index.html HTML page, populated from a provided Liquid template coverpage, and linking to all the documents in the manifest.

Usage:
  metanorma collection FILENAME [..options]

Options:
  -x, [--extensions=EXTENSIONS]     # Type of extension to generate
  -w, [--output-folder=FOLDER]      # Folder to generate collection in
  -c, [--coverpage=COVERPAGE]       # Cover page as Liquid template for collection (currently HTML only)

List supported doctypes (`metanorma list-doctypes`)

You want to know what are the supported doctypes and what do they support for input and output format? Well, the metanorma list-doctypes can help.

metanorma list-doctypes

To list out the details for a specific flavor run the following command:

metanorma list-doctypes <flavor>

e.g.,

metanorma list-doctypes iso

List supported output formats (`metanorma list-extensions`)

Need to know what output formats are supported for a given flavor? We’ve got you covered.

To list out the output formats supported by every single flavor type, run the following command:

metanorma list-extensions

To list out the output formats supported by a particular flavor type, run the following command:

metanorma list-extensions <flavor>

e.g.,

metanorma list-extensions iso

Show processor version (`metanorma version`)

The version command returns the version of the Metanorma processor for a specific flavor.

e.g., to know the currently running version for iso, then we can use the following command and this will show the current version that we are using for that specific processor.

metanorma version --type iso

Add new template repository (`metanorma template-repo add`)

The template-repo add interface allows you to add your custom template repository to metanorma, so next time when you need to generate a new document then you can directly use that name to use your custom template from that repository.

metanorma template-repo add my-iso https://github.com/you/my-iso-template

Generate metanorma minisite

The site interface allows you to manage mini site generation using the CLI. To generate a mini site you need to provide the SOURCE_PATH and the CLI will take care of compiling each of those files and generate deployable site in the provided output directory.

This interface also supports a YAML manifest file that can be used to customize the site generation process. You can check more details here: metanorma.yml

metanorma site generate SOURCE_PATH -o OUTPUT_PATH -c metanorma.yml

Using with proxy

The metanorma command can read proxy settings from the following environment variables:

HTTP_PROXY for HTTPS and HTTP proxies
SOCKS_PROXY for SOCKS proxies

Please refer to our announcement on proxy support for details.

Note	Since `metanorma` uses Git for templates (and fonts via Fontist, which also relies on Git), Git must also be configured to use proxies. Please refer to this Gist by evantoli for details.

Credits

This gem is developed, maintained and funded by Ribose Inc.

License

The gem is available under the terms of the MIT License.

robws/metanorma-cli