Metanorma: Aequitate Verum

Text formatting

Inline formatting

The following formatting macros are available in Metanorma.

Strikethrough

The strike command renders text with a middle line strikethrough.

The syntax is as follows:

[strike]#text#

Where:

  • text is the text to be rendered with the strikethrough style

Example 1. Illustration of strikethrough text in Metanorma.
[strike]#strike through text#

renders:

Illustration of strikethrough text

Small caps

The smallcap command renders text in small capital letters.

The syntax is as follows:

[smallcap]#text#

Where:

  • text is the text to be rendered in small caps

Example 2. Illustration of small caps text
[smallcap]#small caps text#

renders:

Illustration of small caps text in Metanorma

Underline

The underline command renders text with an underline. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.2].

The syntax is as follows:

[underline]#text#

Where:

  • text is the text to be underlined

Example 3. Illustration of underlined text
[underline]#underline text#

renders:

Illustration of underlined text in Metanorma

CSS declarations

The css command is used to wrap content with a CSS declaration (MDN) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6].

This feature only applies to HTML output.

Note
CSS declarations are also used within the HTML style attribute.

The syntax is as follows:

[css {css-directive}]#{styled-text}#

Where:

  • {css-directive} is a CSS declaration

  • {styled-text} is text where the CSS declaration is to be applied

Example 4. Example of applying a custom CSS declaration to content
[css font-family:"Noto Sans JP"]#お好み焼き#

[css font-family:"Noto Sans Canadian Aboriginal"]#ᓀᐦᐃᔭᐍᐏᐣ#

Identifier

The identifier command, used to indicate that its contents are an identifier as semantic markup (and not to be processed as a hyperlink) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.2].

The syntax is as follows:

identifier:[my-identifier]

Where:

  • my-identifier is the identifier to be encoded.

This functionality is very useful for encoding URIs, which can be virtually indistinguishable from URLs that can be resolved. URIs very often cannot be resolved since they are simply namespaced identifiers.

