Metanorma: the standard for standards

image:img.shields.io/gem/v/metanorma.svg[“Gem Version”, link=“rubygems.org/gems/metanorma”] image:github.com/metanorma/metanorma/workflows/rake/badge.svg[“Build Status”, link=“github.com/metanorma/metanorma/actions?workflow=rake”] image:codeclimate.com/github/metanorma/metanorma/badges/gpa.svg[“Code Climate”, link=“codeclimate.com/github/metanorma/metanorma”] image:img.shields.io/github/issues-pr-raw/metanorma/metanorma.svg[“Pull Requests”, link=“github.com/metanorma/metanorma/pulls”] image:img.shields.io/github/commits-since/metanorma/metanorma/latest.svg[“Commits since latest”,link=“github.com/metanorma/metanorma/releases”]

Metanorma is dedicated to harmonizing standard documents produced by different standard-setting bodies in a manner that maintains correct semantics while allowing each standard publisher to define appropriate semantic extensions.

Simply put, it allows standards bodies or any other organization to create their own standard or specification document in a best practices manner.

Metanorma is composed of a number of specifications and software implementations. The Metanorma document model is based on the SecureDoc document model.

Metanorma includes the following sub-projects:

the github.com/metanorma/asciidoctor-rfc/[asciidoctor-rfc RFC XML v2 and v3 implementations]

the github.com/metanorma/metanorma-model-iso/[Metanorma ISO model], the github.com/metanorma/metanorma-iso/[metanorma-iso IsoDoc implementation]

github.com/metanorma/metanorma-model-csd[Metanorma CSD model], the github.com/metanorma/metanorma-csd/[metanorma-csd implementation]

github.com/metanorma/metanorma-model-gb[Metanorma GB models, for Chinese standards], the github.com/metanorma/metanorma-gb/[metanorma-gb implementation]

github.com/metanorma/metanorma-model-csand[Metanorma CSAND model], the github.com/metanorma/metanorma-csand/[metanorma-csand implementation]

github.com/metanorma/metanorma-model-m3d[Metanorma M3D model], the github.com/metanorma/metanorma-m3d/[metanorma-m3d implementation]

Installation on supported platforms

MacOS

We recommend macOS users to directly run the Metanorma setup script located here: github.com/metanorma/metanorma-macos-setup

This is a one-stop installation script that setups Ruby, Node and all necessary parts for running Metanorma.

Alternatively, you can also use the Metanorma Docker container (see below).

Linux

Please see: github.com/metanorma/metanorma-linux-setup

Alternatively, you can also use the Metanorma Docker container (see below).

Docker: Windows and other platforms

Please use the Metanorma Docker container: github.com/metanorma/metanorma-docker

//// If you want to run Ubuntu on MacOS, you should do the following beforehand:

source,sh

# Setup docker through dinghy on MacOS: brew tap codekitchen/dinghy brew install dinghy brew install docker docker-machine dinghy create –provider virtualbox

# Run the Ubuntu container: dinghy up eval $(dinghy env) docker run -it ubuntu:18.10 bash


////

Installing individual components

The Metanorma workflow can be utilized via the `metanorma` Ruby gem.

source,sh

gem install metanorma-cli


If you are going to generate PDFs from HTML (which applies to CSD), you will also need to install the node library github.com/GoogleChrome/puppeteer:

nodejs.org/en/download/package-manager/ . (For macOS, `brew install node`)

Usage

Help command:

source,sh

$ metanorma -h Usage: metanorma [options] <file>

-t, --type TYPE                       Type of standard to generate: rfc2, rfc3, iso, gb, csd, csand, m3d
-x, --extensions EXT1,EXT2,... | all  Type of extension to generate per type:
{
  :rfc2=>{:xmlrfc=>"v2.xml"},
  :rfc3=>{:xmlrfc=>"v3.xml"},
  :iso=>{:html=>"html", :html_alt=>"alt.html", :doc=>"doc"},
  :gb=>{:html=>"html", :compliant_html => "compliant_html", :doc=>"doc"},
  :csd=>{:html=>"html", :pdf=>"pdf", :doc => "doc"},
  :csand=>{:html=>"html"},
  :m3d=>{:html=>"html", :doc=>"doc", :pdf => "pdf"},
  :rsd=>{:html=>"html", :doc=>"doc", :pdf => "pdf"}
  :acme=>{:html=>"html", :doc=>"doc", :pdf => "pdf"}
  :mpdf=>{:html=>"html", :doc=>"doc", :pdf => "pdf"}
  :unece=>{:html=>"html", :doc=>"doc"}
}
In addition, xml (outside of rfc2, rfc3) generates IsoDoc XML. If the argument is "all" or the option is
missing, all available extensions are generated.
-f, --format FORMAT                   Format of source file: asciidoc (current default, only format supported)
-r, --require LIBRARY                 Require LIBRARY prior to execution
-w, --wrapper                         Create wrapper folder for HTML output
-d, --data-uri-image                  Encode HTML output images as data URIs
-a, --asciimath                       Preserve AsciiMath in Metanorma XML, instead of transforming it into MathML
-R, --relaton FILENAME                Export Relaton XML (bibdata) for this document to FILENAME
    (Also triggered through -x rxl)
