Metanorma: Aequitate Verum

Metanorma for ISO

Content style validation

ISO/IEC DIR 2

Metanorma tries to impose rules on content taken from ISO/IEC DIR 2, including restrictions on where requirements may be stated, usage of decimal points, hanging clauses, and subclauses that are the only child of their parent clause. While the error detection is not infallible, they should be reviewed at least once. Where possible, the gem will give the ID or section heading associated with the error. For example:

ISO style: WARNING (Section: ): Footnote may contain requirement: The maximum permissible mass fraction of defects shall be determined with respect to the mass fraction obtained after milling.
ISO style: WARNING (Section: Wire sieve,): possible decimal point: 0.02
ISO style: invalid technical committee type XYZ
ISO style: AnnexA-4-1:Preparation of test sample: subsection is only child

If any content warnings are generated during build, you will see them prefixed with ISO Style.

Style rules involving text are currently specific to content in English, except where otherwise noted.

The style rules implemented include:

  • Numbers with what looks like dots instead of commas for decimal points. (ISO/IEC DIR 2, 9.1)

  • Groups of numbers without spacing for every three digits. (The gem attempts to ignore ISO references. The gem also avoids numbers between 1900 and 2050 as potential years, unless :validate-years: is set [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.4.4].) (ISO/IEC DIR 2, 9.1)

  • No space before percent sign. (ISO/IEC DIR 2, 9.2.1)

  • No bracketing of tolerance in percentage (e.g. 15 ± 7 % .) (ISO/IEC DIR 2, 9.2.1)

  • Avoid "billion" (ISO/IEC DIR 2, Table B.1)

  • Abbreviated terms should not contain full stops (ISO/IEC DIR 2, 8.4)

  • Avoid language-specific abbreviated terms like ppm (ISO/IEC DIR 2, 9.3)

  • Space between number and unit symbol, other than degree, minute, second (ISO/IEC DIR 2, 9.3)

  • Only use SI units, as set out in ISO 80000 and IEC 80000 (ISO/IEC DIR 2, 9.3)

  • No recommendations, permissions or requirements (detected by keyword) in: foreword, scope, introduction, term examples and examples, notes, footnotes. (ISO/IEC DIR 2, 12.2) (ISO/IEC DIR 2, 13.2) (ISO/IEC DIR 2, 14.2) (ISO/IEC DIR 2, 16.5.7) (ISO/IEC DIR 2, 24.5) (ISO/IEC DIR 2, 25.5) (ISO/IEC DIR 2, 26.5)

  • No requirements in term definitions (ISO/IEC DIR 2, 16.5.6)

  • Cross-referenced terms are italicised (implicit in ISO/IEC DIR 2, 16.5.10)

  • No subclauses that are the only child of a clause (in clauses, annexes, or scopes.) (ISO/IEC DIR 2, 22.2)

  • 5 levels of subclause nesting. (ISO/IEC DIR 2, 22.3.2)

  • Non-ISO/IEC reference turning up as normative. (ISO/IEC DIR 2, 10.2)

  • Term definition starts with an article, or ends with a period. (ISO/IEC DIR 2, 16.5.6)

  • Title intro or title part appears in only one of French or English.

  • Subparts are only permitted in IEC documents (ISO/IEC DIR 2, 11.4)

  • The type or nature of the document (e.g. International Standard, Technical Specification, Publicly Available Specification, Technical Report or Guide) shall not be indicated in the title. (ISO/IEC DIR 2, 11.5.2)

  • Each clause shall have a title (ISO/IEC DIR 2, 22.2)

  • A subclause shall not be created unless there is at least one further subclause at the same level. For example, text in Clause 10 shall not be designated subclause "10.1" unless there is also a subclause "10.2". (ISO/IEC DIR 2, 22.3.2)

  • "see" and "refer to" can only introduce informative references. (ISO/IEC DIR 2, 15.5.3)

  • Undated references may be made only to a complete document. (ISO/IEC DIR 2, 10.4)

  • Forewords shall not be subdivided (ISO/IEC DIR 2, 12.4)

  • Normative references shall not be subdivided (ISO/IEC DIR 2, 15.4)

  • The Scope may be subdivided; however, this is not normally necessary as it is meant to be succinct. (ISO/IEC DIR 2, 14.4)

Syntax validation

ISO/IEC DIR 2 is more strict than most standards about the order and contents of clauses. Many of these rules are realized through the XML schema of the Metanorma ISO flavour, and they are reported on through syntax validation. Users should pay particular attention to syntax errors in Metanorma ISO documents.

ISO house style

Metanorma also takes the rules in the ISO house style into account [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.0.5], including 2022 and 2023 updates [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.4.4]. Metanorma now validates against the following requirements:

  • References in Clause 3 (Terms and definitions): Cross-references in terms clauses can only reference content within terms clauses. Cross-references outside of terms clauses can only reference content outside of terms clauses. So terms clauses and other content are self-contained in cross-referencing.

  • Lists: List punctuation needs to be consistent with that of the sentence preceding it.

    • If the list comprises several sentences, then use the following list format.

      • The introductory sentence is a complete sentence and ends with a colon or a full stop.

      • The list items are complete sentences that start with a capital letter and end with a full stop.

    • If the list comprises one sentence broken into a list format, then:

      • the introductory sentence is a partial sentence and preferably ends with a colon;

      • the list items start in lower case and end with a semicolon (preferred) or a comma, used consistently;

      • the final list item ends with a full stop.

  • Lists: There should not be more than one ordered list in a numbered clause.

  • Lists: No list should be more than four levels deep.

  • Vocabulary documents: Single terms clause in vocabulary document should have normal Terms and definitions heading. Multiple terms clauses in vocabulary document should be prefixed with "Terms related to".

  • Numbers: The Unicode minus sign, U+2212, should be used instead of the hyphen.

  • And/Or: The conjunction and/or should be avoided.

  • And or &: Avoid ampersand in ordinary text

  • Full stops: Do not use full stop at the end of a title or caption.

  • Need to, might & could: Warn of ambiguous provision wording.

  • Quantities and units: Warn of more than one level of nesting of subscripts.

  • Cross-references to an unnumbered document: Superscript cross-references must follow punctuation.