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:
-
Misc-Container
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7] -
Abstract
-
Foreword
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] -
Introduction
-
Acknowledgements
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] -
Scope
-
Normative references
-
Terms and definitions
-
Symbols and abbreviated terms
-
Symbols
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.0] -
Abbreviated terms
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.0] -
Bibliography
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 Metanorma will supply the “Foreword” title if no such title is given.
|
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. |
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”
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:
.