-e, --extract DIR(,ASSET1,ASSET2...)  Extract assets from this document to directory DIR. If ASSET1,ASSET2 are named, only those types of asset are extracted.
-h, --help                            Show this message

Basically it is used like this:

source,sh

$ metanorma –type <chosen-type> [–format input-format] [–extensions EXT1,EXT2…] iso-my-standard-document.adoc


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).

`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.

`datauriimage`

Encode all images as data URIs.

`relaton`

exports the bibdata Relaton XML description of the document (which is part of its Metanorma XML)

to the nominated directory. The filename is the document identifier, if present, else the document filename.

`asciimath`

Preserve AsciiMath in Metanorma XML, instead of transforming it into MathML (which is the default).

`extract`

export assets found in the document to the nominated directory. If no other arguments are given,

then all asset classes are exported, each to its own subdirectory. If trailing arguments are given, they are taken as naming which asset classes to extract from the document. Three asset classes are recognised: `sourcecode`, `image`, and `requirement` (which includes `recommendation` and `permission` elements). The assets are given autonumbered names, unless they were given a `filename` attribute in the source Metanorma XML, which is used instead.

`format`

(optional, specified via `–format` or `-f`) only accepts `asciidoc` for now,

defaults to `asciidoc`

As the `–format` argument is (currently) optional, so:

source,sh

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


`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; e.g.

source,sh

$ metanorma -t mpfd mpfd-bpn.adoc

metanorma

Error: mpfd is not a supported standard type.

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


The `asciimath`, `type`, `extension` and `relaton` options can be omitted if the corresponding metanorma directives are included in the document as Metanorma directives; for Asciidoctor input, these take the form of document attributes `mn-keep-asciimath:`, `mn-document-class:`, `:mn-output-extensions:` and `:mn-relaton-output-file:`, e.g.

source,asciidoctor

My ISO document

:mn-keep-asciimath: :mn-document-class: iso :mn-output-extensions: html,xml,pdf :mn-relaton-output-file: test.xml

.Foreword


Metanorma can also be invoked within Ruby, through the metanorma gem:

source,asciidoctor

require “metanorma”

Metanorma::Compile.new().compile(filename, options)


The options hash has the same structure it does when invoked in metanorma-cli:

`:type`

one of `“iso”`, `“csd”`, `“rsd”`, etc. (mandatory)

`:format`

`:asciidoc` is only value currently allowed

`:extension_keys`

array of symbols: `:all`, `:xml`:, `:doc` etc.

`:wrapper`: true/false `:datauriimage`: true/false `:asciimath`: true/false `:require`: array of libraries to require `:relaton`: exports the bibdata Relaton XML description of the document (which is part of its Metanorma XML) to the nominated directory

Origin of name

Meta- is a prefix of Greek origin (“μετα”) for “`with`” “`after`”. In English, it has ended up meaning “about (its own category)”; e.g. meta-discussion (a discussion about discussion). (For the roundabout way it ended up with that meaning, see en.wikipedia.org/wiki/Meta#Etymology.)

Norma is Latin for “`rule`” and “`standard`”; hence English norm, but also German Norm “standard”.

The Metanorma project is for setting a standard for standard documents created by standards-setting organizations (which is a meta thing to do); hence this name.

Metanorma seeks to embrace all standards documents standards, but not possess any: it can give rise to many “standard” standards, but not limit the extension of any of those standards.

The motto of the project is en.wikipedia.org/wiki/Aequitas[Aequitate] verum, “Truth through equity”. Dealing with all standards fairly (aequitate), we seek not an abstract virtue (veritas), but a practical reality on the ground (verum), that can be used by stakeholders of multiple standards.