Text formatting

Strikethrough and small caps

The following formatting macros are used for strikethrough and small caps text:

[strike]#strike through text#
[smallcap]#small caps text#

which renders:

Figure 1. Illustration of strikethrough and small caps text in Metanorma.

Paragraph alignment

Paragraph alignment is defined as an attribute for paragraphs:

[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

which renders

Figure 2. Illustration of possible paragraph alignments in Metanorma.

If you have line-breaks in a paragraph, and the default alignment in the stylesheet is justified (as is often the case in Word output), you will need to set [align=left] to make the paragraph look as normally expected:

[align=left]
Vache Equipment +
Fictitious +
World +
mailto:gehf@vacheequipment.fic[]

which renders

Figure 3. Illustration of left-alignment for multiple line-breaks in Metanorma.

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:

// Content following this directive will be shown in landscape mode
[%landscape]
<<<

...

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

...

Block quotes

As in normal AsciiDoc, block quotes are preceded with an author and a citation; but the citation is expected to be in the same format as all other citations, a cross-reference optionally followed by text, which may include the bibliographic sections referenced:

[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

Figure 4. Illustration of a block quote in Metanorma.

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, or figure.

To prevent that behaviour, add the attribute keep-separate to the note [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.29].

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

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.

Index Terms

Metanorma supports index entries with primary, secondary and tertiary index terms; however these are currently only rendered in the IETF flavour, and do not appear otherwise in DOC, PDF or HTML output [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10].

The Lady of the Lake, her arm clad in the purest shimmering samite,
held aloft Excalibur from the bosom of the water,
signifying by divine providence that I, ((Arthur)),
was to carry Excalibur (((Sword, Broadsword, Excalibur))).

Lists

Ordered Lists

Ordered lists in both HTML and Word have their labels pre-configured to align with ISO/IEC DIR 2:

a), b), c) for the first level,
then 1), 2), 3) for the second level,
then i), ii), iii),
then A), B), C),
then I), II), III).

Note	Metanorma AsciiDoc ignores the `type` attribute for ordered lists used in Asciidoctor AsciiDoc, which allows the user to specify the label of an ordered list.

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

MS 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 MS 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 autowidth 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: or , and ‑, respectively;, e.g. This is&nsbp;a non‑breaking 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 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 finally have a width attribute, which following HTML CSS and HTML 4 can set the width of a table to 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].

[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

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

Typical AsciiDoc allows table cells to have footnotes (which Metanorma renders inside the table) and notes following the table (which Metanorma moves inside the table footer).

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

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:

(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 )].

(ISO 10303-55, Clause 2)

[stem]
++++
f -= lambda x (a * x + b)
++++

Note	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 LaTeXML processor.

Metanorma relies on LaTeXML’s latexmlmath command for LaTeX math parsing as it is deterministically accurate, even though some complains of it being slower than other (non-deterministic) LaTeX to MathML converters.

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

EXAMPLE:

(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)].

