Quickstart Guide

Tip
This guide has been authored for ISO standards, but most of it applies to all Metanorma standards. We indicate where guidance differs for different standards classes. See List of Metanorma processors.

This is a guide on how to get started using Metanorma to create documents aligned with different standards classes (such as ISO, GB, CSD, etc), in Microsoft Word and HTML formats. This guide is written to apply generically across the standards classes that can be expressed in Metanorma; guidance specific to a particular standards class is given as TIPs.

Metanorma takes text in the Asciidoctor markup language as input (consult the Asciidoctor User Manual on the basics of this markup language). Metanorma makes some adjustments to the text format for its requirements; these adjustments (which we refer to as Metanorma Asciidoctor, or AsciiISO) are documented in relevant sections of this documentation. Metanorma uses Asciidoctor to generate Metanorma XML, as an intermediate, semantic representation of standards content. Metanorma XML in turn is processed by the isodoc gem to generate output in Microsoft Word (.doc) and HTML (.html).

Even quicker summary

In order to start a new Metanorma document, or migrate your document from Word:

  1. Install [installation] (for your specific Metanorma standards class)

  2. Clone the AsciiISO Rice

To migrate:

  1. Use our reverse_asciidoctor gem to help you convert a Word document into Asciidoctor. Be warned that the conversion will not be 100% clean, and you will have to manually fix some syntax (especially if your Word document contains an index, stray anchors, and equations).

  2. Move the content back to the cloned isodoc-rice.

  3. The isodoc-rice repository is set up for the ISO standards class; if you are not working with ISO, change its makefile to refer to the correct standards class (e.g. from bundle exec metanorma -t iso -x doc,xml,html $^ to bundle exec metanorma -t rsd -x doc,xml,html $^

Installing on Linux and macOS

Install Metanorma-ISO gem and its dependencies:

You can install the metanorma-cli gem, and all its dependencies, through the Ruby gem installer:

gem install metanorma-cli

If you want the latest version (note: may not be stable due to active development), you can install it from Github:

git clone https://github.com/metanorma/metanorma-cli.git
cd metanorma-cli
gem build *.gemspec
gem install *.gem
bundle update

The final bundle update step updates the dependent gems, and is necessary because those gems are even more heavily under development.

Tip

The Metanorma tool is a suite of Ruby gems, and works on the command line. The Ruby programming language can be installed on Windows (e.g. https://rubyinstaller.org), but is typically run on a Unix command line—including Linux and MacOS. The following instructions are for the Unix console.

The starting poing of the Metanorma tool is the metanorma-cli gem (command line interface); it references various other gems that the tool is based on, including the converter from Asciidoctor to Metanorma XML (metanorma-standoc), the converters from Metanorma XML to HTML and Word (isodoc, html2doc), the variants of Metanorma for different standards classes (metanorma-iso, metanorma-csd, etc.), and tools for processing bibliographies (relaton, isobib etc.)

The Metanorma tools processing Asciidoctor, in turn, build on the Asciidoctor gem, which interprets the Asciidoctor markup language in Ruby. Installing the Metanorma gem will install the Asciidoctor gem, if it is not already installed.

Ruby comes with Linux and MacOS. Asciidoctor-ISO uses at minimum Ruby 2.3.0, and you may need to update your Ruby instance to use that version. Refer to https://www.ruby-lang.org/en/documentation/installation/

Setting up a new project

At its simplest, all you need is a text document in Asciidoctor-like AsciiISO format, which you compile using the Metanorma-ISO gem.

To keep document dependencies in order, place your document in a distinct folder:

mkdir new_standard
cd new_standard
vi new_standard.adoc

To compile the document, execute the asciidoctor script, flagging it to use a specific standards class with the -t flag (refer to [stupported-standards] for the abbreviations used); e.g.

metanorma -t iso new_standard.adoc

This will generate two files from the new_standard.adoc document (provided it is well-formed):

  • new_standard.html, a standalone HTML document,

  • new_standard.doc, a Word document (currently in the pre-2007 .doc format, but Microsoft Word will open it fine).

Both these files are generated via an intermediate XML file, new_standard.xml, which represents the structure of the document as it is formally defined by the standards body, and captured in the Metanorma XML schema.

Even if there are no errors in the Asciidoctor syntax, the document may still raise warnings to the console as it is being validated. The validation comes from the formal definition of the standard class (e.g. ISO/IEC DIR 2 in the case of ISO and IEC), and consists of two parts: warnings about document content (e.g., for ISO, requiring space before a percentage sign; requiring that the scope not contain text that looks like a recommendation); and warnings about document structure. The latter are generated by running the generated XML against the ISOXML schema, and report the line numbers of the XML document where issues are observed.

Even if there are no errors in the syntax, the document may still raise warnings to the console as it is being validated. The validation comes from ISO/IEC DIR 2, and consists of two parts:

  • Warnings about document content (e.g., requiring space before a percentage sign, or requiring that the scope not contain text that looks like a recommendation).

  • Warnings about document structure (found from running the generated XML against the ISOXML schema, they report the line numbers of the XML document where issues are observed).

Starting with an example project

Perhaps the simplest way to get started is to take an existing Metanorma-ISO document and edit it, observing how it approaches various formatting tasks.

The "Rice document" is the ISO’s model document of an international standard. An Metanorma-ISO version of the document is available at https://github.com/metanorma/isodoc-rice/. We suggest downloading the site, and editing it.

The iso-rice-en.adoc document consists of a document header, and it references the separate body/body-en.adoc document for the document proper (include::body/body-en.adoc[]). You can just continue on with the document text after the document header—so long as you remember to leave a blank line between the two.

Learning the AsciiDoc-based syntax

To author AsciiDoc documents, you need to be familiar with the core AsciiDoc syntax, as well as the syntax extensions and conventions that are specific to Metanorma-ISO.

Migrating existing documents from Microsoft Word

  1. Use our reverse_asciidoctor gem to help you convert a Word document into AsciiISO.

    You will likely have to manually clean up some syntax (especially if your Word document contains an index, stray anchors, and equations): don’t rely on the automatic conversion to be 100% correct.

Migrating existing documents from Microsoft Word:

  1. Use our reverse_asciidoctor gem to help you convert a Word document into AsciiISO.

      You will likely have to manually clean up some syntax
      (especially if your Word document contains an index, stray anchors, and equations):
      don’t rely on the automatic conversion to be 100% correct.
    . Move the content back to the cloned isodoc-rice.