Metanorma for ISO markup

Document layouts

General

Metanorma ISO supports multiple layouts of ISO documents through the :document-scheme: document attribute [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.1].

If the :document-scheme: is not provided, the scheme to apply is inferred solely based on the :copyright-year: document attribute.

If neither of those attributes is present, the current default is applied.

Note	The current default is `2024`.

Note	Metanorma does not consider the month in selecting the actual document scheme because historically the transitions made from one scheme to another were according to a specific cut-off date [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.6].

Specific instructions on using these layouts are described below.

2024 (latest and default)

The following attributes should be set:

:semantic-metadata-feedback-link: which is used to generate cover page QR code.
:library-ics: to set the ICS code(s).

2013

The following attributes should be set:

:library-ics: to set the ICS code(s).

2012

The 2012 PDF layout, published in mid-2012, is equal to the 1989 layout with an ISO logo update.

The following attributes should be set:

:library-ics: to set the ICS code(s).

1989

The following attributes should be set.

From publication year 1994 and onwards:

:library-ics: to set the ICS code(s).

Prior to publication year 1994:

:classification: to set the UDC code(s).

1987

The following attributes should be set:

:classification: to set the UDC code(s).

1979

The following attributes should be set:

:classification: to set the UDC code(s).

1972

The following attributes should be set:

:classification: to set the UDC code(s).

1951

The first available published ISO format.

The following attributes should be set:

:classification: to set the UDC code(s).

Lists

Unordered lists

Unordered lists in Word are rendered with em-dashes instead of bullets, as preferred by ISO/CS.

Ordered lists

Ordered list numbering enforces the ISO/IEC DIR 2 labelling convention as default: "a)", "1)", "i)", "A)", "I)".

However, the style attribute is respected in ordered lists if provided [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.5]:

[arabic]
. A
. B
[lowerroman]
.. C
.. D

The start attribute is supported in ISO by Metanorma, but not by IEC or BSI [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.1.2].

The start attribute behaves as described below:

PDF and HTML respect the start attribute at all stages;
For Word output:
- The start attribute will be ignored for stages between 00 and 30, because Word output for those stages uses the “ISO Simple Template”, which involves autonumbering of lists. Metanorma does not yet support start in Word for autonumbered lists.
- The start attribute will work from stages 40 onward, as Work output for those stages uses the “ISO Edited DIS Template”, which insert explicit numbers in lists, and do not rely on Word autonumbering.

Admonitions

Admonitions can be applied to:

Document elements, by adding the block anywhere in the document;
To the document as a whole, by adding the block to before the first numbered clause.

Metanorma natively supports the ISO admonitions “Caution”, “Warning”, and “Important” through the admonition syntax using the corresponding type names.

Note	These message types are referenced in ISO/IEC DIR 2 from ISO/IEC Guide 51 and ISO 78-2.

A “Caution” message can be specified using CAUTION: or [CAUTION].
Example 1. Example of specifying Caution messages
CAUTION: This is a single-block caution. [CAUTION] ==== This is a caution in multiple blocks. ====
A “Warning” message can be specified using WARNING: or [WARNING].
Example 2. Example of specifying Warning messages
WARNING: This is a warning. [WARNING] ==== This is a warning too, in multiple blocks. ====

If the admonitions “Danger” and “Safety Precaution” are needed, they should be indicated through a type attribute, which will override the admonition type appearing.

Example 3. Example of specifying Danger and Safety Precaution messages

[type=Danger]
CAUTION: This is a single-block danger.

[WARNING,type=Safety Precaution]
====
This is a safety precaution

spanning multiple-blocks.
====

Statement concerning units

Please refer to instructions at:

Editorial notes

Editorial notes can be added to an ISO document, to differentiate feedback from ISO editors to the readers of a circulated draft, from feedback to the authors or editors of a draft [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.1.2].

The editorial note in ISO documents is meant to represent the zzHelp style as known to ISO editors, meant to represent notes to the editors.

Editorial notes are encoded as the EDITOR admonition, which can be used in a single-line encoding or in a block syntax.

EDITOR: {text}

