Text formatting

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⁴)

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

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

.Illustration of strikethrough text in Metanorma.

Example

[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

.Illustration of small caps text

Example

[smallcap]#small caps text#

renders:

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

.Illustration of underlined text

Example

[underline]#underline text#

renders:

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 of a word in a title not to be capitalized

: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.

For a more deep explanation about encoding custom characters, see Encoding and rendering special characters in Metanorma.

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:

&‌ndash;

.Examples of encoding numeric ranges

See chapters 15–17...
Issues 18–20 are in fact a single issue...
_Laser Physics_ *17* 1017–1024 (2007).

Character substitutions

Metanorma AsciiDoc supports Asciidoctor-style character substitutions as shown in table-char-sub.

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

.Supported Metanorma AsciiDoc character substitutions

In addition to these character substitutions, Metanorma converts straight quotes to smart quotes in postprocesssing: see ink:/author/ref/document-attributes#smart-quotes[Smart quotes] for the associated rules.

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.

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 of applying a custom CSS declaration to content

[css font-family:"Noto Sans JP"]#お好み焼き#
[css font-family:"Noto Sans Canadian Aboriginal"]#ᓀᐦᐃᔭᐍᐏᐣ#

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

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

.Example of rendering a URN using the identifier command

identifier:[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.

Nesting of styles

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

*Boldmono__space__*