File: README — Documentation for metanorma (0.2.6)

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 Metanorma document model (previously called StanDoc)
IETF Internet-Drafts and RFCs: the AsciiRFC syntax, the asciidoctor-rfc RFC XML v2 and v3 implementations
ISO Standards: the AsciiISO syntax, the IsoDoc Models, the asciidoctor-iso IsoDoc implementation
CalConnect Standard Documents (CSD): the AsciiCSD syntax, CSD Models, the asciidoctor-csd implementation
Chinese GuoBiao (GB) Standards: the AsciiGB syntax, GbDoc Models, the asciidoctor-gb implementation
Cloud Security Alliance Normal Documents (CSAND): the AsciiCSAND syntax, CSAND Models, the asciidoctor-csand implementation
M3AAWG Documents (M3D): the AsciiM3D syntax, M3D Models, the asciidoctor-m3d implementation

Installation

All-in-one install, MacOS

macOS users can 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.

Installation, Ubunto

# Set up prerequisites
apt-get update
apt install -y git make ruby-bundler ruby-dev libxml2-dev libxslt-dev default-jre
gem install bundler
gem install nokogiri -v '1.8.4'
gem install metanorma-cli

(You may need to run these as sudo)

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

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

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 Mac, 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,...   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", :doc=>"doc"},
    :csd=>{:html=>"html", :pdf=>"pdf"},
    :csand=>{:html=>"html"},
    :m3d=>{:html=>"html", :doc=>"doc"},
    :rsd=>{:html=>"html"}
  }
  In addition, xml (outside of rfc2, rfc3) generates IsoDoc XML
  -f, --format FORMAT              Format of source file: asciidoc (current default, only format supported)
  -r, --require LIBRARY            Require LIBRARY prior to execution
  -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
format: (specified via --format or -f) only accepts asciidoc for now

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

metanorma --type iso -x html iso-my-standard-document.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.