AsciiISO markup

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.

Bibliographies

For references to standards with a document identifier, the entry must be preceded by a bibliographic anchor, in triple brackets: this consists of an arbitrary internal identifier (used in citations), followed by the canonical document identifier for the reference as its label.

All references under Normative References are expected to have such an 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 crossreferences 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. (This convention is taken from ISO.) 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 bracketed reference numbers are expected to be correct and in order: they are not overriden in rendering.

Automatic reference fetching

Relaton can fetch bibliographic entries for any standards known to have online bibliographic databases (ISO, IEC, IETF, GB).

Any bibliographic entry recognized through its document identifier prefix will by default have its bibliographic entry fetched by that gem. The fetched data overrides any content about the item provided in the document, since the online bibliography is treated as the source of truth for that standards document.

Annexes & 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

Additional warning types

Asciidoctor 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
====