Example 5. Example of rendering a URI using the identifier command
identifier:[https://schemas.isotc211.org/19115/-1/mdb/1.3]

renders:

https‌://schemas.isotc211.org/19115/-1/mdb/1.3

Example 6. Example of rendering a URN using the identifier command
identifier:[urn:iso:std:iso:8601:-1:en]

renders:

urn:iso:std:iso:8601:-1:en

Semantic spans

The span command is used to introduce semantic markup into Metanorma text [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6].

The syntax is as follows:

span:category[text]

Where:

  • category is a semantic label for the content given as text

  • text is the textual content

Here, the text is tagged as belonging to category.

A semantically-tagged text with span is not normally rendered any different to normal, although the semantic markup introduced can be used to influence rendering.

Note
Only certain Metanorma flavors support enhanced rendering for semantically-tagged content.

Nesting of styles

Character styles can be nested within each other, with both constrained and unconstrained formatting marks.

*Boldmono__space__*
Note
See Asciidoctor Text.

Character substitutions

Metanorma AsciiDoc also recognises HTML and XML character references, and decimal and hexadecimal Unicode code points.

Table 1. Supported Metanorma AsciiDoc character substitutions
Source Rendered as Note

(C)

© (Unicode 'Copyright Sign' U+00A9)

(R)

® (Unicode 'Registered Sign' U+00AE)

(TM)

™ (Unicode 'Trade Mark Sign' U+2122)

-

— (Unicode 'Em Dash' U+2014)

See NOTE below.

...

  1. (Unicode 'Horizontal Ellipsis' U+2026)

->

→ (Unicode 'Rightwards Arrow' U+2192)

=>

⇒ (Unicode 'Rightwards Double Arrow' U+21D2)

<-

← (Unicode 'Leftwards Arrow' U+2190)

<=

⇐ (Unicode 'Leftwards Double Arrow' U+21D0)

'

Smart single quote, smart apostrophe

"

Smart double quote

Note
Replacement of - only occurs when placed between two word characters, between a word character and a line boundary, or flanked by spaces. Flanking spaces (as in x — y) are rendered as thin spaces (Unicode 'Thin Space' U+2009).

Typical links created by the link command require the correct file path that includes the file suffix (e.g. .html for HTML documents).

When linking a Metanorma document to another Metanorma document, which can be rendered into multiple output formats with different suffixes (such as in HTML, PDF or DOC), the option update-type=true can be specified to achieve format-independent links [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4].

When the option update-type=true is given, the rendered link will provide the correct file paths dependent on the output format.

The following conditions must be satisfied to use format-independent links:

  • The link shall be relative and not absolute

  • The link shall not have a file suffix

Example 7. Example of links to other Metanorma documents
link:../parent[update-type=true]
link:../child[This is the child document,update-type=true]

This will render the following links depending on the output format:

  • in HTML, ../parent.html and ../child.html

  • in PDF, ../parent.pdf and ../child.pdf

Numeric ranges

Numeric ranges, like dates (e.g., 1981–1995), make use of en dashes in between the numbers, usually without any white space around.

At the time writing, there is no AsciiDoc encoding to render en dashes.

In Metanorma, there is a vision of implementing a semantic encoding for numeric ranges, perhaps an option like range:[n,m] or shorthands like n..m.

For the time being, the existent workaround for such cases is the use of entity codes, more specifically:

&&#x200c;ndash;
Example 8. Examples of encoding numeric ranges
See chapters 15&ndash;17...

Issues 18&ndash;20 are in fact a single issue...

_Laser Physics_ *17* 1017&ndash;1024 (2007).

renders:

See chapters 15–17…​

Issues 18–20 are in fact a single issue…​

Laser Physics 17 1017–1024 (2007).

Paragraph alignment

Paragraph alignment is defined as the align attribute for paragraphs.

Example 9. Examples of possible paragraph alignments
[align=left]
This paragraph is aligned left

[align=center]
This paragraph is aligned center

[align=right]
This paragraph is aligned right

[align=justified]
This paragraph is justified, which is the default

renders:

Illustration of possible paragraph alignments

If the paragraph contains line breaks, and the default alignment in the stylesheet is justified (as is often the case in Word output), it is necessary to specify [align=left] to make the paragraph look as normally expected.

Example 10. Example of a paragraph containing line breaks that needs to be left-aligned
[align=left]
Vache Equipment +
Fictitious +
World +
mailto:gehf@vacheequipment.fic[]

renders:

Illustration of left-alignment for multiple line-breaks

Page breaks

Page breaks can be given a page orientation, which applies from that point forward until the next page break with a page orientation [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.17].

Page orientation only appears in paged output, such as in Word.

To set content to landscape mode, the syntax is:

[%landscape]
<<<

To set content to portrait mode, the syntax is:

[%portrait]
<<<

If no orientation option is given, the text after the page break remains in the same orientation as that before. In Word, page breaks changing orientation are realised as distinct sections.

In Metanorma, documents are split into three sections by default:

  • a cover page,

  • a preface, and

  • the main document body (including annexes and bibliography)

  • (some documents also have a colophon)

The page orientation is reset at the start of the main document body to portrait.

Example 11. Example of switching from portrait to landscape and back to portrait in the same document
// Content following this directive will be shown in landscape mode
[%landscape]
<<<

...

// Content following this directive will return to portrait mode
[%portrait]
<<<

...

Avoiding page breaks

The “keep with next” feature is useful if you want to indicate that a document element must belong on the same page with another element, on a paginated medium [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1].

Note
“Keep with next” is often considered as the opposite of a forced “page break”, i.e. a “page unbreak”.

Metanorma supports the following boolean attributes for the avoidance of page breaks:

keep-with-next

The block with this attribute specified will be rendered on the same page with the next document element.

keep-lines-together

The block with this attribute specified will force the paragraph to render all its content on the same page.

The syntax is as follows:

[keep-with-next=true]
{Paragraph or block}

and

[keep-lines-together=true]
{Paragraph}

The following syntax indicates that these two paragraphs will always be presented on the same page, even if the textual layout allows them to be split into two pages.

Example 12. Example of using keep-with-next to avoid page breaks
[keep-with-next=true]
This is a paragraph.

This is a paragraph that will be on the same page as the
immediately previous one.

Block quotes

Block quotes are preceded with an author and a citation.

  • The citation is expected to be in the same format as all other citations, which is a cross-reference optionally followed by text.

  • The citation may include the bibliographic sections referenced.

[quote,{attribution},{citation}]
____
{content}
____

Where:

  • {attribution} is the rendered name of the source

  • {citation} is a valid citation reference (citation anchor, optionally followed by locality)

  • {content} is the quotation content

Example 13. Example of a block quote, quoting a section from an ISO deliverable
[quote, ISO, "ISO7301,section=1"]
_____
This International Standard gives the minimum specifications for rice
(_Oryza sativa_ L.) which is subject to international trade. It is applicable to
the following types: husked rice and milled rice, parboiled or not, intended for
direct human consumption. It is neither applicable to other products derived
from rice, nor to waxy rice (glutinous rice).
_____

renders as

Illustration of a block quote in Metanorma

Notes

Folding notes

Notes that are not at the end of a clause are folded into the preceding block, if that block is not delimited (so that the user could not choose to include or exclude a note). That is, notes are folded into a preceding list, formula, figure, or table.

Prevent notes from folding

To prevent a note from folding into the preceding block, add the attribute keep-separate to the note [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.29].

Note
Extended to apply to tables [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6].
* A
* B
* C

[NOTE,keep-separate=true]
====
Note not folded into its preceding block
====

Without the keep-separate=true markup, the note would be attached to the list, and numbered accordingly.

[NOTE]
This note will be folded in the preceding block.

NOTE: This one too.

Notes may be given a type through the attribute type [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1].

[NOTE,type=bibliographic]
====
Bibliographic note
====

Explicitly-defined terminology entry notes

Normally, notes are only tagged as term notes when they appear in the context of a terms section.

Rarely, term notes need to be presented in isolation, including in ISO Amendments or Technical Corrigenda.

To achieve that, mark the note up with %termnote [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.2].

[NOTE%termnote]
====
Bibliographic note
====

Examples

Explicitly-defined terminology examples

Normally, examples are only tagged as term examples when they appear in the context of a terms section.

Rarely, term notes need to be presented in isolation, including in ISO Amendments or Technical Corrigenda.

To achieve that, mark the example up with %termexample [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.2].

[%termexample]
====
Bibliographic note
====

Admonitions

General

Admonitions (“NOTE”, “IMPORTANT”, “WARNING”, “CAUTION” etc.) are typically inserted into the main content of a document providing guidance or request readers to exercise caution.

== General requirements

[NOTE]
====
This is just a note providing guidance.
====

[IMPORTANT]
====
This is an important message.
====

== Safety requirements

[WARNING]
====
This important notice applies to safety concerns.
====

[CAUTION]
====
This notice must not be ignored.
====

Whole document admonitions

Admonitions (“NOTE”, “IMPORTANT”, “WARNING”, “CAUTION” etc.) in the document body (i.e. within a main body clause) can be stated to apply to the entire document by moving them to the start of the document body, before the main sequence of clauses.

This can be done by giving them the attribute beforeclauses=true [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.30].

== Scope

[IMPORTANT,beforeclauses=true]
====
This important notice applies to the entire document.
====

My scope text...

Preface admonitions

Admonitions in the document prefaces (including in the Foreword) can be stated to apply to the entire preface by moving them to the start of the preface, before the Foreword. This can be done by giving them the same attribute beforeclauses=true [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.2].

= Document title
:document-attribute: XXXX

[IMPORTANT,beforeclauses=true]
====
This important notice applies to the entire document.
====

== Foreword

My foreword text...

Cover page admonitions

An admonition in the document prefaces can instead be flagged to be rendered on the cover page of the document, through coverpage=true [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.8].

= Document title
:document-attribute: XXXX

[IMPORTANT,coverpage=true]
====
This important notice appears on the cover page.
====

== Foreword

My foreword text...

Normally, the label of the type of admonition (NOTE, IMPORTANT, etc) is inserted at the start of the admonition in rendering. This may not be desirable, especially for coverpage admonitions.

Inserting the admonition type is suppressed through notag=true [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.8].

= Document title
:document-attribute: XXXX

[IMPORTANT,coverpage=true,notag=true]
====
This important notice appears on the cover page.
====

== Foreword

My foreword text...

Footnotes

Table and figure footnotes are treated differently from all other footnotes: they are rendered at the bottom of the table or figure, and they are numbered separately.

When the text of a footnote is repeated in two different places, default behaviour in Metanorma, both for HTML and for DOC, is to use the same footnote number in both places, rather than treat the repetition as a new footnote.

Footnotes on document titles are recognised [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1], but by default they are not rendered, because of how document title pages are processed separately in Metanorma via Liquid templates. Document title footnotes are moved into /bibdata/note[@type = "title-footnote"], and are treated as document metadata, as are document titles themselves. The location of the footnote within the title is not preserved.

Multi-paragraph footnotes can be entered using the macro footnoteblock:[id] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.4], where id is the identifier of a note containing the contents of the footnote:

This is a paragraph.footnoteblock:[id] This continues the paragraph.

[[id]]
[NOTE]
--
This is

a multi-paragraph

footnote
--
Note
Multi-paragraph footnotes are a Metanorma AsciiDoc feature and not supported in typical AsciiDoc.

Lists

Ordered lists

Ordered list labels conform to rules specified in ISO/IEC DIR 2 throughout Metanorma:

  • level 1: a), b), c) (called alphabetic),

  • level 2: 1), 2), 3) (called arabic),

  • level 3: i), ii), iii) (called roman),

  • level 4: A), B), C) (called alphabetic_upper),

  • level 5: I), II), III) (called roman_upper).

Note
This labeling applies to all output formats, including PDF, HTML and Word.

In certain flavours (NIST, ITU, OGC), class=steps is used to override this numbering, and use Arabic numbering as the base instead:

  • level 1: 1), 2), 3)

  • level 2: a), b), c)

  • level 3: i), ii), iii)

  • level 4: A), B), C)

  • level 5: I), II), III)

The start attribute for ordered lists is only allowed by certain Metanorma flavors, such as BIPM and ISO. This is because of the difficulty of realising the list numbering starting other than at 1 in autonumbered lists in Word HTML.

Note

This note applies to isodoc v1.3.0 to v2.0.2.

