Metanorma: Aequitate Verum

Metanorma templates for CalConnect, OGC and ISO documents

Author’s picture Ronald Tse on 26 Apr 2019

Introduction

Today metanorma-cli 1.1.7 has been released and provides a much requested feature: Metanorma document templates.

Previously, there were two ways to create a new Metanorma document:

  1. Copy over an existing document and edit it; or

  2. Handcraft a new document from scratch.

Both methods are error-prone (and stressful). Worse, they also risk incompatibility with newer versions of the Metanorma framework, as attributes are updated.

Metanorma templates are supposed to help you exactly with this. A template provides not only a Metanorma document that allows you to get started easily, it also comes with a set of supporting files for you to manage your document project, including sample files for continuous integration services (Travis CI, Gitlab, AppVeyor).

As of today, the following standard flavors are officially supported (with the rest to come):

  • ISO

  • OGC

  • CalConnect

Note
 OGC is the Open Geospatial Consortium, which much of the world’s geographic information depends on.

The following command demonstrates how to create a new “OGC standard” document:

metanorma new my-new-ogc-standard -t ogc -d standard
# =>
# Creating my-new-ogc-standard/Makefile
# Creating my-new-ogc-standard/appveyor.yml
# Creating my-new-ogc-standard/Gemfile
# Creating my-new-ogc-standard/deploy.sh
# Creating my-new-ogc-standard/Makefile.win
# Creating my-new-ogc-standard/sections/clause_7_normative_text.adoc
# Creating my-new-ogc-standard/sections/clause_3_references.adoc
# Creating my-new-ogc-standard/sections/annex-a.adoc
# Creating my-new-ogc-standard/sections/annex-bibliography.adoc
# Creating my-new-ogc-standard/sections/clause_2_conformance.adoc
# Creating my-new-ogc-standard/sections/clause_0_front_material.adoc
# Creating my-new-ogc-standard/sections/clause_8_media_types.adoc
# Creating my-new-ogc-standard/sections/annex-history.adoc
# Creating my-new-ogc-standard/sections/annex-n.adoc
# Creating my-new-ogc-standard/sections/clause_5_conventions.adoc
# Creating my-new-ogc-standard/sections/clause_6_informative_text.adoc
# Creating my-new-ogc-standard/sections/clause_1_scope.adoc
# Creating my-new-ogc-standard/sections/clause_4_terms_and_definitions.adoc
# Creating my-new-ogc-standard/UML/README.adoc
# Creating my-new-ogc-standard/images/README.adoc
# Creating my-new-ogc-standard/abstract_tests/README.adoc
# Creating my-new-ogc-standard/code/README.adoc
# Creating my-new-ogc-standard/requirements/requirement.adoc
# Creating my-new-ogc-standard/requirements/README.adoc
# Creating my-new-ogc-standard/requirements/requirements_class.adoc
# Creating my-new-ogc-standard/README.adoc
# Creating my-new-ogc-standard/document.adoc
# Creating my-new-ogc-standard/figures/README.adoc

The main document file is provided as document.adoc. The template uses Metanorma AsciiDoc includes to split the document up into different files.

Note
 The bulk of functionality described here was merged in https://github.com/metanorma/metanorma-cli/issues/35.
Metanorma templates raining structure down onto your documents
Figure 1. Metanorma templates raining structure down onto your documents

Usage

It’s easy to find out how to use this with our (relative new) CLI interface.

Simply type metanorma help new to see usage instructions for the metanorma new command:

metanorma help new
# =>
# Usage:
#   metanorma new NAME -d, --doctype=DOCTYPE -t, --type=TYPE
#
# Options:
#   -t, --type=TYPE              # Document type
#   -d, --doctype=DOCTYPE        # Metanorma doctype
#   -r, [--overwrite=OVERWRITE]  # Overwrite existing document
#   -g, [--template=TEMPLATE]    # Git hosted remote template skeleton
#
# Create new Metanorma document

