Metanorma: Aequitate Verum

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.

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.

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.

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

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

A foreword is a full Metanorma AsciiDoc section, with the title “Foreword”; this can be overruled in different flavours. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] A foreword may contain subclauses.

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

Metanorma AsciiDoc also supports a simple foreword clause syntax, using the AsciiDoc preamble (any text between the document header and the first section header). This syntax is restrictive (it requires there to be no preceding clauses and no subclauses), and is now deprecated.

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

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 1. Automatic rendering order for prefatory clauses

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 despite the input order:

  • “Executive summary”

  • “Note for draft”

  • “Acknowledgments”

Misc-Container

The misc-container element in Metanorma XML contains miscellaneous data necessary for the processing of the document, that are not themselves part of the document. Examples include the UnitsML definitions of units referenced in the document, or identifiers used as aliases of anchors in the document.

If a preface clause is named Misc-Container (case-insensitive), its contents are appended to the misc-container element for the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7]. This can be used to add data into a document that is not to be rendered, but which is still needed for processing.

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.

Term Annexes, Symbols Annexes, Bibliography Annexes

Normally in Metanorma, the sections describing terms and definitions, symbols and abbreviated terms, and bibliographic references are contained in a main clause.

However, it is possible for such clauses to be contained in annexes instead. In fact, this is done by default for the "Terms and References" section in the NIST flavour of Metanorma.

In rendering, these annexes are treated identically as when those sections were in the main body.

However, the Metanorma information model does not permit a clause to be an annex and a terms or a bibliographic clause at the same time.

Such clauses are modelled as an annex containing a terms clause or bibliographic clause:

[annex]
== Bibliography

[bibliography]
=== Bibliography

In order to render such annexes as expected, the following rules are applied [added in https://github.com/metanorma/isodoc/releases/tag/v2.0.9]:

  • If an annex contains multiple subclauses, it is rendered as usual.

  • If an annex contains a single subclause, and that subclause is a Terms & Definitions, Symbols & Abbreviated Terms, or Bibliographic section,

    • The title for that subclause is skipped in rendering

    • The subclause itself is skipped for the purposes of numbering; if it has any sub-subclauses of its own, they are numbered as immediate child clauses of the annex.

So:

[annex]
== Terminology

=== Terms and definitions

==== First Term

==== Second Term

is rendered like

Annex A. Terminology

A.1 First Term

A.2 Second Term

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