Metanorma: Aequitate Verum

Metanorma for OGC

Writing Metanorma AsciiDoc

General

Metanorma documents are typically written in a markup language called “Metanorma AsciiDoc”.

Metanorma AsciiDoc is created as an extended superset of the normal AsciiDoc markup language in order to support the complex requirements of standards and model-based content creation.

Note
 A markup language allows applying processing instructions to textual content.

Metanorma AsciiDoc inherits the ease of use of normal AsciiDoc but lets you do much more. AsciiDoc is very similar to Markdown or Wiki formatting but provides more precise markup for creating text documents, for example to create a bibliography section or an index.

Since Metanorma AsciiDoc is a “plain text” markup language, you can use any plain text editor to create and edit its files (.adoc files).

Structure

A Metanorma AsciiDoc document consists of several basic components:

  • Document header

  • Clauses, sections

  • Blocks

  • Text formatting

This guide introduces these concepts through a real life example.

OGC document structure

An OGC document is in the following structure:

  • Preface sections. There are 5 mandatory preface sections: Abstract, Keywords, Security considerations, Submitting organizations and Submitters.

  • 1. Scope

  • 2. Normative references

  • 3. Terms and definitions

  • 4. Conformance

  • 5 and onwards. Document content.

  • Annex A. Abstract test suite or Conformance test suite

  • Annex N. Glossary (last Annex)

  • Bibliography

Note
 In legacy OGC documents, “Conformance” may be section 2, with Normative references and Terms and definitions pushed to 3 and 4 positions.
Note
 In OGC Engineering Reports, "Submitters" is rendered as "Contributors".

Automatic numbering in Metanorma

Metanorma supports auto-numbering for blocks, such as tables and figures. Metanorma extends auto-numbering to formulas (which are encoded as stem blocks) and notes.

Metanorma supports auto-numbering for the following document elements, so you do not need to specify any numbering for them:

  • figures

  • tables

  • admonitions (such as NOTEs)

  • examples

  • formulas (inline or block)

  • sourcecode, pseudocode

  • permissions, recommendations and requirements.

The conventions for numbering vary by Metanorma flavour, but the default is to number all elements consecutively in the main body of a document, and separately in each Annex/Appendix, prefixed bt the Annex/Appendix number.