Sections are marked off in Asciidoc with titles prefixed by double equal signs,
Fixed section names
Metanorma relies on certain pre-defined section titles to identify the different kinds of sections in the document, namely these:
Terms and Definitions
Symbols and Abbreviations
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
that provides the English canonical form of the section name. For example:
== Normative References [heading=terms and definitions] == Terms, definitions and abbreviations
The obligation of a section—whether it is normative or informative—is indicated via 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
The Foreword of a standard is detected as any text between the document header and the first section header.
In the example below, AsciiISO Rice document specifies the
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 entries is not currently supported.
All annexes must be preceded by the style attribute
Like all clauses, annexes are normative by default,
an informative annex is indicated with
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 subclause headings (e.g. for test methods) are indicated by preceding the heading
[%inline-header] option attribute. So in the Rice Model document,
[%inline-header] ==== Sieve, with round perforations of diameter 1,4 mm.
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
====== 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: 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