Author’s documentation

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.

Clause headings

Fixed section names

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

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

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.

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

Clause attributes

Language & script

The language and script of a section is indicated via the optional attributes language and script:

[language=fr]
== Section 3

[appendix,script=Zmth]
== Math Appendix

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

Numbering

As with block element numbering, a clause number may be provided to override auto-numbering.

For instance, in order to number out-of-sequence clauses in updated documents or amendments [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.3].

A manual clause number is specified with the attribute number:

== Clause 7

[number=0]
=== Zeroth Subclause

Elements subsequent to the manually numbered element will be auto-numbered so as to follow the previous element. This may include incrementing the final letter in an alphanumeric clause number (e.g. 7a followed by 7b.)

If resumption of auto-numbering is not intended for subsequent clauses (e.g. 7bis should not be followed by 7bit), an explicit number also needs to be given to those clauses separately.

Prefatory clauses

Foreword

General

The “Foreword” can be specified in two ways, depending on whether it is a “simple clause”, or a “full clause”.

Simple foreword clause

If the “Foreword” does not contain subclauses, it is considered a simple foreword clause.

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 AsciiDoc section headers.)

Metanorma will supply the “Foreword” title if no such title is given.

[[foreword]]
.Foreword

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

If the “Foreword” contains subclauses, it needs to be encoded as a full foreword clause.

A full foreword clause is recognized as a full Metanorma AsciiDoc section, with the title “Foreword”; this can be overruled in different flavours. Simple foreword content can also be encoded this way. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19]

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

=== Foreword subclause

More foreword...

Arbitrary prefatory clauses

Arbitrary prefatory clauses are allowed in some flavors, and are disallowed but “accepted” for encoding in certain flavors for backwards compatibility reasons.

Note
 Most flavors specify requirements on preface sections. Most flavors specify mandatory and optional preface sections, while some completely disallow arbitrary preface sections.
In ISO only the “Foreword” is allowed — arbitrarily named preface sections are prohibited, in accordance with ISO Directives Part 2.

Any section detected as the “Foreword”, or labelled as “Introduction”, “Acknowledgements” [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19], or “Abstract”, will be inserted into the document preface.

Any other first-level clauses tagged with the role attribute [.preface] are also moved into the document preface [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19].

If these prefatory sections are provided, they will be displayed in the following default ordering:

  • “Abstract”

  • “Foreword”

  • “Introduction”

  • Preface clauses. Any prefatory clauses that don’t fit the other specially “named” sections will be placed here.

  • “Acknowledgments”

EXAMPLE:

This source:

// tagged as the "`abstract`"
[.preface,heading=abstract]
== Executive summary

Widget manufacture has proven profitable until recent times, when increased
competition has forced a reevaluation...

// tagged as the "`acknowledgements`"
[.preface,heading=acknowledgements]
== Organizational contributors

The following organizations have contributed valuable resources and expertise
for the completion of this standard...

// tagged as normal
[.preface]
== Note for draft

This is not an international standard, please be aware of the responsibilities
that come with application of this document...

Will be rendered in this order:

  • “Executive summary”

  • “Note for draft”

  • “Acknowledgments”

Symbols and Abbreviations

Symbols and Abbreviations sections are expected to be simple definition lists (“labelled lists” in AsciiDoc 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], or ([added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.27]) the role attribute [.appendix]. The latter can be used to combine the appendix. with another style attribute, such as [bibliography], though this is not recommended practice.

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.

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

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