Semantic elements

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 of rendering a URI using the identifier command

Example

identifier:[https://schemas.isotc211.org/19115/-1/mdb/1.3]

renders:

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

.Example of rendering a URN using the identifier command

Example

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.

The semantic label is realised in Metanorma as a class attribute. That means that distinct rendering of spans can be specified by embedding custom CSS in the Metanorma document, with CSS classes matching the span:

[.preface]
== Metanorma-Extension
=== user-css
[source]
----
.green { background-color: green}
----
....
span:green[this text is highlighted as green]

Dates

The date command is used to introduce dates and date-times as semantic elements [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.5]. The value of the date:[] command is an ISO-8601 formatted date or date-time. The second argument given in the command, if present, is a `strftime` formatting description of the date. (Space can be specified as %_.) Month and day names and abbreviations, if requested in the formatting string, are internationalised to the document language.

date:[2012-02-02]
date:[2012-02-02, %F]
date:[2012-02-02, %A %d %B] # Thursday 2 February
date:[2012-02-02T21:04:05, %F%_%l%_%p]

Numbers

General

Numbers are formatted consistent according to the current flavor, when encoded explicitly as such, or as encoded in mathematical expressions,

Numbers are formatted according to the flavour's specifications, where defined:

grouping digits;
decimal points; and
precision.

Where these are not specified, the defaults for the document language are used, as specified by twitter-cldr-rb.

Encoding numbers as numbers

Numbers are encoded using the number command. It allows users to specify in detail how a number should be formatted. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.12]

Note

This only affects the presentation of the number. The encoded number in Semantic XML is the full precision number as entered.

The usage of the number command is as follows:

number:{NUMBER}[{OPTIONS}]

Where:

NUMBER

(mandatory) The numerical value to represent. Entered between number: and the [...].

Accepted values are the number formats for Ruby's BigDecimal library:

normal numbers (with no spaces, and with decimal point)
non-decimal numbers prefixed with 0x (hexadecimal), 0o (octal), and 0b (binary), including fractional numbers [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.3.0]
e-notation numbers: 30000.54, 3.000054e4, 300.054e1, 0.03000054e6.

The number must be specified according to the en-US locale.

.Encoding the number value according to the en-US locale [example] 30000.54 is recognised as a decimal number, 30 000,54 is not.

If the document is in French, 30000.54 will in fact be rendered consistent with French practice, as 30 000,54.

OPTIONS

(optional) Comma-delimited list of formatting instructions options, in pairs. Each option pair is formed by the option name and its value, where the value can be given in single or double quotes. If no formatting options are specified, the [] is left empty.

Specifying a number formatted with the default profile

number:30000.54[] is formatted as "30,000.54".

Specifying usage of `,` as the grouping delimiter, `2` the number of digits in each group

number:28228.288[group=',',group_digits=2]

Specifying a number formatted with combined options of `decimal` and `group`

number:30000.54[decimal=',',group=' '] is formatted as "30 000,54"

The following options are recognised (as provided by Plurimath):

locale

Language code whose conventions need to be followed for the number. The value is a two-letter ISO 639-2 code. The locale is assumed to be specified in the Unicode CLDR.

ISO 639-2 codes for English and French

en, fr.

decimal

Symbol to use for the decimal point. Accepts a character.

Using the ',' "comma" symbol as the decimal point

number:32232.232[decimal=','] is formatted as 32232,232.

Using the '.' "full stop" symbol as the decimal point

number:32232.232[decimal='.'] is formatted as 32232.232.

significant

Number of significant digits to render. Accepts an integer value.

Specifying a precision of 6 digits

number:32232.232[significant=6] is formatted as 32232.2.

precision

Number of fractional digits to render. Accepts an integer value.

Specifying a precision of 6 digits

number:32232.232[precision=6] is formatted as 32232.232000.

digit_count

Total number of digits to render. Accepts an integer value.

Specifying a total of 8 digits in rendering the number

number:32232.2[digit_count=8] is formatted as 32232.200.

group

Delimiter to use between groups of digits. Accepts a character. (default is not to group digits.)

Using the Unicode THIN SPACE as the grouping delimiter

The grouping delimiter is Unicode THIN SPACE, U+2009.

number:32232.232[group=' '] is formatted as 32 232.232.

group_digits