The type attribute, with acceptable values listed in the list above, could be used to allow specifying labels of an ordered list [added in https://github.com/metanorma/isodoc/releases/tag/v1.3.0].

In Word rendering the type attribute is always ignored in favor of ISO/IEC DIR 2 compliant labelling.

As of v2.0.3, the ability to specify the type attribute has been retracted [added in https://github.com/metanorma/isodoc/releases/tag/v2.0.3], because of the bugs it introduces with list cross-referencing and rendering.

List items with more than one paragraph

Metanorma XML and HTML support multiple paragraphs within a single list item (see list continuation).

Note
In HTML output, all the paragraphs within a list item will be aligned.
Note
Microsoft Word caveats
  • For list items containing multiple paragraphs, Metanorma attempts to format them appropriately by using custom list continuation styles (ListContLevel1 etc.) applied to groups of paragraphs; however, you should check the output document and may need to manually intervene.

  • In Microsoft Word, each list entry must be a single paragraph. Metanorma is employing a workaround through list continuation styles, and results may be unexpected if the list is edited.

Definition lists

Definition lists are rendered by default horizontally, with the definition in the same line as the term. In Word, definition lists are rendered as true tables, and the width of the term column is determined by the Word auto-width algorithm; if you need to ensure that terms are rendered in a single line in Word, you may need to use non-breaking spaces and non-breaking hyphens (which can be entered in AsciiDoc as HTML escapes: &nbsp; or &#xa0;, and &#x2011;, respectively; e.g. This&nbsp;is&nbsp;a&nbsp;non&#x2011;breaking&nbsp;term instead of This is a non-breaking term.)

Tables

Metanorma AsciiDoc tables are required to handle the full range of complexity of standardization documents, and is therefore significantly more powerful than typical AsciiDoc tables, even when typical AsciiDoc already handles tables very well for a non-XML markup language.

Metanorma AsciiDoc already supports cells spanning multiple rows and columns, horizontal alignment, and [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.3] vertical alignment.

Metanorma AsciiDoc adds the option of multiple header rows via attribute headerrows to deal with the complexity of standardization documents' tables requiring labels, variables, and units to lining up in the header.

Tables can also have alternate text as a title, alt, and summary text, summary, both of which are to be rendered as a summary of the table for accessibility.

Tables can be set with a width attribute, which could be either a percentage (e.g. 70%) or a pixel count (e.g. 500px). [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.21].

Note
The width attribute value aligns with HTML CSS and HTML 4 behavior.
[headerrows=2,alt=Table of maximum mass fraction of defects in husked rice,summary=Table enumerating the permissible mass fraction of defects in husked and various classes of milled rice,width=70%]
|===
.2+|Defect 4+^| Maximum permissible mass fraction of defects in husked rice +
stem:[w_max]
| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice

| Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] | 1,0 | 0,5 | 1,0 | 0,5

|===

which renders:

Illustration of a table in Metanorma (DOC output). Configuration: 70% of width
Figure 1. Illustration of a table in Metanorma (DOC output). Configuration: 70% of width, two header rows, one normal row, one footnote.

In Metanorma AsciiDoc:

  • table cell footnotes are rendered inside the table;

  • notes following the table are rendered inside the table footer.

Note
Typical AsciiDoc renders table cell footnotes inside the cell, and notes trailing the table outside the table.
Tip

Table 1 in the Metanorma ISO Rice example document illustrates a large range of table formatting options.

Table columns can also have their widths set [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.3]. Table column widths must be enumerated explicitly per column to generate column widths.

Example 14. Example of table with equal width columns

The following syntax will be processed as generating equal width columns.

[cols="1,1,1"]
Note
In typical AsciiDoc, [cols="3"] is considered a shorthand to [cols="1,1,1"], but this is not supported in Metanorma AsciiDoc.

Mathematical expressions

General

Metanorma AsciiDoc accepts mathematical input in these formats:

  • AsciiMath

  • LaTeX math

  • MathML

Math can be entered using one of the following mechanisms:

  • the stem:[…​], asciimath:[…​] and the latexmath:[…​] commands; and

  • the [stem], [asciimath], [latexmath] blocks delimited with ++++

The math syntax used by stem:[…​] and [stem] blocks depends on the value of the document attribute :stem:. It can be set to:

:stem: latexmath

any markup within stem is interpreted as LaTeX math

:stem: asciimath

any markup within stem is interpreted as AsciiMath

:stem:

(default) when left empty, AsciiMath is selected

stem:[…​] and [stem] markup that contains MathML markup (as detected by an initial <math …​ >) is interpreted as MathML.

MathML is used as the internal representation of STEM expressions in Metanorma.

Using AsciiMath

AsciiMath can be entered using the asciimath:[…​] command and the [asciimath] block delimited with ++++. The stem:[] and [stem] blocks can also be used if the document attribute :stem: asciimath has been specified in the document.

AsciiMath is converted into MathML using the asciimath gem.

The syntax of AsciiMath recognised by the asciimath gem is more strict than the common MathJax processor of AsciiMath.

For example, asciimath insists on numerators being bracketed.

Example 15. Usage of AsciiMath in IEV (IEV 103-01-03)
The derivative of a distribution stem:[D] is another distribution
stem:[D'] defined for any function stem:[f](stem:[x]) by
stem:[D^( ' ) ( f ) = - D ( d f // d x )].
Example 16. Usage of AsciiMath in ISO 10303-55 (ISO 10303-55, Clause 2)
[stem]
++++
f -= lambda x (a * x + b)
++++
Warning
Some math expressions are NOT supported by AsciiMath. In that case it is necessary to use LaTeX math or MathML input.

Using LaTeX math

LaTeX math can be entered using the latexmath:[…​] command and the [latexmath] block delimited with ++++. The stem:[] and [stem] blocks can also be used if the document attribute :stem: latexmath has been specified in the document.

LaTeX math is converted into MathML using the latexmath gem, which generates output compliant with the deterministic output of the NIST LaTeXML suite.

Note
LaTeX math parsing of the LaTeXML’s latexmlmath command is deterministically accurate. The latexmath gem was created to generate identical output to the latexmlmath command.

Unicode characters in the LaTeX source are translated into LaTeX escapes through the unicode2latex gem.

Example 17. Example of using LaTeX Math in ISO 10303-110 (ISO 10303-110, Clause 4)
The only change from the above example would be the
nondimensionalization of viscosity, which would become,
latexmath:[\tilde{\tilde{\mu}} = mu / (rho_infty c_infty L)].
Example 18. Another example of using LaTeX Math in ISO 10303-110 (ISO 10303-110, Clause 4)
[latexmath]
++++
\begin{array}{c@{\qquad}c@{\qquad}c}
  \tilde{x} = x/L, \tilde{u} = u/c_\infty, \tilde{\rho} = \rho/\rho_\infty,
  \tilde{y} = y/L, \tilde{v} = v/c_\infty, \tilde{p} = p/(\rho_\infty c_\infty^2),
  \tilde{z} = z/L, \tilde{w} = w/c_\infty, \tilde{\mu} = \mu/\mu_\infty,
\end{array}
++++

The LaTeX math eqnarray environment is not supported in Metanorma as it is not supported by LaTeXML and the latexmath gem. It is also not recommended by the general LaTeX community due to inconsistencies in vertical alignment and other aspects (see Madsen).

The proper LaTeX math syntax used to replace existing eqnarray equations is to place the equations in separate blocks concatenated with +.

Example 19. Replacing LaTeX math eqnarray in Metanorma with separate equations

These equations using the eqnarray environment:

[latexmath]
++++
\begin{eqnarray*}
  \bf{z^\prime} & = & \bf{\zeta} \\
  \bf{x^\prime} & = & \langle \bf{\eta} \times \bf{\zeta} \rangle
\end{eqnarray*}
++++

should be re-arranged as:

[latexmath]
++++
\bf{z^\prime} = \bf{\zeta}
++++
+
[latexmath]
++++
\bf{x^\prime} = \langle \bf{\eta} \times \bf{\zeta} \rangle
++++

Formulae

General

Formulae are marked up as [stem] blocks.

Equations

In most flavours, equations and inequalities are both referenced in the same way, as “Formula”.

In some flavours (e.g. ITU), they are referenced differently as “Equations” and “Inequalities”.

Inequalities

Inequalities are indicated through the option attribute %inequality:

[stem%inequality]
++++
{formula-content}
++++

Where:

  • {formula-content} is content within a formula.

Example 20. Example of encoding an inequality formula
[stem%inequality]
++++
A < B
++++

renders as:

Example of a block stem inequality in Metanorma

Key

Explanation of symbols used in the formula is specified in a "key" list, which is specified as a definition list with the [%key] option [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.3].

The syntax is as follows:

[stem]
s++++
{some-formula}
++++

[%key]
stem:[{some-symbol}]:: {symbol-description}

Where:

  • {some-formula} represents content within a formula

  • {some-symbol} represents a symbol within the formula

  • {symbol-description} is text that describes information about the symbol

Example 21. Example of including a key for a formula (stem) block
[stem]
++++
w = (m_D) / (m_s)
++++

[%key]
stem:[w]:: is the mass fraction of grains with a particular defect in the test sample;
stem:[m_D]:: is the mass, in grams, of grains with that defect;
stem:[m_S]:: is the mass, in grams, of the test sample.

renders as:

Example of a block stem equation in Metanorma

Instead of [%key], the definition list can also be preceded with a paragraph containing the English word where, though this is not recommended practice.

Example 22. Example of including a key for a formula (stem) block using the where keyword
[stem]
++++
w = (m_D) / (m_s)
++++

where

stem:[w]:: is the mass fraction of grains with a particular defect in the test sample;
stem:[m_D]:: is the mass, in grams, of grains with that defect;
stem:[m_S]:: is the mass, in grams, of the test sample.

Figures

Key

Like formulae, figures can be followed by a definition list for the variables used in the figure. This definition list is marked up with [%key] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.3].

The syntax is as follows:

.Figure title
image::figure-path.png[]

[%key]
{some-id}:: {some-description}

Where:

  • .Figure title represents the intended title of the figure

  • figure-path.png is an example for an image path

  • {some-id} represents a reference within the figure

  • {some-description} is text that describes information about the thing represented by {some-id}

Example 23. Example of providing a key for a figure (ISO Rice document)
.Typical gelatinization curve
image::rice_images/rice_image2.png[]
footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]

[%key]
stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent
stem:[t]:: cooking time, expressed in minutes
stem:[t_90]:: time required to gelatinize 90 % of the kernels
P:: point of the curve corresponding to a cooking time of stem:[t_90]

NOTE: These results are based on a study carried out on three different types of kernel.

The key definition list can also be preceded by a paragraph consisting of *Key*, though that is not recommended.

Example 24. Example of providing a key for a figure using the *Key* syntax (ISO Rice document)
.Typical gelatinization curve
image::rice_images/rice_image2.png[alt text]
footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]

*Key*

stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent
stem:[t]:: cooking time, expressed in minutes
stem:[t_90]:: time required to gelatinize 90 % of the kernels
P:: point of the curve corresponding to a cooking time of stem:[t_90]

NOTE: These results are based on a study carried out on three different types of kernel.

Data URLs as images

Metanorma allows Data URLs as the URL for an image:

image::data:image/png;base64,ivBO[alt text]
Note
Data URLs are not typically supported by AsciiDoc processors.

Discursive figures

A discursive figure, containing text as well as images, can be marked up as an example, with a [.figure] role [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.7]:

[.figure]
.Typical gelatinization curve
====
image::rice_images/rice_image2.png[alt text]

This is lots of discursive text
====

Subfigures

Subfigures (which appear in ISO formats, for example) are entered by including images in an example block.

.Stages of gelatinization
====
.Initial stages: No grains are fully gelatinized (ungelatinized starch granules are visible inside the kernels)
image::rice_images/rice_image3_1.png[]

.Intermediate stages: Some fully gelatinized kernels are visible
image::rice_images/rice_image3_2.png[]

.Final stages: All kernels are fully gelatinized
image::rice_images/rice_image3_3.png[]
====

Image size

The size of an image can be modified via the height and width attributes.

By default, both height and width are set to the value auto, which means that the image will be shown according to the best visual settings determined by Metanorma.

Image dimensions can also be fixed with pixel values with px.

Note
The pixel is the only supported unit in image sizing right now.
Image resizing specifying height and width attributes in pixels
[height=150px,width=100px]
image::logo.jpg[]

In the height and width attributes, the px suffix may be omitted.

Image resizing with values omitting px unit
[height=150,width=100]
image::logo.jpg[]

The auto value indicates that the dimension does not have a fixed size but retain the aspect ratio of the original image.

Aspect ratio is retained with width set to auto based on the value of height
[height=150,width=auto]
image::logo.jpg[]

An unspecified dimension is considered auto.

Aspect ratio is retained when setting height but not width
[height=150]
image::logo.jpg[]
Note
Treatment of image resizing may slightly differ across output formats.

Captions and titles

As elsewhere in Metanorma, the caption of an image (of the figure containing the image) is set with a line prefixed with dot above the image.

.Caption
image::logo.jpg[]
image::logo.jpg[title=Caption]
Note
Similar to Asciidoctor AsciiDoc, the title attribute is treated as identical to the dot-prefixed caption.

Metanorma supports a title attribute on images for accessibility, which is distinct from the figure caption. This is entered in Metanorma as the titleattr attribute:

[titleattr=Title Attribute]
image::logo.jpg

Or

image::logo.jpg[titleattr=Title Attribute]

Both captions and titles could be used together.

.Rice husk separation in rice farm at Breton near Dinan
image::logo.jpg[titleattr=Photo of rice husks being separated]
Note
The titleattr attribute does not get rendered in Word output due to Word limitations. Word only supports a single image “Alt Text”, which would be set by the caption. Word’s description of “Alt Text” is: “How would you describe this object and its context to someone who is blind?”.

Preformatted blocks

Figures can include preformatted blocks, as well as images.

For accessibility, preformatted blocks can be provided with an alt text attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10].

     ___^_
   /    | \__/\
    \   /  ^ ^|
   / \_/   0  0_
  /             \
 /     ___     0 |
/      /  \___ _/

Figure classes

Figures in documents can belong to different classes (e.g. Plate, Chart, Diagram), each of which can be auto-numbered and captioned differently. In order to achieve this, the desired class can be indicated through the class attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.5].

