Writing in AsciiDoc, Part 4

Nick Nicholas on 15 Jan 2019

In our foregoing discussion, we have presented how to mark up standards documents for Metanorma using AsciiDoc markup. Two types of section have specialized content, which requires additional markup: Terms and definitions, and Bibliographies.

Bibliographies

We have already seen an example of how bibliographies are marked up in Part 2 of this series:

[[infobib]]
[bibliography,obligation=informative]
== Informative Bibliography

* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_

== Next heading...

References are provided as a list of bibliographic anchors (in triple brackets, to differentiate them from normal internal cross-reference anchors, which are in double brackets). The bibliographic anchor is followed by a comma, and then the title of the reference. As we have noted, the section containing such bibliographic anchors must have the style attribute bibliography, to be processed by Metanorma AsciiDoc correctly.

Any bibliographic anchor must consist of a cross-reference token (without spaces), which is how the reference will be cited within Metanorma AsciiDoc, and the official code used to refer to the document as a standard, separated by a comma. The cross-reference token is arbitrary, and does not need to correspond to the document code at all: [[[ref33,ISO 3696]]] would work just as well.

On the other hand, the document code is used to fetch the current correct reference to the standards document where the bibliography is accessible online. For that reason, the document code needs to be correct, or else the right document will not be retrieved. In the case of ISO, IEC, and GB, the code is also expected to contain references to part numbers, if only a document part is cited, and to the year, if a specific edition of the standard is cited; so [[[a,ISO 3166-2:2007]]] refers to the 2007 edition of ISO standard 3166, part 2, and [[[b,GB/T 1.1-2009]]] refers to the 2009 edition of GB/T standard 1, part 1.

If the document is not a standard but a generic reference, the document code is replaced by a number; for example,

* [[[ref10,10]]] [smallcap]#Standard No I.C.C 167#. _Determination of the protein content in cereal and cereal products for food and animal feeding stuffs according to the Dumas combustion method_ (see http://www.icc.or.at)

Any number of sections can be marked up as bibliographies with the style attribute bibliography. Following ISO practice, there are usually two bibliographies in a standards document: a "Normative References" section, which contains references to documents with normative effect (almost always standards); and a general "Bibliography", which contains references to documents with informative effect. Under ISO, these two bibliographies are rendered differently, and appear in different locations of the document.

Relaton

The relaton family of gems is used to fetch references where available from online bibliographies; it is used within Metanorma to update any bibliographic references with the current correct title. It is currently implemented for ISO, IEC, IETF, and the GB family of standards. The bibliographic entries it fetches online are cached locally, to avoid time-consuming refetching when the Metanorma document is re-compiled. (You will notice that when you first compile a document, each reference can take several seconds to resolve.)

Figure 1. IEC references gradually being fetched online through the magic of Relaton

By default two caches are created by relaton:

one global cache, storing all accesses to relaton (by default ~/.relaton/cache), and
one cache specific to the documents in the current directory (by default relaton/cache).

The caches contain one file for each accessed document, encoded in an XML schema specific to Relaton; you can edit the files, and reuse them between documents. The metanorma-standoc document attributes document how to override this behaviour, including not permitting relaton to resolve references at all.

In order to work out which website to fetch a reference from, the relaton gem needs to know what kind of standard is being referenced. ISO and IEC references always have their code prefixed by ISO and IEC; Relaton also recognizes that codes starting with RFC are IETF references, and that codes starting with GB are GB references. However, to remove ambiguity, and to deal with other document prefixes, the code provided can be wrapped in a prefix specific to the standards body: IETF(I-D.ribose-asciirfc-08) identifies I-D.ribose-asciirfc-08 as an IETF standard (an Internet Draft), while CN(GM/T 0009-2012) is the Chinese sector standard GM/T 0009-2012.

The relaton-cli tool exposes various functions of relaton to the command line.

Specifically, this command fetches a document with document code CODE as Relaton XML.:

