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.

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
	...

Practice time

:exercise-file: exercise-2-2 include::exercises.adoc[tags=intro;exercise-2-2]

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

+++ <div class="cta tutorial"><a class="button" href="/learn/lessons/lesson-2-3-1/">Start next lesson »</a></div> ++++

Edit this page on GitHub →