Where:

{text} is the contents of the editorial note.

Example 4. Example of specifying editorial notes

EDITOR: This is an editorial note.

[EDITOR]
====
So is this.
====

[EDITOR]
And this as well.

Renders into:

Figure 1. Example rendering of editorial notes

Note	`[EDITOR]` is an alias for the admonition `[IMPORTANT,type=editorial]`. Hence, the following markup is also valid: `[IMPORTANT,type=editorial] This is an editorial note, too.`

Cross-references

Custom cross-references should not be used in ISO standards, either for an external reference, or for a section of the current document: ISO/IEC DIR 2 requires any cross-references to be transparent in text.

For example, a cross-reference to the anchor such as:

[[tabular]]

on Clause 5 should be given as just:

<<tabular>>

…and custom text will be automatically rendered as Clause 5.

ISO clause references will suppress the word "Clause" before a subclause reference, following ISO/IEC DIR 2: <<ISO24333,clause=5>> will be rendered as ISO 24333, Clause 5, but <<ISO7301,clause=3.1>> will be rendered as ISO 7301, 3.1.

Terms and definitions

Note	This subsection supplements Concepts, designations, terms and definitions in general Metanorma documentation.

Terminological entry numbering

General

Terminology presented in ISO documents adhere to ISO 10241-1. ISO 10241-1, 6.1 details the organization of numbering terminological entries, which could be one of:

systematic order (also called “nested terms”); or
mixed order (also called “grouped terms”).

Systematic order

General

In systematic order, the entry numbers are "serial numbers reflecting the position of the respective concept within a concept system".

Example 5. Example of clause structure with systematic order (ISO 10241-1)

3.1 Terminological entry at first level of concept system.
3.2 Terminological entry at first level of concept system.
3.2.1 Terminological entry at second level of concept system.
3.2.2 Terminological entry at second level of concept system.
3.2.2.1 Terminological entry at third level of concept system.
3.3 Terminological entry at first level of concept system.

In this arrangement, terms are nested within other terms in numbering.

Encoding terms in systematic order

== Terms and definitions

=== Term 1
Definition 1

==== Term 1.1
Definition 1.1, a sub-concept of Term 1

==== Term 1.2
Definition 1.2, a sub-concept of Term 1

=== Term 2
Definition 2

==== Term 2.1
Definition 2.1, a sub-concept of Term 2

Encoding parent terms without definitions

If a parent term clause (a term clause that contains terms below) is not given a definition, the [.term] attribute needs to be applied to indicate that the parent term is a "term" instead of a "mixed-order grouping".

Encoding terms in systematic order when a parent term definition is missing

== Terms and definitions

[.term]
=== Term 1 (missing definition)

==== Term 1.1
Definition 1.1, a sub-concept of Term 1

==== Term 1.2
Definition 1.2, a sub-concept of Term 1

[.term]
=== Parent Term 2

==== Term 2.1
Definition 3, a sub-concept of Term 2

Mixed order

General

In mixed order,

entry numbers of divisions are "serial numbers reflecting the structure of the concept system"
entry numbers of terminological entries within the divisions are "serial numbers reflecting the order of preference"

Example 6. Example of clause structure with mixed order (ISO 10241-1)

3.1 Division at first level of concept system.
3.2 Division at first level of concept system.
3.2.1 Terminological entry in the order of preference.
3.2.2 Terminological entry in the order of preference.
3.2 Division at first level of concept system.
3.2.1 Division at second level of concept system.
3.2.1.1 Terminological entry in the order of preference.

This arrangement counts terminal subclauses within a “Terms and definitions” clause as terms, and all other intermediate clauses as term groupings.

Example 7. Encoding terms in mixed order with groupings

== Terms and definitions

=== Term grouping 1 (subclause 1)

==== Term A
Definition A

==== Term B
Definition B

=== Term grouping 2 (subclause 2)

==== Term C
Definition C

Note	If there is any text in a term grouping, Metanorma is going to assume that the grouping was intended as a systematic term.

Declared term groupings

