Metanorma: Aequitate Verum

Author's documentation

Metanorma AsciiDoc tips

Metanorma AsciiDoc adopts the 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

Native 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.

Metanorma introduces a footnote macro footnoteblock:[id] which allows multi-paragraph notes to be treated as footnotes: see Footnotes.

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 Metanorma ISO 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 character substitutions

Metanorma AsciiDoc inherits the AsciiDoc character substitutions for special characters (<, >, &), and character replacements:

Sequence Replacement Notes

(C)

©

(R)

®

(TM)

™

--

— (em-dash)

Only replaced if between two word characters, between a word character and a line boundary, or flanked by spaces. When flanked by space characters (e.g., a -- b), the normal spaces are replaced by thin spaces (Unicode U+2009 THIN SPACE, HTML &#8201;).

...

…​

->

→

=>

⇒

<-

←

<=

⇐

In addition, Metanorma AsciiDoc by default converts straight single and double quotes into smart quotes. The rules for smart formatting follow the sterile gem, and are given in smart_format_rules.rb.

Metanorma treats - identically to --; this is important particularly in citation of ISO-style titles (so Sterilization of health care products - Radiation is correctly rendered as Sterilization of health care products — Radiation, as can be seen in ISO PDF output.)

There is no equivalent given for en-dash. Metanorma AsciiDoc will recognize any UTF-8 character, and character escapes like &#x2062; and &#8201;.

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.

To prevent the substitution of multiple-character combinations, try interpolating &#x200c; between the characters; so -\&#x200c;- or \&#x200c;- for double or single hyphens, to prevent them being smart-rendered as em-dashes. Character U+200c (the zero width non-joiner) is invisible, and its function is to prevent ligatures combining the characters either side of it.

In cases where an HTTP link is nested into an http macro, like for example:

http://example.com[http://example.com/]

it is necessary to escape the inner http string with a backslash in order to not be recognized as another http macro, like so:

http://example.com[\http://example.com/]

Document attributes

Metanorma AsciiDoc body content is interpolated and processed, such as:

  • inline markup such as boldface and italics;

  • mathematical formatting;

  • footnotes;

  • text substitutions such as smart quotes and -- for em-dash;

  • etc.

Within document attributes, however, the behavior is different.

Typically, all text entered are treated as plain text without processing, as described in AsciiDoc escaping. This means that markup you would normally expect to be processed will be ignored if present in a document attribute.

Metanorma does process smart quotes and -- as em-dash in document attribute text (and in all text except those within source code, pseudocode, and monospace text).

Note
 Document titles, subtitles and authorship information are populated via document attributes and are therefore subject to the same restrictions listed above.