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 Getting Started instead. |
To install this gem, simply run:
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 Metanorma Installation.
But if you aren’t afraid of tinkering deeply, please see the 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:
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:
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:
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.
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.
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:
metanorma list-extensions
To list out the output formats supported by a particular flavor type, run the following command:
metanorma list-extensions <flavor>
e.g.,
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.
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.
metanorma template-repo add my-iso https://github.com/you/my-iso-template
Credits
This gem is developed, maintained and funded by Ribose Inc.
License
The gem is available under the terms of the MIT License.