Sections

Sections define hierarchy levels in your document and are equivalent to chapters. The document title is the highest section and is created by prepending a = sign in front of the heading. If you want to go one level deeper in the hierarchy, add another =. Here’s an example:

= Document title
== Section 1
=== Section 1.1
==== Section 1.1.1
===== Section 1.1.1.1
== Section 2
…

Section headings and validation

Metanorma provides a document model that determines what sections need to appear in a document. Let’s have a look at the standard document model (standoc) to understand what kinds of sections appear in a typical Metanorma document.

Note	The standoc flavour does not correspond to any one SDO: it is a default model that other flavors are based on.

Figure 1. A UML representation of all section classes in Metanorma

A typical Metanorma document can contain the following sections:

Abstract
Foreword
Introduction
Acknowledgments
Scope
Conformance
Normative references
Terms and definitions
Definitions
Clauses
Symbols and abbreviated terms
Bibliography
Annex

To successfully validate a document, the compiler needs to know what sections are in the document. Metanorma relies on these predefined section titles to check them against the document model. However, not all sections need an identifier, for example, your ordinary content sections fall under the category of clause section, and are not further standardized.

Note

Each organization is based on the standard document model but they can omit sections or make them mandatory, if they choose to. For example, only NIST uses the acknowledgments section, whereas other SDOs do not require it. Flavours may overrule these pre-defined section titles with titles of their own, or may choose not to recognise at least some of them as special sections. Check the flavor documentation for more details on how your SDO uses Metanorma.

Deviating section titles

If you want to use a different title or create a document in a language other than English, you need to add metadata in square brackets to ensure that sections are recognized. Plain AsciiDoc already provides some section metadata that Metanorma uses for document validation:

[abstract]
[acknowledgments]
[appendix]
[bibliography]
[index]
[preface]

Documents can contain only one Abstract, one Acknowledgements section, and one Index. On the other hand, documents can have any number of appendixes (or annexes), bibliographies, and prefatory sections, each of them marked with those attributes. There are also some Metanorma-specific section identifiers, that follow the syntax [heading=section]:

[heading=terms and definitions]
[heading=foreword]
[heading=introduction]
[heading=scope]
[heading=symbols and abbreviated terms]

= Document title

== Abstract

== Foreword

[preface] (1)
== Introduction to version 3 of this standard

[bibliography] (2)
== Normative references

[heading=terms and definitions] (3)
== Terms, definitions, and abbreviations

[bibliography]
== Bibliography
	...
[appendix,obligation=informative] (4)
== Annex
	...

This section is an introduction but the compiler can not recognize it because it deviates from plain == Introduction. The preface attribute ensures that the document structure is still valid.
The Normative references section contains references to related standards. The compiler needs the [bibliography] tag, so that it renders the reference correctly.
Use the heading tag to assign section types specific to Metanorma.
Here, the appendix is called “Annex”, and needs the appendix tag to define what kind of section it is. You can specify if a section is normative or informative by adding the obligation identifier after the section identifier.

Practice time

The code for this exercise is available on GitHub.

The corresponding file is named exercise-2-2.adoc

Look at the prepopulated Metanorma document. There are many clauses describing the content but there are sections missing to form a correct standard document. Add the following sections:

We’ve built the basic structure of a Metanorma document. Let’s add some content to our document in the next lesson.

Start next lesson »