Gem Version Build Status Code Climate

Warning
This gem is still under development.

Formerly known as asciidoctor-iso.

Functionality and Approach

For the conceptual underpinnings of this gem, and the other gems in the Metanorma suite, see the metanorma-standoc README.

Outputs

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 .html file follows ISO conventions in rendering, which looks very similar to the Word output, while the -alt.html file 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".)

Usage

The preferred way to invoke this gem is via the metanorma script:

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

Installation

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 (incorporating the metanorma executable seen above).

Content Warnings

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

Bibliography

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.

Document Attributes

The gem uses the document attributes defined for metanorma-standoc (see the metanorma-standoc README).

The following document attributes are specific to ISO:

:tc-docnumber:

The document number assigned by the Technical committee

:partnumber:

The ISO document part number. (This can be "part-subpart" if this is an IEC document.)

:title-intro-en:

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

:title-main-en:

The main component of the English title of the document (mandatory).

:title-part-en:

The English title of the document part

:title-intro-fr:

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

:title-main-fr:

The main component of the French title of the document (mandatory).

:title-part-fr:

The French title of the document part

:doctype:

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.

:docstage:

The stage code for the document status (see International harmonized stage codes). This attribute and :docsubstage: replace the :status: attribute of metanorma-standoc.

:docsubstage:

The substage code for the document status (see International harmonized stage codes)

:iteration:

The iteration of a stage, in case there have been multiple drafts (e.g. 2 on a CD: this is the second iteration through the CD stage).

:secretariat:

The national body acting as the secretariat for the document in the deafting stage

:technical-committee-number:

The number of the relevant ISO technical committee (also :technical-committee-number_2:, :technical-committee-number_3:…​; the same applies for all technical-committee, subcommittee and workgroup attributes)

:technical-committee-type:`

The type of the relevant technical committee. Defaults to TC if not supplied. Values: TC1, `PC, JTC, JPC.

:technical-committee:

The name of the relevant ISO technical committee (mandatory)

:subcommittee-number:

The number of the relevant ISO subcommittee

:subcommittee-type:

The type of the relevant ISO subcommittee. Defaults to SC if not supplied. Values: SC, JSC.

:subcommittee:

The name of the relevant ISO subcommittee

:workgroup-number:

The number of the relevant ISO workgroup

:workgroup-type:

The type of the relevant ISO workgroup. Defaults to WG if not supplied. Example values: JWG, JAG, AG (advisory group), AHG, SWG, SG, MA (maintenance agency), CORG, JCG, CAG

:workgroup:

The name of the relevant ISO workgroup

Examples

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.

See also spec/metanorma-iso for individual features.