The role [.grouping] explicitly declares a clause as a term grouping, and not a term. [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.3.4]. It is used to enforce mixed order divisions of terms.

Encoding terms in mixed order with declared groupings

== Terms and definitions

[.grouping]
=== Term grouping 1
Paragraph 1

==== Term A
Definition A

==== Term B
Definition B

[.grouping]
=== Term grouping 2
Paragraph 2

==== Term C
Definition C

Combined terms and definitions

The title of a top-level “Terms and definitions” clause is populated automatically, overriding the title provided by the user.

If it contains a “Symbols” and “Abbreviated terms” subclause, it is titled "`Terms, definitions, symbols and abbreviated terms`", otherwise it is titled "`Terms and definitions`".

The “Symbols” and “Abbreviated terms” subclauses are also titled; other subclauses of “Terms and definitions” clauses are not.

In summary, allowed titles for the top-level “Terms and definitions” clause (Clause 3) include:

“Terms and definitions”
“Terms, definitions and symbols”
“Terms, definitions and abbreviated terms”
“Terms, definitions, symbols and abbreviated terms”

Concept mentions

Metanorma supports intelligent terms referencing in term definitions.

In ISO deliverables, if a term definition contains a term that is defined in the current document, this term needs to be put in italics with a cross-reference for that term supplied between parenthesis immediately after.

EXAMPLE (ISO/IEC Directives Part 2 (2020), 16.5.10):

part of a terminological data collection which contains the terminological data (3.1.3) related to one concept (3.2.1)

