= Metanorma command-line interface (CLI) image:https://img.shields.io/gem/v/metanorma-cli.svg["Gem Version", link="https://rubygems.org/gems/metanorma-cli"] image:https://github.com/metanorma/metanorma-cli/workflows/macos/badge.svg["Build Status (macOS)", link="https://github.com/metanorma/metanorma-cli/actions?workflow=macos"] image:https://github.com/metanorma/metanorma-cli/workflows/ubuntu/badge.svg["Build Status (ubuntu)", link="https://github.com/metanorma/metanorma-cli/actions?workflow=ubuntu"] image:https://github.com/metanorma/metanorma-cli/workflows/windows/badge.svg["Build Status (Windows)", link="https://github.com/metanorma/metanorma-cli/actions?workflow=windows"] image:https://codeclimate.com/github/metanorma/metanorma-cli/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/metanorma-cli"] image:https://img.shields.io/github/issues-pr-raw/metanorma/metanorma-cli.svg["Pull Requests", link="https://github.com/metanorma/metanorma-cli/pulls"] image:https://img.shields.io/github/commits-since/metanorma/metanorma-cli/latest.svg["Commits since latest",link="https://github.com/metanorma/metanorma-cli/releases"] == 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 https://www.metanorma.com/docs/getting-started/[Getting Started] instead. ==== To install this gem, simply run: [source,sh] ---- 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 (such as Puppeteer and LaTeXML) 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 https://www.metanorma.com/author/topics/install/[Metanorma Installation]. But if you aren't afraid of tinkering deeply, please see the link:docs/installation.adoc[Developer Installation Notes] for advanced details regarding dependencies and Windows installation notes. == Usage === 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: [source, sh] ---- 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: [source,sh] ---- 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: [source,sh] ---- 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. [source] ---- 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. [source, sh] ---- 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`. === 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: [source,sh] ---- metanorma list-extensions ---- To list out the output formats supported by a particular flavor type, run the following command: [source,sh] ---- metanorma list-extensions ---- e.g., [source,sh] ---- 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. [source, sh] ---- 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. [source, sh] ---- metanorma template-repo add my-iso https://github.com/you/my-iso-template ---- == Credits This gem is developed, maintained and funded by https://www.metanorma.com/docs/getting-started/[Ribose Inc.] == License The gem is available under the terms of the http://opensource.org/licenses/MIT[MIT License].