Metanorma’s approach to authoring documents

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 XML document based on formal schema, and outputs end documents in appropriate formats (HTML, PDF, MS Word) according to Metanorma flavor used.

Document model

The Metanorma document model used in document generation intends to introduce rigour into 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. 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 would allow checking for consistency in format and content, and expedite authoring and quality control of ISO standards. 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.

AsciiDoc and Asciidoctor

AsciiDoc was chosen as the markup language for writing Metanorma documents, and Asciidoctor is the tool used to convert the document model representation of standards.

AsciiDoc is somewhat 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).

Since Metanorma uses Asciidoctor, and Asciidoctor can output text and HTML, if desired the Asciidoctor toolchain can be used to preview a Metanorma document as it is being authored. However, since Metanorma toolchain outputs HTML and MS Word files, there should not be much need for this.

See Writing AsciiDoc for beginner’s intro and some advice on authoring for Asciidoctor.

Differences from Asciidoctor

While Metanorma uses AsciiDoc markup, there are some specifics in how it is interpreted, as is documented here. In addition, Metanorma imposes a much more strict and hierarchical document model than Asciidoctor 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. Asciidoctor allows some flexibility in table markup (though its a table cell format taking arbitrary Asciidoctor markup); Metanorma will not process arbitrary formatting properly.

Asciidoctor has some formatting constraints because of its own document model that users need to be aware. For example, Asciidoctor 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.)

See Document format section of author’s documentation for some differences of how Metanorma’s interpretation of basic AsciiDoc features differs from that of Asciidoctor, and for custom macros Metanorma has added.

Metanorma document model does not impose AsciiDoc/Asciidoctor 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.