Metanorma: Aequitate Verum

Mathematical Expressions

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 plurimath gem.

The syntax of AsciiMath recognized by plurimath can be more strict than the common MathJax processor of AsciiMath.

Example 1. 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 2. 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.
Warning
Encoding brackets inside stem:[]

When we encode inline math expressions that contain brackets we have have to make sure of two things:

  1. The closing bracket must be escaped, \].

  2. If the opening bracket is the first character of the expression, there should be a white space between stem:[ and the opening bracket; i.e. stem:[ […​. Otherwise, the engine may interpret the double-opening brackets [[ as the beginning of an anchor definition.

As an example, suppose we want to encode this inline expression: \$[x_n,y_n]\$.
The correct encoding to avoid misinterpretations would be: stem:[ [x_n,y_n\]]

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 3. 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 4. 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 5. 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 6. 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 7. 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 8. 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.