How to use the Metanorma tutorial repository

This repository contains exercises for the beginner Metanorma tutorial. The document is based on OGC’s "OGC® WPS 2.0.2 Interface Standard Corrigendum 2" and is written in Metanorma-OGC. Please note that standard organization has different needs. Therefore, each Metanorma AsciiDoc flavor has slightly different document headers (metadata) and may require a different document structure.

Source files provided in this repo

• OGC-WPS-single-file.adoc: Metanorma-OGC markup source document for the WPS 2.0.2 Interface Standard Corrigendum 2

• OGC-WPS-sections.adoc: Metanorma-OGC markup source document for the WPS 2.0.2 Interface Standard Corrigendum 2 document, referencing the individual files in sections/*

• sections/*: The Metanorma-OGC markup source document for the WPS 2.0.2 Interface Standard Corrigendum 2 document, broken up into separate files for each section

• images/*: Contains the referenced images

• rendered_output/*: This folder contains pre-rendered versions of the Metanorma document, so that you know what you are working towards.

Prerequisites

To write and compile Metanorma documents yourself, you need:

• Installation of git

• Installation of Metanorma

  Note	Docker allows you to get started quicker than a local installation, because it already contains all dependencies.

• Text editor of your choice, for example VS Code or Atom

• Familiarity with the command line

Fetching the document

1. Open a new terminal.

2. Go to the directory you want to save the tutorial repository in. For example:

   $ cd Documents/Metanorma

3. Run the following command to copy the repository onto your machine:

   git clone https://github.com/metanorma/metanorma-tutorial/

Writing Metanorma documents

If you are not yet familiar with Metanorma and AsciiDoc, this repository, together with the Metanorma tutorial, will help you getting started.

If you are already familiar with Metanorma and need a refresher on how to compile a document, read the following section.

Compiling a Metanorma document

Depending on the type of installation and your OS, the command to compile a Metanorma is slightly different.

Local installation (Windows, macOS, Linux)

If you have installed Metanorma and its dependencies on your machine, you can generate a document like this:

1. Open a new terminal.

2. Go to the directory where your Metanorma document(s) are stored. For example:

   $ cd Documents/Metanorma/metanorma-tutorial

3. Use the following command to compile a Metanorma document. To learn more about the command syntax and options, read the metanorma-cli documentation.

   Note	The fontist automatically installs all needed fonts. The --agree-to-terms option agrees to all font license agreements that come up during the compilation process. If you don’t set this option, you will be asked to agree to the licenses during the compilation process which might break it.

   metanorma compile sources/standard/OGC-WPS-single-file.adoc --agree-to-terms

Running Metanorma in Docker

If you don’t want to deal with local dependencies, use the Docker image. If you are not yet familiar with Docker, the learning curve is a bit steeper than with a local installation, but it pays off. Docker provides a great Getting started tutorial.

Prerequisites

• Installation of Docker

• Metanorma Docker image

  Note	Install the metanorma/metanorma image for a stable release.

• Familiarity with Docker.

To compile a Metanorma document using Docker:

1. Open a new terminal.

2. Start Docker using Docker Desktop.

3. Go to the directory where your Metanorma document(s) are stored. For example:

   $ cd Documents/Metanorma/metanorma-tutorial

4. Start the container and compile the document. To learn more about the command syntax and options, read the metanorma-cli documentation.

   Note	The fontist automatically installs all needed fonts. The --agree-to-terms option agrees to all font license agreements that come up during the compilation process. If you don’t set this option, you will be asked to agree to the licenses during the compilation process which might break it.

   Docker on Linux and macOS

   docker run -v "$(pwd)":/metanorma/ -w /metanorma metanorma/metanorma metanorma compile -t ogc sources/standard/OGC-WPS-single-file.adoc --agree-to-terms

   Docker on Windows

   docker run -v "%cd%":/metanorma/ -w /metanorma metanorma/metanorma metanorma compile -t ogc sources/standard/OGC-WPS-single-file.adoc --agree-to-terms

Description of generated artifacts

While Metanorma runs, it generates the following files from the AsciiDoc input:

• {filename}.xml: Metanorma-OGC XML output corresponding to the {filename}.adoc source

• {filename}.rxl: Document that contains Relaton XML references

• {filename}.html: Metanorma-OGC HTML output corresponding to the {filename}.adoc source

• {filename}.doc: Metanorma-OGC Word output corresponding to the {filename}.adoc source

• {filename}.pdf: PDF output, formatted according to OGC’s specification.

• {filename}.err: File that contains error messages from the compilation process. Note: Not all errors cause the build to fail, and it’s common to have some minor errors. As long as the output works and looks as expected, you do not need to start troubleshooting.

Managing complex Metanorma documents

Managing complex Metanorma documents

The WPS 2.0.2 Interface Standard Corrigendum 2 document is given here both as a single source document and broken up into separate files, to illustrate both ways of managing Metanorma content.

Single file

The single-file setup is illustrated in the file OGC-WPS-single-file.adoc. The document header (metadata) as well as all content clauses are written within the same AsciiDoc document.

Pro: Shorter documents, which are authored by only one person, could be set up as a single file. This approach allows you to search and replace within a single document.

Con: Long documents can become hard to work with in text editors. If more than one person works on the same file, you might run into merge conflicts that need to be resolved manually.

Multiple files

The document OGC-WPS-sections.adoc includes the document header and the following files.

The section files are listed in order of appearance in the document, and each corresponds to a first-level clause of the document:

• 00-abstract.adoc: Foreword

• 01-scope.adoc: Scope

• 02-conformance.adoc: Conformance

• 03-references.adoc: Normative References

• 04-terms-def.adoc: Terms and Definitions

• 05-conventions.adoc: Conventions

• 06-wps-conceptual-model.adoc: WPS Conceptual Model

• 07-wps-native-process-model.adoc: WPS Native Process Model

• 08-wps-native-process-model-encoding.adoc: WPS Native Process Model Encoding

• 09-common-wps-service-model.adoc: Common WPS Service Model

• aa-abstract-test-suite.adoc: Annex A

• ab-xml-examples.adoc: Annex B

• az-bibliography.adoc: Bibliography

Pro: A multi-file approach grants you modularity, which has a number of benefits:

• It’s possible to reuse chapters.

• You can troubleshoot documents easier.

• When you separate the header from the content, you can generate standards to be published in more than one organization, for example ISO and OGC documents.

• You can split the work across different files to minimize problems with version control.

Con: Operations like "search and replace" become a bit more tedious, because you have to look at multiple files to catch each instance of the word (or something else) you want to update. However, this weak point can be beat by tools like Visual Studio code that can search throughout a whole repository.

Summary

The best way to learn Metanorma is to follow along the Metanorma tutorial. This repository contains all exercises to help you get a grasp of Metanorma AsciiDoc.

If you already have a bit experience, feel free to look through the flavor-specific sample repositories.