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:
-
IETF Internet-Drafts and RFCs: the AsciiRFC syntax, the asciidoctor-rfc RFC XML v2 and v3 implementations
-
ISO Standards: the AsciiISO syntax, the Metanorma ISO model, the metanorma-iso IsoDoc implementation
-
CalConnect Standard Documents (CSD): the AsciiCSD syntax, Metanorma CSD model, the metanorma-csd implementation
-
Chinese GuoBiao (GB) Standards: the AsciiGB syntax, Metanorma GB models, for Chinese standards, the metanorma-gb implementation
-
Cloud Security Alliance Normal Documents (CSAND): the AsciiCSAND syntax, Metanorma CSAND model, the metanorma-csand implementation
-
M3AAWG Documents (M3D): the AsciiM3D syntax, Metanorma M3D model, the metanorma-m3d implementation
-
Ribose Specification Documents (RSD): AsciiRSD, RSD XML schema, and the metanorma-rsd implementation
-
Mandatory Provident Fund Schemes Authority of Hong Kong Documents (MPFD): metanorma-mpfd implementation (still at proof-of-concept stage)
-
United Nations Economic Commision for Europe Documents (UNECE): metanorma-unece implementation
Installation on supported platforms
MacOS
We recommend macOS users to directly run the Metanorma setup script located here: https://github.com/riboseinc/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
Alternatively, you can also use the Metanorma Docker container (see below).
Docker: Windows and other platforms
Please use the Metanorma Docker container: https://github.com/riboseinc/metanorma-docker
Installing individual components
The Metanorma workflow can be utilized via the metanorma
Ruby gem.
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 https://github.com/GoogleChrome/puppeteer:
-
Install Node, with at least version 7.6.0: https://nodejs.org/en/download/, https://nodejs.org/en/download/package-manager/ . (For macOS,
brew install node
) -
Install npm: https://docs.npmjs.com/getting-started/installing-node
-
Install puppeteer:
npm install -g --save --save-exact puppeteer
Usage
Help command:
$ 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
-R, --relaton FILENAME Export Relaton XML (bibdata) for this document to FILENAME
-h, --help Show this message
Basically it is used like this:
$ 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 alsorequire
). 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. 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.
format
-
(optional, specified via
--format
or-f
) only acceptsasciidoc
for now, defaults toasciidoc
As the --format
argument is (currently) optional, so:
$ 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.
$ metanorma -t mpfd mpfd-bpn.adoc
[metanorma] Error: mpfd is not a supported standard type.
$ metanorma -t mpfd -r metanorma-mpfd mpfd-bpn.adoc
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 https://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 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.