The Metanorma workflow
The Metanorma workflow consists of six phases:
-
Document creation
-
Editing the document
-
Validation
-
Output generation
-
Review
-
Publication
Document creation
You can create a new standard document either by:
-
Creating a new, empty AsciiDoc file
-
Using a template
-
Importing a Word Document
New file
The easiest way is to create a document from scratch, by creating an empty AsciiDoc file (.adoc
) in the desired folder.
Templates
Templates get you started faster, as they provide the structure of a standard document already. If your organization provides templates, you can create a new document based on a template using the command line.
Import from Word
Importing from Word makes sense if you are moving from Word to Metanorma and need to move several, large documents. To facilitate the migration, you can use the import tool called Reverse AsciiDoc. However, the imports are not always perfect, so you need to be familiar with the Metanorma and know how to resolve error messages. If you new to Metanorma, the simplest way is to transfer your content into Metanorma AsciiDoc manually.
Editing the document
You can edit Metanorma documents in any plain-text editor because they only consist of text. The next lesson will introduce you to the basics of AsciiDoc. These editors have been reported to work well for writing Metanorma AsciiDoc:
-
Atom with Asciidoctor plugins
-
Microsoft Visual Studio Code with AsciiDoc extension for live preview
Validation
Before you can generate any outputs, the AsciiDoc document needs to be checked against the document model to ensure it follows the rules of your SDO. Since the document model is defined in an XML schema, the compiler converts the AsciiDoc document into an XML file. The XML file is then checked against the SDO’s XML schema. Metanorma will log all deviations from the SDO’s structure or formatting on the terminal and into an error file.
-
❌ Invalid XML: The XML file does not comply with the XML schema, or with the formatting rules defined by the SDO. All errors are logged to the terminal and are saved to an Error file (.
err
). Often the document will render successful despite errors, but the error messages point out potential issues with the document structure. -
✅ Valid XML: The XML file complies with the XML schema and the compiler can proceed to generate an output.
Output generation
The Metanorma toolchain compiles documents in the following formats:
-
Metanorma XML
-
HTML
-
PDF
-
Microsoft Word
Metanorma XML
Metanorma always generates an XML output first because it is the intermediate format used to drive the other formats. The Metanorma XML file marks up the semantic content of the standards document and is therefore used during the validation stage. Metanorma then generates a presentation version of the XML (.presentation.xml
), which resolves cross-references, captions, and internationalisation, and is used as the basis of all other formats.
HTML
The HTML output is in HTML 5. All HTML output has a sidebar with a Javascript-generated table of contents, which is two section levels deep. Audio and video files are not supported.
Metanorma generates PDF output from XML. The styling comes from an XSL-FO stylesheet. A processing engine (Apache FOP) interprets the stylesheet and generates the PDF.
Microsoft Word
Metanorma can also generate a .doc
Word output. Metanorma does not output .docx
because it is easier to support all of the formatting requirements in a .doc
file.
Review
Standards documents require collaboration and every SDO has its own process for reviews. Metanorma does support authors and reviewers by providing metadata that indicate in which phase the document is in and who reviewed it. You can add your remarks to a document with comments or create a to-do if you want someone to act.
Publication
Once you and your reviewers agree that the standard is ready for publishing, you send it to your standard developing organization (SDO). The SDO will publish your document in their preferred channels, such as online or print.
Before we dive into AsciiDoc, let’s summarize what we’ve covered so far.