Writing in AsciiDoc

Nick Nicholas on 11 Dec 2018

Metanorma AsciiDoc

If you want to write a document in Metanorma, you will be using the AsciiDoc markup language to write text.

The Asciidoctor User Manual gives the formatting commands and structures that AsciiDoc can encode; almost all of them will result in something meaningful in Metanorma — although the way they are rendered in Metanorma may not always be the same as how they are rendered by the AsciiDoc tool itself.

Note	There are a few capabilities in Asciidoctor AsciiDoc which are not rendered in Metanorma AsciiDoc, such as embedded video, indexes, and verse quotations. But you are unlikely to run into them, because they are not required by the kinds of document Metanorma has modelled to date.

Metanorma AsciiDoc allows you to do things which AsciiDoc on its own cannot, for example:

The structure around Terms and Definitions, can be elaborate and quite domain-specific; so we have defined markup specific to Terms and Definitions, including markup for term domains, alternative terms, deprecated terms, and term sources.

The enhancements common to all flavors of Metanorma are listed in https://github.com/metanorma/metanorma-standoc#asciidoctor-model-additions, and any enhancements specific to a flavor of Metanorma are given in the Readme of the corresponding Ruby gem; for example, https://github.com/metanorma/metanorma-iso#asciidoctor-model-additions for features specific to ISO.

We also have documentation available online on how to write documents:

Note	We are in the process of consolidating our documentation in the one place, but as Metanorma services a lot of different standards organizations, there is a continuing split between generic functionality and functionality specific to a flavor of Metanorma.

If you’re going to spend serious time with Metanorma, you will need to get familiar with everything in those documents. But in this series of posts, we will ease you in with a simple document.

Getting started: A text document

Metanorma AsciiDoc documents are text; so if you already have a document in a PDF file, or a Word file, or an HTML file, the simplest thing to do is to copy its text into a text document, and then to mark it up. Yes, you will lose all your formatting that way; but remember, part of the point of using Metanorma is that much of the formatting will be automated; you will be giving only the essentials needed for formatting as markup in the document.

By losing the markup through copy-paste, you are starting with a clean text, and you control what markup actually needs to be reintroduced. Your document is going through a kind of cleanse. Like a car wash, only with less suds, and with you doing your own wax polishing, instead of leaving it to the attendant.

Metanorma AsciiDoc document generation as car wash

Figure 1. Manual MS Word to AsciiDoc document conversion as car wash.

Note

If you are feeling adventurous, https://github.com/metanorma/reverse_adoc is a tool we have created that maps HTML to Metanorma AsciiDoc, and can even be used to convert Word documents to Metanorma AsciiDoc. If you’ve got a lot of “essential” formatting, particularly mathematics, it might make sense to use it. Most of the time, though, it is simpler just to mark up text from scratch.

So, go ahead. Open up a text editor, and cut and paste all the text you need into it. (Or, if you don’t already have any text to convert, just start typing.)

The next thing you are going to have to do is make sure there are paragraphs in your text. In Metanorma AsciiDoc, a paragraph is not indicated by a single carriage return, but by two: you need to be able to see space between the paragraphs on the screen.

There is a parargaph break here.
But Metanorma AsciiDoc will still treat these two lines as a single paragraph, and will join this line
up with the previous line.

This, on the other hand, is a new paragraph.

Markup in Metanorma AsciiDoc uses non-alphabetic characters. If you want to italicize a word within a paragraph, for example, you put _ around it. (If you’re italicizing a whole paragraph, on the other hand, because it is a subheading, you probably shouldn’t: formatting titles is likely to be taken care of by your standard’s stylesheet.

Typical AsciiDoc knows about _italics_, *boldface*, `monospace`,
and a few others. Metanorma AsciiDoc provides additional macros to deal with
[strike]#strikethrough text# and [smallcap]#text in small capitals#.

Notice that formatting commands involve non-alphabetic text: _, *, \`. Strikethrough and small-caps are not built in to typical AsciiDoc, they are specific to Metanorma AsciiDoc, which are also indicated with non-alphabetic text: brackets and hashes.

Note

Because non-alphabetic characters are used to indicate formatting commands, that means they can be misinterpreted in typical AsciiDoc text. Most of the time they won’t; but full stops [periods] and square brackets at the start of a line are already used to indicate formatting, as will formatting like * on either side of a group of characters. If you want those characters not to be treated like formatting, it is usually enough to put a backslash \\, in front of the character.

Headings

Your document will need to have headings and subheadings, like any non-trivial standards document does. Headings are marked up by prefixing a paragraph with a number of equal signs — one more than the heading level — followed by space. So a first level heading is prefixed by `== `; a second level heading by `=== `; and so on:

== First Level Heading

Some Text

=== Second Level Heading

Some More Text

You do not need to make the heading italicized or boldface: again, that will be taken care of by the Metanorma flavor stylesheets.

Document header

To make the text work as an Metanorma AsciiDoc document, it needs to be introduced by a document header, which contains metadata about the document, expressed as document attributes: key-value pairs, with the key surrounded by colons.

Different flavors of Metanorma have different kinds of metadata: again, the gem README for your particular flavor describes the document attributes specific to it (Metanorma document attributes for ISO), while Metanorma document attributes for StanDoc describes the document attributes that apply across Metanorma.

The textual structure goes in this order:

The document header consists of the document title, which is a line prefixed with an equals sign and a space;
A line which gives the authors of the document (which is ignored in Metanorma, but is still required by typical AsciiDoc processors);
The list of document attributes, one per line. There can be no blank lines within the document preface, and there has to be a blank line between the document header and the rest of the document;
Actual body text.

For example:

= Document Title
Author Name Which Metanorma Ignores
:published-date: 2017-01-02
:language: en
:status: published
:no-isobib:

Text of document starts here.

Note	In some flavors (like Metanorma-ISO), titles are compound and multilingual, and need to be given in separate document attributes. In that case, the title of the document header is ignored.

Once your document has a document header, paragraphs, and headers, it is ready for you to process through Metanorma. There will be a lot more to refine in the document, (as we’ll discuss next post), but that will give you a start to work with.

All those cryptic wax polishing illustrations we showed before should now make a little more sense:

Figure 2. Metanorma AsciiDoc document generation as car wash, re-contextualized.