Metanorma-ISO: Metanorma processor for ISO standards
Functionality and Approach
For the conceptual underpinnings of this gem, and the other gems in the Metanorma suite, see the metanorma-standoc README.
This gem processes Metanorma documents following a template for generating ISO International Standards. The following outputs are generated.
The XML representation of the document, intended as a document model for ISO International Standards.
Microsoft Word output (
.doc), following the style conventions of the ISO Standard Microsoft Word template.
HTML. For ISO, two HTML files are generated: the
.htmlfile follows ISO conventions in rendering, which looks very similar to the Word output, while the
-alt.htmlfile has richer styling.
PDF. Not supported for the ISO gem, but available for other specifications, generated from the HTML file.
The following input formats are supported:
Asciidoctor (This AsciiDoc syntax for writing ISO standards is hereby named "AsciiISO".)
The preferred way to invoke this gem is via the
$ metanorma --type iso a.adoc # output HTML and DOC $ metanorma --type csd --extensions html a.adoc # output just HTML $ metanorma --type csd --extensions doc a.adoc # output just DOC $ metanorma --type csd --extensions xml a.adoc # output CSD XML
The gem translates the document into ISO XML format, and then validates its output against the ISO XML document model; errors are reported to console against the XML, and are intended for users to check that they have provided all necessary components of the document.
The gem then converts the XML into HTML and DOC.
If you are using a Mac, the https://github.com/riboseinc/metanorma-macos-setup repository has instructions on setting up your machine to run Metanorma scripts such as this one. You need only run the following in a Terminal console:
$ bash <(curl -s https://raw.githubusercontent.com/riboseinc/metanorma-macos-setup/master/metanorma-setup) $ gem install metanorma-iso $ gem install metanorma-cli
The metanorma-cli gem is the command-line interface for the Metanorma tool suite
metanorma executable seen above).
The gem also realises several format checks as prescribed in ISO/IEC DIR 2:2018, and warns the user about them in the console:
Numbers with what looks like dots instead of commas for decimal points.
Groups of numbers without spacing for every three digits. (The gem attempts to ignore ISO references.)
No space before percent sign.
No bracketing of tolerance in percentage (e.g.
15 ± 7 % .)
No recommendations, permissions or requirements (detected by keyword) in: foreword, scope, introduction, term examples and examples, notes, footnotes.
No subclauses that are the only child of a clause. (In clauses, annexes, or scopes.)
5 levels of subclause nesting. (Never actuated, AsciiDoc only permits 4 levels of subsections.)
Non-ISO/IEC reference turning up as normative.
Term definition starts with an article, or ends with a period.
Title intro or title part appears in only one of French or English.
In addition, the gem checks all terms cited from the IEV Electropedia against the online IEV Electropedia entry, and issues a warning if the term is different.
The document model for ISO Standards contains all the structures described in ISO/IEC DIR 2 "Principles and rules for the structure and drafting of ISO and IEC documents". It is expressed as a Relax NG Compact schema; actual validation occurs against its full Relax NG counterpart.
Asciidoctor model additions
Refer also to https://github.com/riboseinc/metanorma-standoc/blob/master/README.adoc; this section lists additions specific only to metanorma-iso
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
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 ====
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.
For automated bibliography integration, see the metanorma-standoc README.
The gem uses the document attributes defined for metanorma-standoc (see the metanorma-standoc README).
The following document attributes are specific to ISO:
The document number assigned by the Technical committee
The ISO document part number. (This can be "part-subpart" if this is an IEC document.)
The introductory component of the English title of the document. This and the other
:title-*document attributes are used instead of the metanorma-standoc
:title:attribute and the default Asciidoctor title (the first line of the document header, prefixed with
The main component of the English title of the document (mandatory).
The English title of the document part
The introductory component of the French title of the document. (This document template presupposes authoring in English; a different template will be needed for French, including French titles of document components such as annexes.)
The main component of the French title of the document (mandatory).
The French title of the document part
Has its possible values defined by ISO deliverables: The different types of ISO publications (mandatory). The permitted types are:
international-standard, technical-specification, technical-report, publicly-available-specification, international-workshop-agreement, guide.
The stage code for the document status (see International harmonized stage codes). This attribute and
:status:attribute of metanorma-standoc.
The substage code for the document status (see International harmonized stage codes)
The iteration of a stage, in case there have been multiple drafts (e.g.
CD: this is the second iteration through the
The national body acting as the secretariat for the document in the deafting stage
The number of the relevant ISO technical committee (also
:technical-committee-number_3:…; the same applies for all technical-committee, subcommittee and workgroup attributes)
The type of the relevant technical committee. Defaults to
TCif not supplied. Values:
The name of the relevant ISO technical committee (mandatory)
The number of the relevant ISO subcommittee
The type of the relevant ISO subcommittee. Defaults to
SCif not supplied. Values:
The name of the relevant ISO subcommittee
The number of the relevant ISO workgroup
The type of the relevant ISO workgroup. Defaults to
WGif not supplied. Example values:
The name of the relevant ISO workgroup
The gem has been tested to date against the "Rice document", the ISO’s model document of an international standard. Sample representation of the Rice document in Asciidoctor, and output formats, are included in the https://github.com/riboseinc/isodoc-rice repository.
spec/metanorma-iso for individual features.