Text formatting

Metanorma supports extensive inline formatting functionality. The following formatting macros are available in Metanorma.

Basic markup

General

AsciiDoc allows you to:

Emphasize words in bold using asterisks
Italicise words with underscores
Apply monospace format using backticks
Specify superscript and subscript characters (CO₂, x⁴)

Example 1. Example of basic inline markup

*bold*
_italic_
`monospace`
^superscript^
~subscript~

Renders as:

bold italic monospace ^superscript _subscript

end::text-markup[]

Strikethrough

The strike command renders text with a middle line strikethrough.

The syntax is as follows:

[strike]#text#

Where:

text is the text to be rendered with the strikethrough style

Example 2. Illustration of strikethrough text in Metanorma.

[strike]#strike through text#

renders:

Small caps

The smallcap command renders text in small capital letters.

The syntax is as follows:

[smallcap]#text#

Where:

text is the text to be rendered in small caps

Example 3. Illustration of small caps text

[smallcap]#small caps text#

renders:

Illustration of small caps text in Metanorma

Underline

The underline command renders text with an underline. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.2].

The syntax is as follows:

[underline]#text#

Where:

text is the text to be underlined

Example 4. Illustration of underlined text

[underline]#underline text#

renders:

Illustration of underlined text in Metanorma

Ruby

Ruby annotations in East Asian text are provided [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.5] using the ruby:{annotation}[{base text}] macro.

The ruby command supports these optional parameters:

lang= for language of annotation
script= for script of annotation
type= for the type of annotation (pronunciation or annotation, with pronunciation as the default value).

ruby:とうきょう[東京]
ruby:とうきょう[lang=ja,script=Hira,type=pronunciation,東京]
ruby:Tōkyō[type=pronunciation,script=Latn,東京]
ruby:ライバル[type=annotation,親友]
ruby:とう[東] ruby:きょう[京]
ruby:Tō[script=Latn,東]ruby:kyō[script=Latn,京]

Metanorma supports "double-sided" Ruby annotations, with annotations both above and below characters; these are marked up as nested Ruby annotation macros, with the deeper nested annotation assumed to be the annotation below the characters.

ruby:とう[ruby:tou[東\]] ruby:なん[ruby:nan[南\]] の方角
ruby:たつみ[ruby:とう[東\]{blank}ruby:なん[南\]]
ruby:プロテゴ[ruby:まも[護\]{blank}れ]!
ruby:プロテゴ[れ{blank}ruby:まも[護\]]!

As of this writing, double-sided annotations are not supported in Word, and the nested annotations are realised as bracketed text.

Capitalisation

Capitalisation may be applied automatically in the rendering of documents, despite not being present in the source material; for example, titles and captions may be title-cased or put in all caps. In order to prevent a span of text automatically having its case changed, use CSS styling to set its CSS text-transform property to "none" [added in https://github.com/metanorma/isodoc/releases/tag/v2.8.5]:

Example 5. Example of a word in a title not to be capitalised

:title: [css text-transform:none]#IoT# and content standards

...

=== Approaches to [css text-transform:none]#IoT#

As shown, such styling extends to document titles as document attributes.

Custom character sets

When a private use codepoint is used in a document, reflecting an agreement between the document author and the document renderer, but not a standard like Unicode, the custom character set that includes that codepoint needs to be flagged. So U+F8D0 is the Klingon letter for "a" in the Conscript Unicode Registry, but the Kanji-Katakana hybrid of 訁and コ (equivalent to 講) in the BabelStone PUA.

In order to flag such a custom interpretation of the codepoint, the interpretation can be named in a formatting directive, flagged as custom-charset [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.3]. For example:

[custom-charset:conscript]#\\uf8d0#
[custom-charset:babelstone]#\\uf8d0#

In order to be rendered, a font implementing that interpretation needs to be indicated as a processing hint for Metanorma. This is done with the Presentation XML metadata directive :presentation-metadata-custom-charset-font: {name of interpretation}:"{name of font}", as a document attribute, giving a comma-delimited list of charset-font pairs. For instance:

:presentation-metadata-custom-charset-font: conscript:"Code 2000",babelstone:"BabelStone PUA"
:fonts: "Code 2000","BabelStone PUA"

As with CSS declarations, any font specified as a custom charset font also needs to be passed to Metanorma in the :fonts: document attribute.

Numeric ranges

Numeric ranges, like dates (e.g., 1981–1995), make use of en dashes in between the numbers, usually without any white space around.

At the time writing, there is no AsciiDoc encoding to render en dashes.

In Metanorma, there is a vision of implementing a semantic encoding for numeric ranges, perhaps an option like range:[n,m] or shorthands like n..m.

For the time being, the existent workaround for such cases is the use of entity codes, more specifically:

&&#x200c;ndash;

Example 6. Examples of encoding numeric ranges

See chapters 15&ndash;17...

Issues 18&ndash;20 are in fact a single issue...

_Laser Physics_ *17* 1017&ndash;1024 (2007).

renders:

See chapters 15–17…

Issues 18–20 are in fact a single issue…

Laser Physics 17 1017–1024 (2007).

Character substitutions

tag::char-subs[]

Metanorma AsciiDoc supports Asciidoctor-style character substitutions as shown in Supported Metanorma AsciiDoc character substitutions.

Metanorma AsciiDoc also recognises HTML and XML character references, and decimal and hexadecimal Unicode code points.

Table 1. Supported Metanorma AsciiDoc character substitutions
Source	Rendered as	Note
(C)	© (Unicode 'Copyright Sign' `U+00A9`)
(R)	® (Unicode 'Registered Sign' `U+00AE`)
(TM)	™ (Unicode 'Trade Mark Sign' `U+2122`)
`-`	— (Unicode 'Em Dash' `U+2014`)	See NOTE below.
...	(Unicode 'Horizontal Ellipsis' `U+2026`)
->	→ (Unicode 'Rightwards Arrow' `U+2192`)
=>	⇒ (Unicode 'Rightwards Double Arrow' `U+21D2`)
<-	← (Unicode 'Leftwards Arrow' `U+2190`)
<=	⇐ (Unicode 'Leftwards Double Arrow' `U+21D0`)
`'`	Smart single quote, smart apostrophe
`"`	Smart double quote

Note	Replacement of `-` only occurs when placed between two word characters, between a word character and a line boundary, or flanked by spaces. Flanking spaces (as in `x — y`) are rendered as thin spaces (Unicode 'Thin Space' `U+2009`).

end::char-subs[]

end::tutorial[]

CSS declarations

The css command is used to wrap content with a CSS declaration (MDN) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6].

This feature only applies to HTML output.

Note	CSS declarations are also used within the HTML `style` attribute.

The syntax is as follows:

[css {css-directive}]#{styled-text}#

Where:

{css-directive} is a CSS declaration
{styled-text} is text where the CSS declaration is to be applied

Example 7. Example of applying a custom CSS declaration to content

[css font-family:"Noto Sans JP"]#お好み焼き#

[css font-family:"Noto Sans Canadian Aboriginal"]#ᓀᐦᐃᔭᐍᐏᐣ#

Note	Any font specified in `[css font-family:…]` needs to be passed to Metanorma for processing by specifying it in the `:fonts:` document attribute.

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 8. 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 9. 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.

Nesting of styles

Character styles can be nested within each other, with both constrained and unconstrained formatting marks.

*Boldmono__space__*

Note	See Asciidoctor Text.