Document sections

Sections are marked off in Asciidoc with titles prefixed by at least two equal signs, ==. === indicates a first level subsection; ==== a second level subsection; and so on.

Fixed section names

Metanorma relies on certain pre-defined section titles to identify the different kinds of sections in the document, namely these:

  • Abstract

  • Introduction

  • Scope

  • Normative References

  • Terms and Definitions

  • Symbols and Abbreviations

  • Bibliography

Note

A dedicated topic expands on Terms and Definitions section grammar, specifically.

As an alternative (if the document deviates from that naming structure, or is in a language other than English), the section can be prefixed with a heading= attribute that provides the English canonical form of the section name. For example:

== Normative References

[heading=terms and definitions]
== Terms, definitions and abbreviations

Blank subclases

Blank subclause headings can be given like this:

=== {blank}

These are used when you want to give a subclause number for a new subclause, but without an associated header text. For example,

=== Physical and chemical characteristics

==== {blank}

The mass fraction of moisture, determined in accordance with...

renders as

4.2. Physical and chemical characteristics

4.2.1. The mass fraction of moisture, determined in accordance with…​

Note

This notation should not be used to implement paragraph numbering as required for e.g. UNECE. The UNECE Metanorma flavor treats each paragraph as a distinct clause and automatically numbers it.

Obligations

The obligation of a section—whether it is normative or informative—is indicated via the attribute “obligation” (see example below).

For most sections, this is fixed; for annexes and clauses, the default value of the obligation is "normative" and users need to set the obligation to "informative" as a section attribute if needed. For example:

[[AnnexA]]
[appendix,obligation=informative]
== Determination of defects

Foreword

The Foreword of a standard is detected as any text between the document header and the first section header.

The example below specifies the .Foreword title to the foreword in the source. (Strictly speaking, this is the caption of the first paragraph in the foreword, but it is used as the foreword header since the Foreword must precede any Asciidoctor section headers.) Metanorma will supply the "Foreword" title if no such title is given.

[[foreword]]
.Foreword
The Calendaring and Scheduling Consortium ("`CalConnect`") is global non-profit
organization with the aim to facilitate interoperability of technologies across
user-centric systems and applications...

Symbols and Abbreviations

Symbols and Abbreviations sections are expected to be simple definition lists (“labelled lists” in Asciidoctor nomenclature).

Metanorma takes care of sorting the symbol entries in the order prescribed by ISO/IEC DIR 2, provided the symbols are in AsciiMath; sorting MathML and LaTeX entries is not currently supported.

Annexes

All annexes must be preceded by the style attribute [appendix].

Like all clauses, annexes are normative by default, an informative annex is indicated with [appendix,obligation=informative].

The numbering of annexes and appendices is automatic: do not insert "Annex A" or "Appendix 1" as part of the title.

Annex and Appendix titles can be left blank, as with Clauses.

Inline headings

Inline subclause headings (e.g. for test methods) are indicated by preceding the heading with the [%inline-header] option attribute. So in the Rice Model document,

[%inline-header]
==== Sieve,

with round perforations of diameter 1,4 mm.

renders as

A.2.1.1. Sieve, with round perforations of diameter 1,4 mm.

Sections deeper than 5 levels

Asciidoctor permits only five levels of section embedding (not counting the document title). Standards do contain more levels of embedding; ISO/IEC DIR 2 only considers it a problem if there are more than 7 levels of embedding. To realise higher levels of embedding, prefix a 5-level section title with the attribute level=:

====== Clause 5

[level=6]
===== Clause 6

[level=7]
====== Clause 7A

[level=7]
====== Clause 7B

[level=6]
====== Clause 6B

====== Clause 5B

This generates the following ISO XML:

<clause id="_" inline-header="false" obligation="normative">
	<title>
		Clause 5
	</title>
	<clause id="_" inline-header="false" obligation="normative">
		<title>
			Clause 6
		</title>
		<clause id="_" inline-header="false" obligation="normative">
			<title>
				Clause 7A
			</title>
		</clause>
		<clause id="_" inline-header="false" obligation="normative">
			<title>
				Clause 7B
			</title>
		</clause>
	</clause>
	<clause id="_" inline-header="false" obligation="normative">
		<title>
			Clause 6B
		</title>
	</clause>
</clause>
<clause id="_" inline-header="false" obligation="normative">
	<title>
		Clause 5B
	</title>
</clause>

Table of Contents

The table of contents is generated automatically for Word, HTML, and PDF output.

  • In Word, it takes the form of a normal Word Table of Contents; the page numbers are not populated when the document is generated, and the table of contents needs to be refreshed (Right Click: Update Field).

  • In HTML, it takes the form of a side panel. In PDF, it takes the form of an introductory table of contents; because the PDF is generated from HTML in Metanorma, there are no page numbers in the table of contents.

By default, the table of contents includes two levels of heading. More levels of heading can be set by using the document attribute :toclevels:; e.g. :toclevels: 3 for three levels of heading included. The number of levels of heading to include can be set separately for HTML/PDF and for DOC, by using the document attributes :htmltoclevels: and :doctoclevels:.