[class=plate]
.Rice husk separation in rice farm at Breton near Dinan
image::logo.jpg[]

Passthrough to Metanorma XML and target formats

Passthrough blocks

Passthrough text, such as XML tags, intended to be rendered in a target format unaltered, can be entered as a passthrough block [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.27].

This functionality enables automated processing, custom tagging, hacking into intermediary formats and experimental development of Metanorma output.

Warning
A broken Metanorma XML file will cause rendering of target formats to also break. Use with caution.

Passthrough intended to be rendered in Metanorma XML (such as Metanorma XML tags), generated from Metanorma AsciiDoc input, can be entered as a passthrough block [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1], with no format indication.

Example 25. Using passthrough XML tags in the Metanorma XML target
++++
<bibitem>
++++
Warning
Passthrough text may break the structure of the output format — it is the user’s responsibility to ensure the integrity of the resulting structure (e.g. XML) is retained.

Passthrough intended to be rendered in a target format must be specified with a format indication corresponding to one or more of the existing output formats of Metanorma in a comma-delimited manner (not limited to: html, doc, pdf, rfc, sts).

Example 26. Using passthrough XML tags in the RFC XML target
[format=rfc]
++++
<artset>
<artwork>
++++

Passthrough inline text

Metanorma AsciiDoc supports the following syntaxes for inline passthrough.