Number of digits in each group of digits. Accepts an integer value. (default is 3 in most locales.)

Using the Unicode THIN SPACE as the grouping delimiter, and grouping every 2 digits

number:32232.232[group=' ',group_digits=2] is formatted as 3 22 32.232.

fraction_group

Delimiter to use between groups of fractional digits. Accepts a character.

Using the Unicode THIN SPACE as the fraction grouping delimiter

number:32232.232131[fraction_group=' '] is formatted as 32232.232 131.

fractiongroupdigits

Number of digits in each group of fractional digits. Accepts an integer value.

Using the Unicode THIN SPACE as the fraction grouping delimiter, and grouping every 2 fraction digits

number:32232.232131[fractiongroup=' ',fractiongroup_digits=2] is formatted as 32232.23 21 31.

notation

Type of notation to use for rendering. Possible values are:

basic: Basic notation.
e: Exponent notation.
scientific: Scientific notation.
engineering: Engineering notation.
Using the engineering notation
number:32232.232[notation=engineering] is formatted as 32.232232 × 10⁴.

exponent_sign

Whether to use a plus sign to indicate positive exponents, in exponent-based notation (used in the modes: e, scientific, engineering). Legal values are:

plus: The + symbol is used.
Using the plus sign to indicate positive exponents
number:32232.232[notation=engineering,exponent_sign=plus] is formatted as 32.232232 × 10⁺⁴.

number_sign

Whether to use a plus sign to indicate positive numbers [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.7]. Legal values are:

plus: The + symbol is used. This option is automatically populated if a + appears in front of the number entered.
Using the plus sign to indicate positive numbers
number:32232.232[notation=engineering,number_sign=plus] is formatted as +32.232232 × 10⁴.
Prefixing a "plus" sign in the value to use the plus sign option by default
number:+32232.232[] is formatted as +32232.232.

times

Symbol to use for multiplication where required by the notation (used in the modes: scientific and engineering).

Using the '·' "middle dot" symbol as the multiplication symbol

number:32232.232[notation=engineering,times=·] is formatted as 32.232232 · 10⁴.

e

Symbol to use for exponents in E notation (default value E). (used in the mode: e only).

Using the lowercase 'e' symbol as the exponent symbol

number:32232.232[notation=e,e=e] is formatted as 3.2232232e5.

large_notation

Allow a choice of two different notations for numbers, one as the default (notation), and this for very large or very small numbers. Takes the same values as notation.

largenotationmin

The threshold for very small numbers, below which the large_notation option must be applied. If not provided, it defaults to 1e-6.

largenotationmax

The threshold for very large numbers, above which the large_notation option must be applied. If not provided, it defaults to 1e6.

Using `large_notation` to flip between two notations for numbers

number:32232.232[notation-basic,large_notation=e] is formatted as 32232.232. number:322322.32[notation-basic,large_notation=e] is formatted as 3.2232232E6. number:322322.32[notation-basic,largenotation=e,largenotation_max=1e7] is formatted as 322322.32. number:0.000032232232[notation-basic,large_notation=e] is formatted as 0.000032232232. number:0.0000032232232[notation-basic,large_notation=e] is formatted as 3.2232232E-6. number:0.0000032232232[notation-basic,largenotation=e,largenotation_min=1e-7] is formatted as 0.0000032232232.

base

