README.adoc
= 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
[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 <<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 `template`s compilation tests
. run `sample`s 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].