Metanorma: Aequitate Verum

Author's documentation

Document sections

General

tag::tutorial[]

Sections define hierarchy levels in a document, as chapters do. In AsciiDoc, sections are encoded with titles prefixed by equal signs (=).

  • The document title is considered the highest section in the hierarchy, and is created by prepending a = sign in front of the heading.

  • Subsequent sections are encoded with titles prefixed with least two equal signs:

    • == indicates a first-level section;

    • === indicates a second-level section;

    • ==== indicates a third-level subsection;

    • and so on.

Example 1. Example of setting document and section titles
= Document title

== Section 1

=== Section 1.1

==== Section 1.1.1

===== Section 1.1.1.1

== Section 2

=== Section 2.1

...

Section titles

Pre-defined section titles

Sections in a document are composed and placed in their appropriate places inside the Metanorma document model.

Metanorma utilizes the following pre-defined section titles to identify specific kinds of sections in the document:

The content body, or annexes, are entered as normal sections without need for pre-defined titles.

Fixed section names are specific to either the preface of a document, or the main body; so for example an instance of "Introduction" the main body of the text will not be treated as part of the preface.

Note
 The underlying document model behind all Metanorma flavors is called the StandardDocument model, also abbreviated as "StanDoc". The available section types available in StanDoc are reproduced in this section. StanDoc represents the harmonized common requirements of standardization documents, not the document model of a particular SDO.
UML representation of section classes in Metanorma StanDoc
Figure 1. UML representation of section classes in Metanorma StanDoc

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.

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

Entering titles that deviate from the pre-defined titles, or in languages other than English requires explicit declaration of those section types.

The section type is declared between square brackets [ …​ ] immediately above the section title.

For these types of sections, enter them without

  • Abstract: [abstract]

  • Foreword: [heading=foreword]

  • Preface sections: [preface]

  • Introduction: [heading=introduction]

  • Acknowledgements: [acknowledgments]

  • Scope: [heading=scope]

  • Bibliography, Normative references: [bibliography]

  • Terms and definitions: [heading=terms and definitions]

  • Symbols and abbreviated terms: [heading=symbols and abbreviated terms]

  • Index: [index]

  • Annexes: [appendix]

Note
 Documents can contain only one Abstract, one Acknowledgements section, and one Index.

The following example indicates usage of the section titles.

= 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)
== Additional content
...

  1. This section is meant to be the introduction but the title deviates from the pre-defined title. The [preface] declares it as such.

  2. "Normative references" is encoded with the [bibliography] declaration.

  3. The "heading" declaration assigns the section as a particular kind.

  4. "Additional content" is an annex and needs to be declared explicitly. Normative status of the annex is defined by adding the obligation option.

end::tutorial[]

Note

The above section titles as detected by Metanorma are case-insensitive. While ISO Directives Part 2 demands clause titles to be in sentence case, some organizations utilize title case.
Note

A dedicated topic expands on “Terms and definitions” section grammar.

Automated title recognition (by English titles such as Scope, Normative references, etc.) applies only at the topmost level of clause. If a clause is to be recognised with a special type and nested at a deeper clause level, the heading attribute still needs to be used [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.6]; otherwise, the clauses will be treated as normal clauses, without the special semantics or formatting of those clause types. For example,

== General

[heading=scope]
=== Scope

[bibliography,heading=normative references]
=== Normative references

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

In most flavours of Metanorma, if the title is indicated or guessed correctly, it is overwritten by the standard title required by the SDO and internationalisation; for example, in ISO,

[heading=foreword]
== Fore Word

will still be rendered as

Foreword

in English, and

Avant-propos

in French; the supplied text is ignored.

Moreover, the title of a Terms and definitions clause will be determined automatically, based on its contents; a Terms and definitions clause which contains a symbols clause but not an abbreviated terms clause will automatically be titled Terms, definitions and symbols in English (Termes, définitions et symboles in French.

In order to force the provided title to be retained in the clause, despite the SDO requirements for the flavour of Metanorma, use the attribute keeptitle=true [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.6]. For example,

[heading=foreword,keeptitle=true]
== Fore Word

will be encoded and rendered as a foreword, but it will retain its title as Fore Word.

Blank subclause headings

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. metanorma-un. The UN Metanorma flavor treats each paragraph as a distinct clause and automatically numbers it.

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.

Variant titles

Variant titles [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.5] are entered as paragraphs with a variant-title role attribute within a clause, as follows:

=== Proper title

[.variant-title,type=sub]
This is the variant title

Text of section.

Variant titles of type sub are rendered as subtitles of clauses.

Floating titles

Warning
 Intended for legacy support only. Use with care.

A “floating title” is a title that is placed outside the numbered hierarchy of clauses. This means that a floating title is not uniquely referable like normal clauses.

Since the hierarchical structure of standards documents is critical to their proper referencing, floating titles are commonly disallowed by standards documents. Nonetheless, for legacy support reasons, floating titles are supported in Metanoma [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.4]:

=== Section 2.1

[discrete]
==== I am a floating title within section 2.1

==== Section 2.1.1
Note
 Floating titles are sometimes referred in AsciiDoc as “discrete titles”.

Sections deeper than 5 levels

Standards can contain many 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=:

Note
 Asciidoctor AsciiDoc permits only five levels of section embedding (not counting the document title). 
// Six equal signs for five levels
====== Clause 5A

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

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

and the rendering would be something like

1.1.1.1.1 Clause 5A

1.1.1.1.1.1 Clause 6A

1.1.1.1.1.1.1 Clause 7A

1.1.1.1.1.1.2 Clause 7B

1.1.1.1.1.2 Clause 6B

1.1.1.1.2 Clause 5B