Sets the numeric base (radix) used to render both the integer and fractional parts of the number [added in https://github.com/metanorma/isodoc/releases/tag/v3.5.1]. Supported values are:

2: binary
8: octal
10: decimal (default)
16: hexadecimal

base_prefix

Overrides the default base prefix for non‑decimal bases [added in https://github.com/metanorma/isodoc/releases/tag/v3.5.1].

(omitted): when omitted, standard prefixes are used (0b for base 2, 0o for base 8, 0x for base 16).
nil or empty string: omits the prefix entirely.

base_postfix

If present, a postfix is appended to the converted number instead of using any base prefix [added in https://github.com/metanorma/isodoc/releases/tag/v3.5.1]. This is applied after digit grouping.

(text present): the specified text is used as the postfix.
nil or empty string: omits the postfix.

hex_capital

the capitalisation of hexadecimal digits, namely, characters in the range a-f, and any letters used as separators in hexadecimal numbers. This only applies when base is 16. This includes both hexadecimal digits and any separators (such as decimal, group, fraction_group) that happen to be letters in the a-f range. The base_prefix and base_postfix values are never modified. It has no effect for other bases. [added in https://github.com/metanorma/isodoc/releases/tag/v3.5.1].

false: Hexadecimal digits and any letters used as separators in hexadecimal numbers are rendered in lowercase (default).
true: Hexadecimal digits and any letters used as separators in hexadecimal numbers are rendered in uppercase.

Profiles

General

Profiles of mathematical notation preferences can be defined through document attributes to reduce repetition of setting the same options.

Default profile

Setting the default profile

The document attribute :number-presentation: sets the default options to be applied for any number:[] in the document.

:number-presentation: {OPTIONS} <1>

Setting the default profile with number options

:number-presentation: notation=e,exponent_sign=plus,precision=4

Using the default profile

When using the number:[] command, the default profile is applied unless overridden by the options specified in the command.

In the following document, all numbers are formatted according to the default profile set in :number-presentation:.

:number-presentation: notation=e,exponent_sign=plus,precision=4
number:341[] <1>
number:342[precision=5] <2>
number:343[notation=scientific] <3>
number:345[exponent_sign=nil] <4>
number:346[precision=6] <5>

Named profile

Setting named profiles

A named profile specified as :number-presentation-profile-NAME: overrides the default when invoked in number:[] with the argument profile=NAME.

Multiple number named profiles can be created and reused.

:number-presentation-profile-NAME: {OPTIONS} <1>

Setting a profile called `foo` and its number options

:number-presentation-profile-foo: notation=e,exponent_sign=plus,precision=4

Using named profiles

In the following document, all numbers are formatted according to the default profile set in :number-presentation:, except for 342 and 343, which use the named profile foo.

Demonstrate named profiles and overrides

:number-presentation: notation=e,exponent_sign=plus,precision=4
:number-presentation-profile-foo: notation=scientific,exponent_sign=nil,decimal=","
:number-presentation-profile-bar: notation=engineering,precision=4,times=','
:number-presentation-profile-baz: notation=engineering,precision=4,times=',',exponent_sign=nil
number:341[] <1>
number:342[profile=foo] <2>
number:343[profile=foo,precision=5] <3>
number:344[profile=bar] <4>
number:345[profile=baz] <5>
number:346[profile=baz,precision=6] <6>

<1> The initial 341 is set to the options of :number-presentation:, notation=e,exponent_sign=plus,precision=4. <2> 342 uses profile=foo, so it uses :number-presentation-profile-foo:. <3> 343 also uses profile=foo, but overrides its precision value to be 5. <4> 344 uses profile=bar, so it uses :number-presentation-profile-bar:. <5> 345 uses profile=baz, so it uses :number-presentation-profile-baz:. <6> 346 also uses profile=baz, but overrides its precision value to be 6.

Cancelling out options

To cancel out an option set in a profile, set the value to nil.

The value nil cancels out the option, reverting it to the default.

Setting an option to `nil` in a named profile

:number-presentation-profile-baz: notation=engineering,precision=4,times=',',exponent_sign=nil
number:345[profile=baz,precision=nil] <1>

<1> 345 uses profile=baz, so it uses :number-presentation-profile-baz:, but cancels out the precision value. The result is notation=engineering,times=',',exponent_sign=nil.

Precedence rules

The following precedence rules apply:

Any options specified in the number:[] command override any profiles.
Any options specified in a named profile override the default profile.
Any value nil set on an option cancels out that option.

In the following document, all other numbers override :number-presentation: in some way.

Demonstrate number option precedence with a default profile and named profiles

:number-presentation: notation=e,exponent_sign=plus,precision=4
:number-presentation-profile-foo: notation=scientific,exponent_sign=nil,decimal=","
:number-presentation-profile-bar: notation=engineering,precision=4,times=','
number:341[] <1>
number:342[profile=foo] <2>
number:343[profile=bar] <3>
number:344[profile=bar,precision=5] <4>
number:345[profile=bar,,digit_count=10,precision=nil] <5>
number:346[precision=6,digit_count=10,exponent_sign=nil] <6>

<1> The initial 341 is set to the options of :number-presentation:, notation=e,exponent_sign=plus,precision=4.

<2> 342 uses profile=3, so it uses :number-presentation-profile-3:. That replaces notation=e with notation=scientific; it removes exponent_sign=plus (by setting exponent_sign=nil); it adds decimal=","; and it retains precision=4.

<3> 343 uses profile=x, so it uses :number-presentation-profile-x, which similarly overrides :number-presentation:, resulting in notation=engineering,precision=4,times=',',exponent_sign=plus.

<4> 344 also uses :number-presentation-profile-x, but overrides its precision value to be 5.

<5> 345 uses :number-presentation-profile-x, removes the precision value, and adds digit_count=10, resulting in notation=engineering,times=',',exponentsign=plus,digitcount=10.

<6> 346 overrides :number-presentation:, without appealing to a named profile: it overrides precision as precision=6, it sets digit_count=10, and it removes exponent_sign, resulting in notation=e,precision=6,digit_count=10.

Encoding numbers as formulas

General

Numbers can be formatted within stem blocks.

By default, numbers in stem blocks are not formatted at all: number formatting is reserved for the number command.

If a formula contains the string 1221, it will not be formatted into 1,221, but left alone.

Using `number-format`

In order to make a block formula format its numbers, use the argument number-format on [stem]: it has the same format as the foregoing number formatting expressions.

Using the `number-format` argument on a `stem` block

[stem]
++++
1 + x
++++
[stem,number-format="precision=2"]
++++
1 + x
++++

renders as:

1 + x
1.00 + x

Default numeric processing is applied to a formula by specifying number-format=default.

Using the `number-format` argument with `default` on a `stem` block

[stem,number-format="default"]
++++
1221 + x
++++

in an English-language document applies default English locale formatting on the formula's number, to render as:

1,221 + x

Number formatting profiles can also be used on formulas.

Using a number formatting profile on a `stem` block

:number-presentation-profile-foo: notation=scientific,exponent_sign=nil,decimal=","
[stem,number-format="profile=foo"]
++++
1221 + x
++++

To specify the number presentation within all formulas (by default), the number-presentation-formula document attribute is used.

The document attribute takes the same form of value as number-presentation. It also takes the following special values:

number-presentation: this gives number formats in formulas the same value as the :number-presentation: document attribute, meaning that numbers both within and outside formulas are formatted the same way. This is also the default behaviour if number-presentation-formula is not provided [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.8].
nil: apply no formatting to the numbers in formulas [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.8].
default: default number formatting is applied to numbers in formulas (notation='basic').

Syntax:

:number-presentation-formula: {OPTIONS}

number:[] and numbers in formulas are subject to identical formatting.

Number formatting in formulas

The following syntax:

:number-presentation: notation=scientific
number:1000[]
[stem]
++++
1000+y
++++

Renders as:

_ 1e3 1e3 + y _

identically to:

:number-presentation: notation=scientific
:number-presentation-formula: number-presentation
number:1000[]
[stem]
++++
1000+y
++++

Resetting number formatting in formulas

:number-presentation: notation=scientific
:number-presentation-formula: nil
number:1000[]
[stem]
++++
1000+y
++++

renders with no number formatting in the formula, as:

1e3
1000 + y

and

:number-presentation: notation=scientific
:number-presentation-formula: nil
number:1000[]
[stem]
++++
1000+y
++++

renders with basic number formatting in the formula, as:

1e3
1,000 + y

If number-presentation-formula is set, a formula can ignore all number formatting by setting number-format: nil on the formula itself.

Using the `number-presentation-formula` document attribute

:number-presentation-formula: notation=scientific
[stem]
++++
1221 + x
++++
[stem,number-format=nil]
++++
1221 + x
++++

renders as:

1.221e3 + x
1221 + x

The number command however provides granular configuration options, and is the recommended method for encoding numbers for consistency reasons.

Encoding plain numbers inside a math block

There are stem:[30000.54] people in attendance.

Using attributes on inline `stem` commands

Specifying number formatting on inline stem ( \ ) is supported through the following means (inline stem commands do not support attributes):

through using the document-level attribute :number-presentation-formula:; or
by providing the number formatting as an attribute string delimited by % [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.7].

If % needs to appear as a number formatting attribute value, encode it as the XML entity \%.

Using number formatting on inline `stem` commands

This encoding:

stem:[number-format="notation=e,exponent_sign=&#x25;,precision=4"% 10 xx 30]

renders as:

1.000e%1 × 3.000e%1