Passthrough of text that does not involve XML structural syntax can be realized in any of the following syntaxes:

// syntax 1
+this is passed through+

// syntax 2
+++this is passed through too+++

// syntax 3
pass:[also passed-through]
Example 27. Example of specifying passthrough text
This is a special pass:[𝒞𝓪𝓼𝓮].

For passthrough of XML syntax or tags to Metanorma XML, which will require special character processing, use the following command:

pass:c[xml-content]

Where:

  • xml-content is content that contains XML or SGML tags

Example 28. Example of specifying passthrough XML content
pass:c[<u format="num-lit">ᏚᎢᎵᎬᎢᎬᏒ</u>]

If the passthrough text is intended for one or more target formats, the formats needs to be specified with the pass-format command [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.7].

pass-format:FORMAT[...]

Where:

  • FORMAT is a comma-delimited list of target formats.

Example 29. Example of specifying passthrough for selected target formats
pass-format:rfc[<u format="num-lit">ᏚᎢᎵᎬᎢᎬᏒ</u>]

Source code

General

Source code is marked up as elsewhere in AsciiDoc, as a pre-formatted source snippet to be rendered in monospace font, and with spaces preserved.

The syntax is as follows:

[source]
----
Rendered in monospace text
----
Example 30. Example of rendering source code without language specification
[source]
----
Identifier(latitude, longitude, elevation, elevationType)

  return concat(
    "ISO.NLI",
    EncodePoint(latitude, longitude),
    EncodeElevation(elevation, elevationType)
  )
