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 1. 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 2. 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.

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:

== 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)
e-notation numbers: 30000.54, 3.000054e4, 300.054e1, 0.03000054e6.

Note
Numbers like 30 000.54, 30000,54, 3.000054 x 10^4 are not accepted formats.

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

Example 3. Encoding the number value according to the en-US locale

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.

Example 4. Specifying a number formatted with the default profile

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

Example 5. Specifying usage of , as the grouping delimiter, 2 the number of digits in each group

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

Example 6. 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.

Example 7. ISO 639-2 codes for English and French

en, fr.

decimal

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

Example 8. Using the ',' "comma" symbol as the decimal point

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

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

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

precision

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

Example 10. 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.

Example 11. Specifying a total of 6 digits in rendering the number

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

group

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

Example 12. 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.)

Example 13. 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.

Example 14. Using the Unicode THIN SPACE as the fraction grouping delimiter

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

fraction_group_digits

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

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

number:32232.232131[fraction_group=' ',fraction_group_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.

Example 16. 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.

Example 17. 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.

Example 18. Using the plus sign to indicate positive numbers

number:32232.232[notation=engineering,number_sign=plus] is formatted as +32.232232 × 10⁴.

Example 19. 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).

Example 20. 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).

Example 21. Using the lowercase 'e' symbol as the exponent symbol

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

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)

The options are the same as those for the number:[] command.

Example 22. 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)

The initial 341 is set to the options of :number-presentation:, notation=e,exponent_sign=plus,precision=4.
342 overrides the precision value to be 5.
343 overrides the notation value to be scientific.
345 removes the exponent_sign value and reverts it to the default.
346 overrides the precision value to be 6.

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)

The NAME specifies the profile name. The options are the same as those for the number:[] command.

Example 23. 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.

Example 24. 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)

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

Example 25. 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)

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.

Example 26. 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)

The initial 341 is set to the options of :number-presentation:, notation=e,exponent_sign=plus,precision=4.
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.
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.
344 also uses :number-presentation-profile-x, but overrides its precision value to be 5.
345 uses :number-presentation-profile-x, removes the precision value, and adds digit_count=10, resulting in notation=engineering,times=',',exponent_sign=plus,digit_count=10.
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.

Example 27. 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.

Example 28. 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.

Example 29. 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
++++

It is possible to specify that by default, all formulas have their numbers formatted, through the number-presentation-formula document attribute.

The document attribute can take the value number-presentation, in which case it has the same value as the :number-presentation: document attribute; or default, in which case default number formatting is applied (notation='basic').

Syntax:

:number-presentation-formula: {OPTIONS}

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

Example 30. 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.

Example 31. 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 ( 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].

Note
The Metanorma stem command differs from the implementation of other AsciiDoc processors. This form of inline stem is unique to Metanorma.

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

Example 32. 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

Identifier

Semantic spans

Dates

Numbers

General

Encoding numbers as numbers

Profiles

General

Default profile

Setting the default profile

Using the default profile

Named profile

Setting named profiles

Using named profiles

Cancelling out options

Precedence rules

Encoding numbers as formulas

General

Using number-format

Using attributes on inline stem commands

Using `number-format`

Using attributes on inline `stem` commands