(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. 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:

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

Formulae are marked up as [stem] blocks. Any explanation of symbols in the formula is given as a “where” paragraph, followed by a definition list.

For example:

[[formulaA-1]]
[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.

which renders

Figure 6. Example of a block stem equation in Metanorma.

Inequalities are indicated through the option attribute %inequality:

[stem%inequality]
++++
A < B
++++

which renders

Figure 7. Example of a block stem inequation in Metanorma.

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

Figures

Like formulae, figures can be followed by a definition list for the variables used in the figure; the definition list is preceded by *Key*. For example:

[[figureC-1]]
.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.

As an extension to AsciiDoc syntax, Metanorma allows Data URLs as the URL for an image:

image::data:image/png;base64,ivBO[alt text]

Subfigures

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

[[figureC-2]]
.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 value auto is accepted for image width and height attributes. It is only passed on to HTML output; if the output is to Word, both the width and height attributes are stripped from the image.

[height=90,width=auto]
image::logo.jpg

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

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 |
/      /  \___ _/

Source code

Source code is marked up as elsewhere in AsciiDoc, as a preformatted source snippet to be rendered in monospace font, and with spaces preserved:

[source,ruby]
----
  def increment(x)
    x + 1
  end
----

Source code highlighting can be used automatically to highlight keywords specific to the nominated computer language.

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 as a special class of example, marked up with a pseudocode block macro with these differences:

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.

[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*
====

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 (“assets”) are auto-numbered by Metanorma, so users do not need to specify any numbering in their source documents:

figures
tables
examples
formulas
sourcecode, pseudocode
permissions, recommendations and requirements.

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

Multi-level numbering

Auto-numbering numbers assets consecutively. Some times, more than one level of numbering is required for a sequence of assets; e.g. 17a, 17b. To indicate that, all assets in the subsequence are assigned the same subsequence attribute:

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

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

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

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

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

Gets rendered as:

A (1a)

B (1b)

C (2a)

D (2b)

E (3)

Unnumbered elements

Sometimes an asset needs to be excluded from auto-numbering. This is achieved by giving it the option attribute %unnumbered:

[[figureC-1]]
[%unnumbered]
.Typical gelatinization curve
image::rice_images/rice_image2.png[]

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.

[sourcecode%unnumbered]
----
for (i = 0; i < n; i++) { bounce(v[i], wall) }
----

// This is also unnumbered
[%unnumbered]
[pseudocode]
----
stem:[forall v_{i}] *bounce* stem:[v_{i}] off the wall
----

Prevention of double-numbering

If an asset 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]

Cross-references

Cross-references are realised in Metanorma AsciiDoc by assigning an anchor to the block to be referenced, and writing a cross-reference containing that anchor ID:

[[anchor-id]]
== Target clause

The requirements are...

== Reference clause

As seen in <<anchor-id>>...

The anchor ID must follow the NCName constraints of xml:id:

it must start with with a letter, an underscore, or a colon.

The guidance given in ISO/IEC DIR 2 for internal cross-references guarantees unambiguous referencing and is followed rigorously by Metanorma.

In particular, if a formula, example, figure, list, list item or table is cross-referenced outside its (sub)clause, the clause containing the item is always given in the cross-reference, unless the item is being referenced in the same clause.

In the case of notes, the containing clause is extended to containing example, figure or table.

Note

For example, in the AsciiISO Rice model sample document formula B.1 is defined in Annex B.6, and is referenced in B.6 and B.7.

In the Rice model document published by ISO, both instances are cited as "Formula (B.1)". However, Metanorma follows ISO/IEC DIR 2 in citing the former as "Formula (B.1)", but the latter as "B.6, Formula (B.1)".

In this sense, Metanorma is "more royalist than the king" in applying formatting rules and validation—which is what you would want of a computer-based tool.

The label of the item cross-referenced, the use of brackets, and the containing reference are all taken care of by Metanorma; the document author needs only give the item identifier in the AsciiDoc source (e.g. \<<formulaB-1>> generates either “Formula (B.1)” or “B.6, Formula (B.1)”, depending on where in the document it occurs.)

Localities

Normally in AsciiDoc, any text in a cross-reference that follows a comma constitutes custom text for the cross-reference.

So a cross-reference <<ISO7301,the foregoing reference>> would be rendered as "the foregoing reference", and hyperlinked to the ISO7301 reference.

In Metanorma AsciiDoc cross-references, bibliographic localities (e.g. page numbers, clause numbers) can be added directly after the comma, as part of the cross-reference text. This overrides the normal AsciiDoc treatment of custom text.

List items

List items can be cross-referenced by inserting a bookmark at the very start of the list item:

. Ordered list
.. [[id1]] This is the first list item
... [[id2]] This is a list sub-item

Hyperlinks

Hyperlinks to URIs can have alt text, which is used in accessibility (corresponding to the HTML a@title attribute). This is specified by appending ,title=… after the text in the URL macro in AsciiDoc:

http://www.example.com[text to go into the hyperlink]

http://www.example2.com[text to go into the second hyperlink,title=This is a tooltip for the link]

Cross-references to external documents

Metanorma will process cross-references to anchors within external documents just like AsciiDoc would normally. For example,

<<document1.adoc#b>>

will be processed as a link to anchor #b in document document1.adoc.

If the reference uses the .adoc suffix, as in the example above, it is stripped in Metanorma XML and substituted with the extension of the current document type during document generation.

The above example is rendered in Metanorma XML as <xref target="document1#b">, in HTML as <a href="document1.html#b">, and in PDF as <a href="document1.pdf#b">.

Admonitions

Admonitions (NOTE, IMPORTANT, WARNING, CAUTION etc.) 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].

This attribute will encode the admonition(s) as applicable to the entire document.

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