----

It is possible to specify the computer language used in the [source] block to enable source code highlighting (syntax highlighting) for supported languages.

Metanorma integrates the CodeRay syntax highlighter which supports the following list of languages represented by codes:

  • c

  • clojure

  • css

  • delphi

  • diff

  • erb

  • go

  • groovy

  • haml

  • html

  • java

  • java_script

  • json

  • lua

  • php

  • python

  • raydebug

  • ruby

  • sass

  • sql

  • taskpaper

  • xml

  • yaml

Note
The full list of supported file extensions is provided by CodeRay).
[source,language]
----
Rendered in monospace with syntax highlighting
----
Example 31. Example of rendering source code with language specification and syntax highlighting
[source,ruby]
----
class MyIdentifier
  def format(string)
    "did:#{string}"
  end
end
----

Markup in source code blocks

It is sometimes necessary to introduce markup into source code. For example, hyperlinking words in source code to external definitions, or else introducing formatting in lieu of automated highlighting.

In order to achieve this, Metanorma allows inline AsciiDoc markup to be introduced into source code, isolating it from the rest of the source code through delimiters. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4]

By default, the delimiters are {{{ and }}}. These can be overridden (in case {{{ and }}} are already used in the document) through the document attributes :sourcecode-markup-start: and sourcecode-markup-end:.

Example 32. Example of applying inline formatting to source code blocks
[source,ruby]
--
{{{*def*}}} method1(x)
  {{{<<method2-definition,method2>>}}}(x) + 3
end
--

renders as:

def method1(x)
    method2(x) + 3
end

Pseudocode

Pseudocode is a mix between formal math with code like properties commonly used in computer science and related fields.

Unlike source code, pseudocode is typically in a proportional font, but it still needs to be indented to reflect code structure. Moreover, pseudocode typically requires source code highlighting such as boldface; but unlike well-defined computer languages, there is no guaranteed way of automating such highlighting.

Pseudocode is supported in Metanorma using the pseudocode block with these properties:

  • text within a pseudocode block is treated as normal text, including respect for inline formatting;

  • lines do not need to be separated by line breaks, although two carriage returns in a row are still interpreted as a new paragraph. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10]

  • indentation spaces at the start of each line are preserved, by converting them into non-breaking spaces; initial tabs are converted into four non-breaking spaces.

The syntax is as follows:

[pseudocode]
====
normal text
  stem:[math]
    _italics_ [smallcap]#small caps text#
*bolded text*
====
Example 33. Example of using the pseudocode block with flow operators
[pseudocode]
====
*do in-parallel*
  [smallcap]#SharedAccess#
*enddo*

[smallcap]#ExclusiveAccess# stem:[-=]
  *if* _ag.mode_ = _exclusive_ stem:[^^ AA t in] [smallcap]#Token# : _t.available_ *then*
    *do forall* _t_ : stem:[in]  [smallcap]#_Token_#
      _t.owner_ := _ag_
    *enddo*
  *endif*
====
Example 34. Example of using the pseudocode block with numeric values (from ISO 8000-118)
[pseudocode]
====
EncodeGroundLevel(_groundLevel_)

  *if not* stem:[-19652 <= "_groundLevel_" <= 19651]
    *raise* _out of bounds error_
  *endif*

  _groundLevel_ = _groundLevel_ + 19652

  *return* [smallcap]#EncodeBase34#(_groundLevel_)
