Document sections

General

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 types

Automatic type recognition

Metanorma automatically detects these standard section types when their titles match common patterns in any supported language:

• Abstract

• Foreword

• Introduction

• Acknowledgements

• Executive summary

• Scope

• Normative references

• Terms and definitions

• Symbols and abbreviated terms (or individual Symbols/Abbreviated terms sections)

• Bibliography

• Misc-Container (special container section)

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.

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.

Manual type specification

If the section title does not match standardized title patterns, the section type must be explicitly declared using attributes.

Note	Clause titles can differ from standardized titles for custom phrasing or language differences.

[type_attribute]
== Your Custom Title

Supported section type declarations include the following.

Section type	Standardized title	Declaration
Abstract	"Abstract"	[abstract]
Foreword	"Foreword"	[heading=foreword]
Preface	No standardized title	[preface]
Introduction	"Introduction"	[heading=introduction]
Acknowledgments	"Acknowledgements"	[acknowledgments]
Executive summary [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.7]	"Executive summary"	[executivesummary]
Scope	"Scope"	[heading=scope]
Bibliography	"Bibliography" or "Normative references"	[bibliography]
Terms and definitions	"Terms and definitions"	[heading=terms and definitions]
Symbols and abbreviated terms	"Symbols", "Abbreviated terms", "Symbols and abbreviated terms"	[heading=symbols and abbreviated terms]
Index	"Index"	[index]
Appendix	No standardized title	[appendix]

There are some restrictions on the number of sections of certain types that can be included in a document.

For all documents:

• only one "Abstract" section is allowed

• only one "Acknowledgements" section is allowed

• only one "Executive summary" section is allowed

• only one "Index" section is allowed

In most flavours and document types:

• only one "Terms and definitions" section is allowed

For sections that are limited to one instance, if a second matching clause is found, it is treated as a normal clause.

This behavior can be overridden by specifying the section type in a heading attribute: this is interpreted as the user explicitly wanting that section type to apply [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.10.0].

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.

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 internationalization; 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