Using the Metanorma CLI

Usage samples

For a single document:

$ metanorma iso-my-standard-document.adoc

or

$ metanorma --type iso -x html iso-my-standard-document.adoc

if type and extensions are not defined in adoc header

Full syntax & options

General help message can be shown by metanorma help

Commands:
  metanorma collection FILENAME -w, --output-folder=OUTPUT_FOLDER  # Render HTML pages from XML/YAML colection
  metanorma compile FILENAME                                       # Compile to a metanorma document
  metanorma config                                                 # Manage configuration file
  metanorma help [COMMAND]                                         # Describe available commands or one specific command
  metanorma list-doctypes                                          # List supported doctypes
  metanorma list-extensions                                        # List supported extensions
  metanorma new NAME -d, --doctype=DOCTYPE -t, --type=TYPE         # Create new Metanorma document
  metanorma site                                                   # Manage site for metanorma collections
  metanorma template-repo                                          # Manage metanorma templates repository
  metanorma version                                                # Version of the code

Options:
  -s, [--no-progress], [--no-no-progress]  # Don't show progress for long running tasks (like download)
                                           # Default: true

Also you can get a help message for a specific command for example metanorma help compile:

Usage:
  metanorma compile FILENAME

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=REQUIRE]                                        # 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
  -d, [--datauriimage], [--no-datauriimage]                      # Encode HTML output images as data URIs
  -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)
  -o, [--output-dir=OUTPUT_DIR]                                  # Directory to save compiled files
      [--agree-to-terms], [--no-agree-to-terms]                  # Agree / Disagree with all third-party licensing terms presented (WARNING: do know what you are agreeing with!)
      [--no-install-fonts], [--no-no-install-fonts]              # Skip the font installation process
      [--continue-without-fonts], [--no-continue-without-fonts]  # Continue processing even when fonts are missing
  -s, [--no-progress], [--no-no-progress]                        # Don't show progress for long running tasks (like download)
                                                                 # Default: true

Compile to a metanorma document

A bit more details on options:

type

(mandatory, specified via --type or -t) takes one of the following types: rfc2, rfc3, iso, gb, csd, csand, m3d, rsd. Each of these corresponds to a standards class and a Metanorma gem; the list of standards classes supported by the script by default will grow (see also require).

extension

(optional) specifies the output formats to be generated. If not specified, all possible output formats are generated. The output formats generated are constrained by what has been defined for each standard type. All standards can generate Metanorma XML (xml), and at least one of HTML (html), DOC (doc), PDF (pdf). Some standards generate alternative HTML renderings (e.g. html_alt for ISO).

Actual list of supported types and extension`s you can get with `metanorma list-doctypes

wrapper

create a separate folder for each instance of HTML output generated; the folder is named the same as the output file, without the .html suffix. Used to make distribution of HTML outputs more straightforward.

format

(optional, defaults to asciidoc, specified via --format or -f) only accepts asciidoc for now

require

If you wish to use metanorma with a document class which has not been included in the types recognised by the metanorma script, you will need to name the corresponding Metnorma gem explicitly with the -r option. For example:

$ metanorma -t mpfd mpfd-bpn.adoc

[metanorma] Error: mpfd is not a supported standard type.

$ metanorma -t mpfd -r metanorma-mpfd mpfd-bpn.adoc