What Metanorma is

Nick Nicholas on 05 Dec 2018

We’ve said what Metanorma is for, but we have not said much about what Metanorma is like as a tool.

Overall, Metanorma provides three things:

a set of standard document metamodels (ISO 36001), that allows different standardization bodies to create their own standardized document model for their standard documents;
a standard XML schema (ISO 36002), as machine-readable standardization documents, that is the serialized form of the document models mentioned above; and
a publishing toolchain that enables authors of standard documents to handle their documents from authoring to publishing in an end-to-end, “author-to-publish” fashion.

Metanorma, the end-to-end standards publishing toolchain

Metanorma is software that transforms input text into output formats. It currently supports output to HTML, PDF (via HTML), and Microsoft Word.

The input text is in a markup format, which represents the intent of the author around formatting and structure. Currently, the only input markup supported is Metanorma AsciiDoc.

Note	Marked up text is text, not a Word document, which means you will need to get familiar with text editors (Notepad, TextEdit), if you aren’t already.

Note	Microsoft Word output is in the older Word `DOC` format.

The transformation to output formats happens via an intermediate Metanorma XML file, which is easier to manipulate programmatically, and which can be formally validated.

Flavors of Metanorma documents

Metanorma comes in various flavors, one for each standards body it supports. The standards bodies currently supported include:

Metanorma defines common formatting and conventions across standards; the various flavors provide functionality specific to each standards body. That includes different validation, different formatting options, and different styling.

Setting Metanorma up and running it

Metanorma is invoked on the command line, and you will need to set up a programming environment for Metanorma to work on the command line.

Note	We are currently setting up a gateway to run Metanorma online, so that you can submit Metanorma input files to a web server, and get output files back. But in the long run, if you are managing the workflow around your document, you will still need to set up processing of the document locally.

To get started, you need to set up your local programming environment.

Setup instructions are given for the following platforms:

macOS: https://github.com/metanorma/metanorma-macos-setup
Linux: https://github.com/metanorma/metanorma-linux-setup
Windows: https://github.com/metanorma/metanorma-windows-setup
Docker: https://github.com/metanorma/metanorma-docker

Once you are set up (which will take a little while), you should be able to create and compile a Metanorma document shown below.

Authoring a basic document in Metanorma

Create the following as a new document, saving it to a file as test.adoc:

test.adoc

= Test

== Clause 1

A requirement.

This document is in AsciiDoc markup:

= indicates the document title
== indicates the section heading of a first-level section within the document
The content text A requirement. is considered content of the section defined above it.

Metanorma AsciiDoc is documented online (with typical AsciiDoc described here), so we won’t be giving detailed tutorials of how AsciiDoc markup works, but we will provide you the basics to get started.

Let’s compile this as an ISO document!

In your command line interface, navigate to where you have created the document, and run the following commands.

On macOS and Linux (native installation):

$ cd <where you saved test.adoc>
$ metanorma -t iso test.adoc

On Windows (native installation):

$ cd <where you saved test.adoc>
$ metanorma -t iso test.adoc

If you are using the Docker installation:

$ docker run -v ${pwd}:/metanorma/ metanorma/metanorma "metanorma -t iso test.adoc"

Note	On Windows, there are some limitations on folder sharing for Docker. Please consult Docker documentation.

What Metanorma outputs

You will see the following files created in the same folder as test.adoc:

test.xml
test.html
test.alt.html
test.doc

All these documents will contain just the section title (“Clause 1”) and the single line of content (A requirement.).

The HTML and DOC are already styled to match the ISO document templates defined for Metanorma, including a (very sparsely populated) cover page.

The two HTML pages are styled differently:

the test.html file is more sparsely formatted, made close to the Word template style of ISO (we call this compliance-optimized); yet
the test.alt.html document is more stylish and easier to read (we designed it to be human-optimized).

And the thing is, you did not have to format a thing, to generate three different renderings of the document, including a Word document that follows the ISO stylesheet slavishly.

Metanorma has taken care of the formatting for you. You just need to make sure you get the content right.

Note	Which means providing more content than just a clause title.

It’s like magic. Command-line, pedantic magic, to be sure, and magic that sometimes throws up cryptic error messages. But still magic.

Figure 1. The author conjuring some Metanorma magic

The test.xml document is the formally compliant representation of the document contents, and unlike the HTML and DOC versions, there is no formatting in there. If you open it up, you will see some metadata about the document ---

test.xml (contributor)

<contributor>
  <role type="author"/>
  <organization>
    <name>International Organization for Standardization</name>
    <abbreviation>ISO</abbreviation>
  </organization>
</contributor>

We said that this is an ISO document, so Metanorma has gone ahead and provided the information that this is a document with ISO as its corporate author --- though much of the metadata is empty.

You will also see the one line of content underneath the metadata:

test.xml (sections)

<sections>
  <clause id="_clause_1" inline-header="false" obligation="normative">
    <title>Clause 1</title>
    <p id="_ae976677-104c-484e-b31b-14ef21c534b8">A requirement.</p>
  </clause>
</sections>

Even here, Metanorma has supplied some default information that may come in handy for rendering: the clause heading is rendered as a separate line, not inline; the clause it introduces is assumed by default to be normative, not informative; and the clause has an identifier, which can be used for cross-referencing within the document --- which the renderer will know to update with the current value of the clause number.

While you were generating the document, you will have noticed several error messagers roll past the console:

ISO style: Initial section must be (content) Foreword
ISO style: Prefatory material must be followed by (clause) Scope
ISO style: Normative References must be followed by Terms and Definitions
ISO style: Document must contain at least one clause

ISO specifically expects to see a whole lot of sections in any standards document that you have not provided, and you are being correctly warned about that.

There are also errors raised against specific line numbers of the XML document (since that is what is being formally validated against a document schema).

In the test.adoc file provided above, the following errors are shown:

element "sections" not allowed yet; missing required element "preface" @ 46:11
element "sections" incomplete; expected element "clause" or "terms" @ 51:12
element "iso-standard" incomplete; missing required element "bibliography" @ 52:16

For example, @ 52:16 refers to line 51, character 16 (the </iso-standard> tag, the last tag of the document) of the test.xml Metanorma XML file. It is complaining about the fact that the document does not contain a <bibliography> element: ISO documents are required to contain a “Bibliography” section according to ISO Directives Part 2.

If we remove the content text (A requirement.) from test.adoc, the following extra message will be shown:

element "clause" incomplete; expected element "admonition", "clause", "dl", "example", "figure", "formula", "ol", "p", "quote", "review", "sourcecode", "table" or "ul" @ 49:10

@ 49:10 refers to line 49, character 10 (the </clause> tag, where the one clause in the document has ended) of the test.xml Metanorma XML file, and it is complaining that the clause after its title is empty. Clauses are expected to contain at least one block of text, and the error message lists the kinds of blocks of text it would expect to see.

Much of the time, you will still get output from Metanorma despite its complaints about structure; but if you want to make sure your document is compliant, you should go through the warnings generated at least once.