As for the options:

-t or --type=

the standard flavor such as, iso, ogc, calconnect

-d or --doctype=

the document type within the standard flavor; for example, ogc templates offers standard, best-practice, white-paper, etc.

-g or --template=

(optional) for loading a template from a Git repository. (more on this later)

How does this work?

A Metanorma template is located within a Metanorma template repository.

Right now, all official Metanorma template repositories are provided at Metanorma’s GitHub account under the repository prefix mn-templates-{flavor}. For example, the repository for CalConnect is located at https://github.com/metanorma/mn-samples-cc.

The metanorma new command fetches the correct template from the repository, and populates a new directory (with name of your choice) with it.

The template files provided are nearly empty: you replace what is in them with your content.

Other than actual document files, build scripts are also typically included in the directory. For example, the Makefile (macOS, Linux) and Makefile.win (Windows) provided allows you to run make compile the generated Metanorma document with correct outputs, and clean up built files with make clean (via the make utility).

Consult the README.adoc files in each subdirectory for more instructions on how to populate each file.

Selecting a template

The easiest way to list the available templates from a template repository is to go straight to the repository source.

Note
 A command for listing out available templates is being developed here.

For example, at https://github.com/metanorma/mn-samples-cc you can see the following directory structure:

  • admin/

  • advisory/

  • directive/

  • report/

  • standard/

All directories shown here are Metanorma templates: admin, advisory, directive, report and standard. Each of these templates takes the directory name as its name, and provides a fully-buildable document within it.

In this template repository, the names of templates match the names of document types at CalConnect. However, this is not necessary — one can create a template of any name for any document type. For example, we could create a separate template for draft directives, for published directives, and for withdrawn directives.

Note
 The full list of CalConnect document types are provided in CC/DIR 10001:2019.
Note
 We have not mentioned the common/ directory, because it is not a template. More on this below.

Creating from a custom template

For those using private Metanorma standard flavors, you could also host your own Git repository for your templates, where access control can be performed.

To create documents using custom templates, run the following:

metanorma new my-new-private-requirement-document \
  -t private-flavor \
  -d special-doctype \
  -g https://gitlab.com/my-account/my-private-mn-template-repo
  # or for SSH:
  # -g git@gitlab.com:my-account/my-private-mn-template-repo.git

Here,

private-flavor

represents a private Metanorma standard flavor

special-doctype

represents a specific template provided in your private Metanorma template repository

https://gitlab.com/my-account/my-private-mn-template-repo

represents the location of the private Metanorma template repository. This address represents a Git address; both HTTPS and SSH are supported.

Structure of a template repository

A template repository is composed of the following structure:

{template}/

a template of the repository, can be named as anything (except the reserved word common)

common/

all files under common are copied across to a generated template. This is a convenience feature for template repository managers, to ensure all templates utilize the same common files, such as continuous integration configuration and scripts, Makefile and Makefile.win, etc.

README.adoc

(optional) the README of the template repository that describes what templates are available and how to use them.

LICENSE

(optional) describes the license that applies to these templates (not to documents created from the template)

Structure of a template

Each template under {template}/ has the following structure:

document.adoc

this is the main Metanorma file for the document. This is mandatory in every template.

README.adoc

(optional) a README file meant for the generated document per the standard flavor’s requirements.

Others

all other directories and files are allowed in the template directory; they will be faithfully copied to the generated document.

Making your own template repository and templates

It is straightforward to create a custom template repository.

  1. Create a Git repository. e.g. on GitHub, GitLab or your favorite service.

  2. Create a common/ directory (feel free to copy the common/ files from our official template repos)

  3. Create your first template with a handcrafted (or modified from an existing document) in a directory name of your choice, and fill it in.

Users of this template repository just need to specify the -g option to indicate where the repository is to be found when creating a document.

That’s it. Happy templating!