relaton fetch CODE -t TYPE -y YEAR

The accepted TYPE's are one of:

iso, through the isobib gem,
ietf, through the ietfbib gem,
iec, through the iecbib gem,
gb, through the gbbib gem

The tool can also extract Relaton XML references from Metanorma documents, and it can convert Relaton XML to HTML, which allows a set of references (including a set of references to Metanorma documents) to be displayed as an HTML file.

Citations

A citation to a reference is marked up in Metanorma AsciiDoc the same way as an internal cross-reference, in << >>; so if you have a reference defined as [[[ref33,ISO 3696]]], the element <<ref33>> is a reference to ISO 3696. If you provide a cross-reference without a corresponding reference, Metanorma will issue a warning.

In Metanorma AsciiDoc, you can provide display text within a cross-reference, after a comma; so <<ref33,the aforementioned standard>> would be rendered as "the aforementioned standard". Metanorma AsciiDoc uses the display text to convey references to a specific location within a document, by using pairs of defined location names (clause, table, figure etc.) and numbers or number ranges. So <<ref33,clause 3,table 3,page 7-9>> will be rendered as "ISO 3696, Clause 3, Table 3, Page 7-9". Within ISO documents in particular, subclause references are not prefixed by "Clause"; so <<ref33,clause 3.1>> will be rendered as "ISO 3696, 3.1".

Terms and Definitions

Most standards documents have a section discussing the terms and definitions used in the document. These can often be a mere glossary of terms, which can be handled adequately as a definition list.

However Metanorma tries to deal with as much complexity as you are likely to find in common standards formats. ISO and IEC in particular provide a rich amount of information in their Terms and Definitions sections, including alternate and deprecated synonyms for the term being defined; the domain of the term (to be used in case of disambiguation); related notes and examples; and the source from which the term has been taken, where applicable. Moreover, ISO/IEC DIR 2, which prescribes the structure of ISO and IEC standards documents, imposes a strict structure on how this information will be presented.

Metanorma supports the ISO/IEC structure of Terms and Definitions by using macros, which are used to provide the requisite semantic information (for alternate, deprecated, and domain markup). A term itself is marked up as a terminal subclause of a Terms and Definitions section (so identified by its title): the term is treated as a term, rather than a subclause, unless it has the style attribute [.nonterm]:

== Terms and definitions

[.nonterm]
=== Introduction
The following terms have non-normative effect, and should be ignored by the ametrical.

[[paddy]]
=== paddy
alt:[paddy rice]
alt:[rough rice]
deprecated:[cargo rice]
domain:[rice]

rice retaining its husk after threshing

[example]
Foreign seeds, husks, bran, sand, dust.

NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking.

[.source]
<<ISO7301,section 3.2>>, The term "cargo rice" is shown as deprecated,
and Note 1 to entry is not included here

This example consists of an introduction (which is a subclause rather than a term), and the term paddy. The term has the synonyms paddy rice and rough rice, the deprecated synonym cargo rice, and is associated with the domain rice, to disambiguate it from other instances of the term paddy. The definition is the paragraph following from the header and synonyms; it can be followed by one or more examples, one or more notes, and a source paragraph.

The source paragraph is expected to start with the citation of the reference that the term is taken for, optionally followed by text indicating how that definition is to be modified for this document. The citation follows the convention already discussed, of using a reference anchor for a reference given in the bibliography, followed by a location within the document.

Often in ISO and IEC the International Electrotechnical Vocabulary is treated as a source of terms and definitions. The IEV corresponds to a large number of IEC 60050 standards, one part per subject area, and each with a different publication year. Rather than require authors to track each subject area separately, Metanorma allows citations to the dummy reference IEV (e.g. [[[iev,IEV]]]): each individual reference to an IEV term (e.g. <<iev,clause 113-01-01>> for “space-time”) is converted to a reference to the specific publication (in this case, IEC 60050-113:2011), and the bibliography is appropriately updated.