= Metanorma: the standard for standards

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 https://github.com/riboseinc/standoc-models[Metanorma document model (previously called StanDoc)]
* IETF Internet-Drafts and RFCs: the https://datatracker.ietf.org/doc/draft-ribose-asciirfc/[AsciiRFC syntax], the https://github.com/riboseinc/asciidoctor-rfc/[asciidoctor-rfc RFC XML v2 and v3 implementations]
* ISO Standards: the AsciiISO syntax, the https://github.com/riboseinc/isodoc-models/[IsoDoc Models], the https://github.com/riboseinc/asciidoctor-iso/[asciidoctor-iso IsoDoc implementation]
* CalConnect Standard Documents (CSD): the AsciiCSD syntax, https://github.com/riboseinc/csd[CSD Models], the https://github.com/riboseinc/asciidoctor-csd/[asciidoctor-csd implementation]
* Chinese GuoBiao (GB) Standards: the AsciiGB syntax, https://github.com/riboseinc/gbdoc[GbDoc Models], the https://github.com/riboseinc/asciidoctor-gb/[asciidoctor-gb implementation]
* Cloud Security Alliance Normal Documents (CSAND): the AsciiCSAND syntax, https://github.com/riboseinc/csand[CSAND Models], the https://github.com/riboseinc/asciidoctor-csand/[asciidoctor-csand implementation]
* M3AAWG Documents (M3D): the AsciiM3D syntax, https://github.com/riboseinc/m3d[M3D Models], the https://github.com/riboseinc/asciidoctor-m3d/[asciidoctor-m3d implementation]
//* Ribose Specification Documents (RSD): AsciiRSD, RSD XML schema, and the https://github.com/riboseinc/asciidoctor-rsd[asciidoctor-rsd implementation]


== Installation

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

[source,sh]
----
gem install metanorma
----

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:

[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,...   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:

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

Options:

//, `rsd`
`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:

[source,sh]
----
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 https://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.