This is done in Metanorma by using citation of terms, on which see Referencing concepts [added in https://github.com/metanorma/metanorma-iso/releases/tag/v1.8.6].

So the foregoing instance would be automatically generated through:

part of a terminological data collection which contains the
{{terminological data}} related to one {{concept}}

assuming the terms are defined as the text “terminological data” and “concept”, or

part of a terminological data collection which contains the
{{terminology data,terminological data}}
related to one {{conceptual notion,concept}}

if say the terms are defined with different wording.

Metanorma imposes the default rendering of term citations following the ISO house style: [added in https://github.com/metanorma/metanorma-iso/releases/tag/v1.8.7]

The first mention of a term in the “Terms and definitions” clause is italicised with a following bracketed cross-reference.

"concept (3.2.1)"
Subsequent mentions of that term in the “Terms and definitions” clause are in plaintext, with no following bracketed cross-reference.

"concept"
Other mentions of the term in the document are in also plaintext, with no following bracketed cross-reference.

"concept"

Vocabulary documents

General

The “vocabulary” document type is defined in the ISO house style and title requirements defined in the ISO/IEC Directives, Part 2, 2018, 11.5.2.

A vocabulary document differs from a normal ISO deliverable because it allows certain exceptions, but also restricts the type of content allowed in the deliverable.

According to the ISO House Style:

A vocabulary is the source document for the terms and definitions of a committee or subject. It is not a collection of terms used in the documents of a committee. Therefore, it does not:

state that it is a collection of terms;

list the documents that use its terminological entries;

include documents from its committee as "SOURCE".

It can include documents from another committee as "SOURCE".

A vocabulary is the only ISO document that can have terminological entries in clauses other than Clause 3. If terminological entries are given in other clauses, use a clause title starting “Terms related to”. Terminological entries are never included in annexes.

Setting a vocabulary document

A vocabulary document is specified by setting the document header of :docsubtype: to the value vocabulary.

Example 8. Example of setting ISO 8000-2 as a vocabulary document

= ISO 8000-2
:docsubtype: vocabulary

Using terminological entries outside Clause 3

Terminological entries are permitted outside of Clause 3 in vocabulary documents [added in https://github.com/metanorma/metanorma-iso/releases/tag/v1.8.3].

Such clauses need to be indicated with the heading attribute set to terms and definitions.

Example 9. Using first level clauses for terminology entries in vocabulary documents

:docsubtype: vocabulary
...

[heading=terms and definitions]
== Terms related to comedy theatre
...

[heading=terms and definitions]
== Terms related to fantasy theatre
...

Handling Symbols and Abbreviated terms

Content for “Symbols” and “Abbreviated terms” are not allowed in the main content body of vocabulary documents.

Note	Information in this clause was provided directly by the ISO/CS Editing team. It is not explicitly documented in the ISO House Style reference.

There are only two ways of handling symbols and abbreviated terms in a vocabulary document:

Included in term entries as preferred or admitted terms. This is the preferred manner by ISO/CS.
Listed in an annex named “Symbols and abbreviated terms”. This is an accepted practice by ISO/CS.

Example 10. Providing symbols and abbreviated terms as an annex in a vocabulary document

:docsubtype: vocabulary
...

== Terms related to requirements
=== abstract test suite
alt:[ATS]

collection of abstract conformance tests of which passing indicates compliance
to the associated conformance class

Example 11. Providing symbols and abbreviated terms as an annex in a vocabulary document

:docsubtype: vocabulary
...

[appendix]
== Symbols and abbreviated terms
ATS:: abstract test suite

Sections

In the document scheme used by ISO between 1987 and 1989, clauses were organised into higher-level numbered sections.

In order to realise this formatting, use type=section [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.5], and heading= to indicate the special clause types for subclauses of sections:

[type=section]
== General

[heading=scope]
=== Scope

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

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

Annexes and appendices

In ISO, Appendixes to annexes can occur, although they are not mentioned in ISO/IEC DIR 2; ISO/IEC DIR 1 features them. They are marked up as immediate subsections of annexes, and must be tagged with an option attribute of appendix:

[appendix]
== Annex A
Text

[%appendix]
=== Appendix 1
Text

Cross-references to annexes and their subclauses are formatted as follows by default, following the practice alluded to (but not spelled out) in ISO/IEC DIR 2:

Annex A
Clause A.1 [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.5]
A.1.1

Bibliographies

Note	This subsection supplements References and bibliography in general Metanorma documentation.

All references under "Normative references" are expected to have a standard document identifier.

Example 12. Using standard document identifiers in a bibliography section

* [[[ricepotentialmilling,ISO 6646]]], _Rice -- Determination of the potential milling yield from paddy and from husked rice_
* [[[ISOGuide73, ISO Guide 73:2009]]], _Risk management -- Vocabulary_

ISO 6646 in the above example would be cited from elsewhere in the document through cross-references to the ricepotentialmilling identifier.

For example,

<<ricepotentialmilling>>: will be rendered as ISO 6646
<<ricepotentialmilling,section 5>>: will be rendered as ISO 6646, Section 5
<<ricepotentialmilling,section 5: the foregoing discussion>>: will be tagged in the XML representation as Section 5 of ISO 6646, but will be displayed as the foregoing discussion.

Metanorma treats dated and undated references as separate: an undated reference is taken to refer to the latest published edition of that reference.

If reference is to be made to both an undated and a dated version of an ISO reference, these need to be explicitly listed as separate references.

If an ISO reference is in preparation, ISO/IEC DIR 2 dictates that details of the reference status be given as a footnote. In Metanorma, this is done by giving the date as a double dash, and following the bibliographic anchor with a footnote macro:

* [[[ISO16634,ISO 16634:--]]] footnote:[Under preparation. (Stage at the time of publication ISO/DIS 16634)], _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_

If an ISO reference includes all parts of the standard, that is indicated by appending (all parts) after the reference anchor:

* [[[ISO16634,ISO 16634 (all parts)]]] _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_

In informative references, references to standards documents are still given with the same format of bibliographic anchor, and they are cited by their document identifier — although they are displayed with an incrementing reference number in brackets, for consistency with any bibliographic entries that are not standards documents. ISO references appear before non-ISO references. So

[bibliography]
== Bibliography

* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_
...
* [[[ref11,11]]] Nitrogen-ammonia-protein modified Kjeldahl method -- Titanium oxide and copper sulfate catalyst. _Official Methods and Recommended Practices of the AOCS_ (ed. Firestone, D.E.), AOCS Official Method Ba Ai 4-91, 1997, AOCS Press, Champaign, IL

is displayed as:

Bibliography

[1] ISO 3696, Water for analytical laboratory use — Specification and test methods … [11] Nitrogen-ammonia-protein modified Kjeldahl method — Titanium oxide and copper sulfate catalyst. Official Methods and Recommended Practices of the AOCS (ed. Firestone, D.E.), AOCS Official Method Ba Ai 4-91, 1997, AOCS Press, Champaign, IL

The entries in the Bibliography are reordered (and, for numerical references, renumbered) according to the following criteria:

Document class (as defined in the ISO sample Rice document): standard which ISO has published or co-published; standard which IEC has published or co-published; other standards; other documents.
- Standards are identified by the use of a code for the document identifier, as opposed to a number.
Document identifier type (as a proxy for the standards setting body)
Document number (the numeric portion of the standards identifier, sorted numerically)
Full document identifier
Document title

The bracketed reference numbers are expected to be correct and in order (accounting for the fact that references to standards will end up numbered): they are not overridden in rendering.

Amendments, addenda, and technical corrigenda

General

Amendments and technical corrigenda [added in https://github.com/metanorma/isodoc/releases/tag/v1.3.25] and addenda [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.8.8] have the following particularities in their markup.

Dates

Amendments, technical corrigenda and addenda bear two dates in their identifiers: the date of the source document, and the date of the update. The latter date is given as the :copyright-year: attribute (and may be given in more detail as the :updated-date: attribute. The former date is given as the :created-date: attribute; if it is missing, the :copyright-year: is used instead.

The :edition: attribute applies to the source document, not to the amendment.

The :updates: attribute must be used, to give the identifier of the source document, including the date. If this is a corrigendum to an addendum, the source identifier must be that of the Addendum.

Clauses

In amendments and technical corrigenda (but not addenda), there are no special clauses: clauses describe the location at which changes are applied. So == Terms and definitions does not introduce a Terms section: it describes the changes to be applied to the Terms section of the existing document. For the same reason, there are no annexes or distinct bibliographies.

Clauses are only expected to be one level deep.

The clauses in amendments and technical corrigenda are instances of the change clauses described in Machine-readable changes.

[change=delete,locality="clause=introduction,paragraph=4-7"]
== Introduction

Form

The document in amendments and technical corrigenda takes the form of clauses describing what is to be amended; the amendments themselves are quoted.

Because the quoted material are snippets with little context, auto-numbering will not yield sensible results, and neither will cross-referencing autonumbered blocks or clauses. For that reason, amendments and technical corrigenda must not use cross-referencing, and any auto-numbering is suppressed. Users will have to include explicit numbering in any snippets of text (as they already do), and mock up clause titles by using boldface (since clause titles will be quoted, and thus not recognised as such).

Numeral formats

In ISO and IEC, by default, the decimal marker used is the comma, as described

The decimal sign shall be a comma on the line in all language versions.

— ISO/IEC Directives Part 2 9.1

And digits are also to be grouped into threes:

Each group of three digits shall be separated by a small space from the preceding digits, counting from the decimal sign. This also applies to digits following the decimal sign.

Example 13. Rendering numbers using number encoding in an ISO or IEC document

The encoding of number‌:60007.12345[] in an ISO or IEC document in any language is displayed as 60 007,123 45.

Example 14. Rendering numbers using number encoding in an ISO or IEC document without treatment on the hanging digit

The encoding of number‌:2345.6789[] in an ISO or IEC document in any language is displayed as 2 345,678 9.

Document layouts

General

2024 (latest and default)

2013

2012

1989

1987

1979

1972

1951

Lists

Unordered lists

Ordered lists

Admonitions

Statement concerning units

Editorial notes

Cross-references

Terms and definitions

Terminological entry numbering

General

Systematic order

General

Encoding parent terms without definitions

Mixed order

General

Declared term groupings

Combined terms and definitions

Concept mentions

Vocabulary documents

General

Setting a vocabulary document

Using terminological entries outside Clause 3

Handling Symbols and Abbreviated terms

Sections

Annexes and appendices

Bibliographies

Amendments, addenda, and technical corrigenda

General

Dates

Related documents

Clauses

Form

Numeral formats