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.
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
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,
[[[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
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 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.)
By default two caches are created by
one global cache, storing all accesses to
one cache specific to the documents in the current directory (by default
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
metanorma-standoc document attributes
document how to override this behaviour, including not permitting
relaton to resolve references
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
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:
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:
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.
A citation to a reference is marked up in Metanorma AsciiDoc the same way as an internal cross-reference,
<< >>; 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
== 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
is converted to a reference to the specific publication (in this case, IEC 60050-113:2011),
and the bibliography is appropriately updated.