Metanorma: Aequitate Verum

Learning objectives for the tutorials

Before we dive into using the Metanorma toolchain, let’s cover the basic ideas you need to understand to work with Metanorma. In this lesson we will cover:

  • What Metanorma is

  • The differences between Word and Metanorma

  • The paradigms "What you see is what you get" vs. "What you see is what you mean"

  • What the Metanorma workflow looks like from document creation to publication

Before we write our first Metanorma document, let us look at the foundation for all Metanorma documents: AsciiDoc. In this lesson, we will discuss what AsciiDoc is and what a typical Metanorma document looks like. You will also learn how to write AsciiDoc.

Reviewing documents is an integral part of developing a standard. The best way to review a document, is to use a version control environment that supports comments as well, such as GitHub and its feature GitHub discussions. In case your organization does not use a git-based approach, Metanorma provides a comment functionality that lets you insert your remarks and create to dos. In this lesson, you will learn:

  • How to add comments using AsciiDoc markup

  • How to generate a draft using the command line.

Once you are happy with your document, the next step is to generate an output to send your SDO for publishing. Since Metanorma poses some validity criteria for your document, it is normal to face some errors. Don’t worry, we will go through some common errors and teach you how to resolve them. In this lesson you will learn:

  • How to generate PDF, HTML, and Word output using the command line

  • How to troubleshoot common errors