= 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/rake/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-cli/actions?workflow=rake"] 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
To install this gem, simply run:
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 <<external-dependencies,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 https://www.metanorma.com/author/topics/install/[Metanorma Installation].
But if you aren't afraid of tinkering deeply, please see the https://www.metanorma.com/install/manual-installation/[Developer Installation Notes] for advanced details regarding dependencies and Windows installation notes.
=== External dependencies
The Metanorma toolchain supports certain features when optional dependencies are installed. Please refer to the following table for them.
[cols="1,1,1"] |=== |Dependency |Mandatory? | Target component / purpose
|https://git-scm.com/[`git] | :white_check_mark: |metarnoma-cli(templates), https://github.com/fontist/fontist[fontist`]
|https://www.oracle.com/java/technologies/[`java] | :white_check_mark: |https://github.com/metanorma/mn2pdf[mn2pdf], https://github.com/metanorma/metanorma-standoc[metanorma-standoc`]
|https://xml2rfc.tools.ietf.org/[`xml2rfc] (python) | :white_large_square: |https://github.com/metanorma/metanorma-ietf[metanorma-ietf`]
|https://inkscape.org/[`inkscape] | :white_large_square: |https://github.com/metanorma/isodoc[isodoc`], SVG to EMF functionality (for inserting SVGs into Word)
|https://graphviz.org/[`graphviz] | :white_check_mark: |https://github.com/lutaml/lutaml[lutaml`] generation of LutaML diagrams
|http://www.plantuml.com/[`plantuml] | :white_large_square: |https://github.com/metanorma/metanorma-standoc[metanorma-standoc`] generation of PlantUML diagrams
|===
== Usage
Refer to https://www.metanorma.org/install/usage[Metanorma CLI usage].
== Release
=== General overview
Once we are ready for release of metanorma-cli, it means:
. required all metanorma-cli's dependencies are released or ready for upcoming release
. last rake workflow for main branch is green (can be started https://github.com/metanorma/metanorma-cli/actions/workflows/rake.yml[manually])
Simply bump metanorma-cli gem version and push. This will initiate rake workflow that:
. run rake tests
. run templates compilation tests
. run samples compilation tests
The test matrix defined as JSON files in link:./.github/workflows/samples-smoke-matrix.json[samples test matrix] and link:./.github/workflows/templates-smoke-matrix.json[templates test matrix]
One all tests is passed, packed-mn 's and docker 's releases will be initiated
=== Responsibility
[cols="1,1"] |=== |Repositories | Responsible
|metanorma-cli's dependencies (including transitive) from the GitHub metanorma organization
|@opoudjis
|packed-mn, docker, chocolatey, snap, brew and any other unusual CI failures
|@CAMOBAP
|===
== 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].