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.
Native Asciidoctor supports only single-paragraph
footnotes through its
(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 |=== ====
can be used as template variables in a document:
if your document contains the text
you can assign the value to be populated in
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
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.,
- 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
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
‌ between the characters; so
\‌- 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.
Metanorma AsciiDoc body content is interpolated and processed, such as:
inline markup such as boldface and italics;
text substitutions such as smart quotes and
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).
|Document titles, subtitles and authorship information are populated via document attributes and are therefore subject to the same restrictions listed above.|