metanorma-cli

= 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 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].