Metanorma markup for ISO

Lists

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

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 AsciiDoc natively supports the ISO admonitions “Caution”, “Warning”, and “Important” through its admonition syntax.

CAUTION: This is a single-block caution.

[WARNING]
====
This is a

multiple-block warning
====

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

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

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

multiple-block warning
====

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 by Metanorma-ISO.

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 Terms and definitions in general Metanorma documentation.

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

Intelligent terms referencing

Basic usage

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)

Metanorma provides a shortcut syntax that makes this easy and fool-proof.

Defined previously terms can be referenced throughout the document by:

term:[{referenced term}]

or if the displayed term differs from the referenced term:

term:[{displayed term},{referenced term}]

Where,

  • {displayed term} is the term displayed;

  • {referenced term} is the term referenced that exists in the document, which will be used generate the cross-reference.

This example demonstrates usage of this syntax using the previous example:

part of a terminological data collection which contains the term:[terminological data] related to one term:[concept]

In some cases, the displayed term is a variant of the referenced term, such as its plural form.

EXAMPLE (ISO 8601:2019, 3.1.1.5):

===== time scale

system of ordered marks which can be attributed to term:[instants, instant] on the term:[time axis], one instant being chosen as the origin

This has the same effect as the verbose and error-prone form of:

===== time scale

system of ordered marks which can be attributed to _instants_ (<<term-instant>>) on the _time axis_ (<<term-time-axis>>), one instant being chosen as the origin

Automatic term section anchors

The terms reference capability relies on automatically created anchor references for every term defined.

For example, in the following text,

== Terms and definitions
=== Foo

bar

=== Lor

special kind of term:[foo]

the anchors of [[term-foo]] and [[term-lor]] are automatically created.

These anchors are generated from the terms themselves according to these rules:

  • the terms are lowercased;

  • non-ASCII characters are stripped;

  • whitespaces are replaced by -.

This means if you wanted to refer to a particular term from body text, you could either:

  • directly refer to the term: e.g., see definition of term:[foo]

  • refer to the anchor of the term: e.g., the topic is further explained in <<term-foo>>

In case you have created manual anchors that conflict with [[term-{X}]], the term reference mechanism is smart enough to rename the generated anchor as [[term-{X}-{n}]], where n is a number from 1, and so forth.

Therefore this will still work as expected:

== Terms and definitions
=== Foo

bar

=== Lor

special kind of term:[foo]


[[term-foo]]
== My section

lorem

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

Bibliographies

Note
This subsection supplements References & Bibliography in general Metanorma documentation.

All references under Normative References are expected to have such a standard document identifier. For example:

* [[[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 this example would be cited from elsewhere in the document through cross-references to the ricepotentialmilling identifier; e.g. \<< ricepotentialmilling>> (which will be rendered as ISO 6646), <<ricepotentialmilling, section 5>> (which will be rendered as ISO 6646, Section 5), <<ricepotentialmilling,section 5: the foregoing discussion>> (which will be tagged in the XML representation as Section 5 of ISO 6646, but will be displayed as the foregoing discussion.)

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

Tip

If an ISO reference is in preparation, ISO/IEC DIR 2 dictates that details of the reference status be given as a footnote. In Asciidoc, 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 overriden in rendering.

Amendments and technical corrigenda

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

Dates

Amendments and technical corrigenda 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

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