Metanorma: Aequitate Verum

Author's documentation

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:[] macro is an ISO-8601 formatted date or date-time. The second argument given in the macro, 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]

The usage of the number command is as follows:

number:{NUMBER}[{OPTIONS}] (1)

  1. Where NUMBER is the number, and OPTIONS is a comma-delimited list of options for the command.

    NUMBER

    The numerical value is entered between number: and the […​].

    OPTIONS

    Formatting instructions are comma-delimited pairs of an option and a value, where the value can be given in single or double quotes.

    • If no formatting options are specified, the [] is left empty.

    • The following options are recognised (as implemented in Plurimath).

      locale

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

      en, fr.

      precision

      Number of fractional digits to render.

      number:32232.232[precision=6] is 32232.232000.

      digit_count

      Total number of digits to render.

      number:32232.232[digit_count=6] is 32232.2.

      group

      Delimiter to use between groups of digits.

      number:32232.232[group=' '] (Unicode thin space) is 32 232.232.

      group_digits

      Number of digits in each group of digits. (default is 3 in most locales).

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

      fraction_group

      Delimiter to use between groups of fractional digits.

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

      fraction_group_digits

      Number of digits in each group of fractional digits.

      number:32232.232131[fraction_group=' ',fraction_group_digits=2] is 32232.23 21 31.

      notation

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

      basic

      Basic notation.

      e

      Exponent notation.

      scientific

      Scientific notation.

      engineering

      Engineering notation.

      number:32232.232[notation=engineering] is 32.232232 × 104.

      exponent_sign

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

      plus

      The + symbol is used.

      number:32232.232[notation=engineering,exponent_sign=plus] is 32.232232 × 10+4.

      times

      Symbol to use for multiplication where required by the notation (scientific, engineering).

      number:32232.232[notation=engineering,times=·] is 32.232232 · 104.

      e

      Symbol to use for exponents in E notation (default value E).

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

Profiles

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

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

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

  • Any options specified in the number:[] macro override any profiles.

  • Any value nil set on an option cancels out that option.

Examples

number:30000.54[]

Is formatted as "30,000.54".

number:30000.54[decimal=',',group=' ']

Is formatted as "30 000,54"

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

:number-presentation: notation=e,exponent_sign=plus,precision=4
:number-presentation-profile-3: notation=scientific,exponent_sign=nil,decimal=","
:number-presentation-profile-x: notation=engineering,precision=4,times=','

number:341[] (1)
number:342[profile=3] (2)
number:343[profile=x] (3)
number:344[profile=x,precision=5] (4)
number:345[profile=x,,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 has 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 has 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=',',exponent_sign=plus,digit_count=10.

  6. 346 overides :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

Numbers can be encoded in the stem blocks, and are formatted identically as those using the number command.

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

Example 3. Encoding plain numbers inside a math block
There are stem:[30000.54] people in attendance.
Note
 The number in the stem:[] expression must be specified according to the en-US locale; 30000.54 is recognised as a decimal number, 30 000,54 is not. However, if the document is in French, stem:[30000.54] will in fact be rendered consistent with French practice, as 30 000,54.