README.adoc in metanorma-cli-1.1.8 vs README.adoc in metanorma-cli-1.2.0

- old
+ new

@@ -1,6 +1,6 @@ -= Metanorma's command-line interface (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://img.shields.io/travis/metanorma/metanorma-cli/master.svg["Build Status", link="https://travis-ci.org/metanorma/metanorma-cli"] image:https://codeclimate.com/github/metanorma/metanorma-cli/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/metanorma-cli"] image:https://ci.appveyor.com/api/projects/status/vqo2221uwcaov8kx?svg=true["Build Status", link="https://ci.appveyor.com/project/metanorma/metanorma-cli"] @@ -12,13 +12,194 @@ 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. ==== -At its core, installing this gem is as easy as `gem install metanorma-cli`. -That will install the `metanorma` executable, which you can use with all +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, certain dependencies such as Puppeteer may have to be installed separately, -and the process is a little more complex if you’re using Windows. -For advanced details regarding dependencies and Windows installation notes, -refer to the link:docs/installation.adoc[full installation manual]. +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 <flavor> +---- + +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 +---- + + +== 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].