====

renders as (PDF):

Pseudocode usage in ISO 8000-118

Filenames for extraction

Images, source code, and requirements can all be extracted out of the generated Metanorma XML downstream, by the metanorma -e command.

By default, the filename for each extracted snippet is automatically generated. (Extraction only applies to data-uri encoded images, which no longer preserve their filename.)

The attribute filename on images, source code, and requirements gives the filename that any inline-encoded images, source code, and requirements should be exported to, if that is requested by downstream tools.

[filename="image1.gif"]
image::logo.gif

In this instance, the image is read in from logo.gif, but is converted in the XML output to a data-uri encoding. The encoding will have the filename attribute of image1.gif; that instructs any downstream processing that extracts images out of the file (such as metanorma -e) to extract this image to the file image1.gif, instead of using an automatically generated filename.

Auto-numbering

General

The following document elements (“elements”) are auto-numbered by Metanorma, so users do not need to specify any numbering in their source documents:

  • figures

  • tables

  • examples

  • notes

  • formulas

  • sourcecode, pseudocode

  • permissions, recommendations and requirements.

The conventions for numbering vary by Metanorma flavour, but the default is to number all elements consecutively in the main body of a document, and separately in each Annex/Appendix, prefixed bt the Annex/Appendix number.

Multi-level numbering

Metanorma’s auto-numbering functionality assigns numbers to elements consecutively. Sometimes, more than one level of numbering is required for a sequence of elements; for instance, 17a, 17b.

To indicate that, all elements in the subsequence should be assigned the same subsequence attribute of an autonumbered document element.

The syntax is as follows:

[{block-type},subsequence={subsequence-id}]

Where:

  • {block-type} is type of the document block

  • {subsequence-id} is the subsequence identifier

Example 35. Example of using multiple subsequences for auto-numbering
[stem,subsequence=A]
++++
A
++++

[stem,subsequence=A]
++++
B
++++

[stem,subsequence=B]
++++
C
++++

[stem,subsequence=B]
++++
D
++++

[stem]
++++
E
++++

renders as:

A (1a)

B (1b)

C (2a)

D (2b)

E (3)

Unnumbered elements

Sometimes a document element needs to be excluded from auto-numbering. This is achieved by giving it the option attribute %unnumbered.

Sourcecode and pseudocode snippets are by default numbered as figures [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.10]. If they are not to be numbered, they need to be given the %unnumbered option attribute.

The syntax is as follows:

// shorthand
[%unnumbered]
image::...[]

// with other options
[options="unnumbered"]
image::...[]

// block type with shorthand
[{block-type}%unnumbered]
image::...[]

// block type with other options
[{block-type},options="unnumbered"]
image::...[]

Where:

  • {block-type} is type of the document block;

  • The % symbol is a shorthand for options="unnumbered".

Note
The % shorthand cannot be used in the presence of block arguments or attributes, such as [source,c] or [source,type="…​"]. In this case, the options="unnumbered" should be spelled out.
Example 36. Example of an unnumbered figure
[[figureC-1]]
[%unnumbered]
.Typical gelatinization curve
image::rice_images/rice_image2.png[]
Example 37. Example of an unnumbered source block

Both of these blocks are identical.

[source%unnumbered]
----
for (i = 0; i < n; i++) { bounce(v[i], wall) }
----
[source,options="unnumbered"]
----
for (i = 0; i < n; i++) { bounce(v[i], wall) }
----
Example 38. Example of an unnumbered source block with syntax highlighting (from RNP)
[source,cpp,options="unnumbered"]
----
/* print a usage message */
static void
print_usage(const char *usagemsg)
{
  cli_rnp_print_praise();
  ERR_MSG("%s", usagemsg);
}
----
Example 39. Example of an unnumbered pseudocode block
[%unnumbered]
[pseudocode]
----
stem:[forall v_{i}] *bounce* stem:[v_{i}] off the wall
----

Prevention of double-numbering

If a document element is included in a block type that is already subject to numbering, it will be excluded from auto-numbering.

This means that tables, sourcecode and pseudocode, and figures are excluded from auto-numbering within examples, requirements, recommendations, permissions, tables, figures, sourcecode and pseudocode. [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.11]

Override numbering

There are circumstances when auto-numbering of elements needs to be overriden; for instance, numbering out of sequence in updated documents.

In these cases, elements can be given an optional number attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1], assigning a required document element number to override auto-numbering.

Elements subsequent to that element will be auto-numbered so as to follow the previous element, so long as the supplied number belongs to the same sequence.

For subsequences, number shall have only subsequence scope.

The syntax is as follows:

[{block-type},number={number-to-use}]

Where:

  • {block-type} is type of the document block

  • {number-to-use} is an integer specifying at which number to use

Example 40. Example of manually specifying numbering of a document block
[source,number=7]
----
for (i = 0; i < n; i++) { bounce(v[i], wall) }
----