Introducing the Metanorma collection, through the SI Brochure

Alexander Bobrikovich

Ronald Tse on 11 Jul 2022

Summary

The Metanorma collection functionality is a new feature used by complex standards published using Metanorma.

In this blog post we will use the SI Brochure, published by the BIPM, as an example of how it is used.

This post will illustrate how to compile the BIPM SI Brochure using the collection sub-command.

What’s in a Collection?

Standards are typically published as individual documents. However, there are standards that are a lot more complex:

the ISO 10303 series of standards is published as a collection known as the STEP Module and Resource Library (SMRL), with interlinking links and embedded computer-readable EXPRESS models;
the BIPM SI Brochure is composed of multiple documents, including the main content, CGPM and CIPM outcomes in both French and English, all cross-linked, together with over 20 mise en pratique documents, where each of these components can be individually published.

The SI Brochure

The SI Brochure is the authoritative document detailing the now ubiquitous International System of Units (SI) (Wikipedia), commonly called the "SI system".

The SI system is established and maintained by the General Conference on Weights and Measures / Conférence générale des poids et mesures (CGPM), which was established by the Metre Convention (Wikipedia) of 1875.

The SI Brochure is offered under the Creative Commons 3 license.

The Metanorma team has been tasked by BIPM to develop a machine-readable form of the BIPM SI Brochure, of which the workings is worthy of several blog posts.

In this blog post, we use the BIPM SI Brochure to illustrate how to compile a Metanorma collection.

SI Brochure in Metanorma

The SI Brochure is structured as a Metanorma collection.

Specifically, it is published in 3 forms:

A French-English bilingual version
A French version
An English version

Figure 1. Metanorma-generated SI Brochure (bilingual)

Figure 2. Metanorma-generated SI Brochure (French)

Figure 3. Metanorma-generated SI Brochure (English)

In Metanorma, the French and English versions are independent documents. The bilingual version, on the other hand, is a composite document that is directly composed of the combination of the French and English documents.

Can’t we just "concatenate the two documents and slap on a new cover page"?

It is actually a lot more complex than this:

The French and English versions contain cross-references to each other. In the bilingual composite version, these links become internal links, and the corresponding references in the bibliography are also considered internal within the collection (since both parts are given in the same document)
The metadata of the individual documents and the metadata of the bilingual collection differ but both need to be reflected.
The document elements shared between the French and English documents, such as figures, resolution outcomes and bibliographic references, should not be duplicated in the bilingual collection.
The bilingual collection allows the generation (or extraction) of its source components, namely, the French and English documents in their desired form and respective cover pages.

Ultimately, this structure allows us to retain only a single source of truth without duplication while keeping the document components independent.

Compiling the collection

As mentioned, the SI Brochure is offered under the Creative Commons 3 license so there should not be licensing concerns in performing this exercise.

The draft version of the machine-readable SI Brochure is available at:

https://github.com/metanorma/bipm-si-brochure

Once you have installed Metanorma, you are ready to do the actual compilation of the document.

The commands that follow have been tested to work on Windows, macOS and Linux.

Clone the repository with your favorite Git application. We recommend either using the git command or GitHub Desktop.

If using the git command, you could do:

$ git clone https://github.com/metanorma/bipm-si-brochure

Generate the source Metanorma documents into site/documents:

$ metanorma site generate -c brochure.yml --agree-to-terms

Note	The `-c brochure.yml` flag is used to only generate necessary files for the bilingual SI Brochure; it does not compile any MEP documents.

Once it is finished you will be able to see compilation results under site/documents.

Note	This is the default directory but you can change the target directory with the `--output-dir` argument.

Then generate the bilingual collection documents with:

$ metanorma collection collection.yml -w collection -x xml,pdf -c sources/collection_cover.html --agree-to-terms --no-continue-without-fonts

Note	On Windows, the above command must be entered on a single line.

Note	This step may take some time depending on processor speed.

The resulting document will be generated in the directory collection. You should see these files generated:

Bilingual SI Brochure (PDF): collection.pdf
Language-specific SI Brochure (PDF)
- English SI Brochure collection_en.pdf
- French SI Brochure collection_fr.pdf
Metanorma XML files
- Metanorma Semantic XML collection.xml
- Metanorma Presentational XML collection.presentation.xml

The machine-readable versions of the SI Brochure are in the XML files. The semantic version provides full semantic encoding of content, where the presentational version provides rendering-oriented structured content.

If you are curious of the inner workings of the Metanorma collection, have a look at collection.yml which provides instructions to Metanorma on how to process the input files.

Conclusion

Metanorma provides a flexible collection compilation functionality for standards. The bilingual SI Brochure can be technically generated just with one line of command (or two!).

We will likely follow up with more articles on how a collection works. Stay tuned!