Metanorma AsciiDoc tips

Metanorma AsciiDoc adopts Asciidoctor syntax for AsciiDoc, and the Asciidoctor User Manual is an excellent companion when authoring Metanorma AsciiDoc documents.

There are some more specialized aspects of Asciidoctor markup, which you might need to dig deeper to find in the manual; we list some of them here.

Multi-paragraph footnotes

Metanorma AsciiDoc (and Asciidoctor) supports only single-paragraph footnotes through its footnote macro (which can only contain a single line of text).

This is due to a stylistic bias against digressive text by the Asciidoctor project, and probably will not change.

This can be worked around by introducing line breaks into the macro. See:

Complex notes and admonitions

A note or admonition can be made to span multiple paragraphs (including lists and tables) by making it a delimited block:

[NOTE]
====
This is a multi-paragraph note.

It includes:

* A list

|===
| And

| a table
|===
====

Attribute references

Attribute references can be used as template variables in a document: if your document contains the text {foo}, you can assign the value to be populated in {foo} by setting it as a document attribute in the Metanorma AsciiDoc header: :foo: this is the text to replace "foo".

In the AsciiISO Rice model sample document, document attributes are used to provide the Subcommittee and Technical Committee names, which are populated as template entries in the document foreword.

See also: Document attributes.

List items with complex contents

List items can contain other blocks in Metanorma AsciiDoc through concatenating blocks; for example:

* List
+
|===
| Contains | A table

|===

However, output formatters (such as MS Word) may not be able to cope with embedding blocks within list items.

In particular, Microsoft Word will force a carriage return between a list item, and a list or table contained in the item.

This means the output like follows, with the list number flush with the embedded block, is not possible in Microsoft Word (though it is in HTML):

a)  1. Text
b)  |-------|------ |
    | table | table |
    |---------------|
c)  Definition Term   Definition
    Definition Term   Definition

AsciiDoc escaping

There are some characters that constitute markup in Metanorma AsciiDoc and need to be escaped if they will be used in text (usually by putting a backslash before them).

That applies in particular to:

  • period at the start of a line, which will be interpreted as a block title;

  • open bracket at the start of a line, which will be interpreted as a style attribute;

  • close bracket inside of a macro (such as footnotes), which are themselves delimited by a close bracket;

  • a number followed by period at the start of a line, which will be interpreted as a numbered list. (This does not happen inside of blocks like examples.)

Sometimes, a backslash will not be enough to make the character make sense to Metanorma AsciiDoc markup. The “break in case of emergency solution” is to make the troublesome span of text a document attribute, since document attributes are skipped over when processing Metanorma AsciiDoc markup, and processed only at the very end.

See for example the Asciidoctor User Manual on using document attributes to deal with complex URLs.