Metanorma’s approach to authoring documents

General

Essentially, Metanorma converts given source document — a set of files authored using AsciiDoc markup—to an XML-based presentation of the document according to the document model.

The XML format intends to introduce rigour into the each standard’s authoring process, and is described in corresponding documentation.

Metanorma validates the resulting XML document based on formal schema, and outputs end deliverables in appropriate formats (HTML, PDF, MS Word, etc.) according to the Metanorma flavor used.

Metanorma document model

The Metanorma Standard Document document model provides rigour in the standards authoring process; existing document templates do not support such rigour down to the element level. It also introduces flexibility by decoupling the document structure from its presentation.

Formal definitions of standards prescribe the contents of standards to a level amenable to an explicit document model.

For example, the ISO International Standard format, as prescribed in ISO/IEC DIR 2 "Principles and rules for the structure and drafting of ISO and IEC documents", is one of the more detailed such prescriptions available.

A formal document model allows checking for consistency in format and content, and expedite authoring and quality control of standardized documents. Authoring standards through a more abstract formal model also permit enhanced functionality such as cross-reference link checking and auto-numbering of sections, figures, tables and formulas. Outputting a document in different languages also becomes straightforward.

Input syntax: Metanorma AsciiDoc

Introduction

Metanorma supports input using Metanorma AsciiDoc, based on the AsciiDoc syntax. Specifically, Metanorma AsciiDoc is built on the syntax of the Asciidoctor version of AsciiDoc.

AsciiDoc is similar to both Markdown and DocBook: it combines the relative ease of use of the former (using relatively lightweight markup), and the rigour and expressively of the latter (it has a well-defined syntax, and was in fact initially developed as a DocBook document authoring tool).

Tip	See Metanorma AsciiDoc for an introduction and advice on authoring with Metanorma AsciiDoc.

Differences from typical AsciiDoc syntax

Metanorma AsciiDoc differs from typical AsciiDoc markup, especially for its interpretation of directives.

This is especially important to know for those coming from a general AsciiDoc / Asciidoctor-AsciiDoc background.

Metanorma imposes a much more strict and hierarchical document model than typical AsciiDoc does.

In particular, it has a strict hierarchy of sections, then blocks, then inline markup, which cannot be mixed. A table for example cannot occur inside a list, and a section cannot occur inside a table.

While Asciidoctor AsciiDoc allows some flexibility in table markup (through its a table cell format taking arbitrary AsciiDoc markup), Metanorma will not process arbitrary formatting.

Asciidoctor AsciiDoc has some formatting constraints because of its own document model that users need to be aware.

Asciidoctor AsciiDoc disallows multiple paragraphs in footnotes by design; and it has a strict hierarchy about how elements can be embedded within other elements, though still less strict than in Metanorma (so for example a list cannot be nested within a paragraph, it can only be used as a separate paragraph.)

Tip	For Metanorma AsciiDoc features and interpretation differences between Metanorma AsciiDoc with typical AsciiDoc, see Document format section of author’s documentation.

Note	Metanorma document model does not impose AsciiDoc constraints, so if desired you can edit the generated XML presentation (say, to break up paragraphs within a footnote) and subsequently regenerate final deliverables from that edited XML.

Previewing with typical AsciiDoc tools

Existing AsciiDoc tools, such as Asciidoctor plugins, could be used to preview a Metanorma document as a generic AsciiDoc document.

However, beware that Metanorma AsciiDoc features and flavor-specific cannot be understood by such plugins and the output will not fully match actual Metanorma output.

Moreover, Metanorma also renders HTML and Microsoft Word output, which greatly differs from that of non-Metanorma tools.