Metanorma: Aequitate Verum

Author's documentation

Passthrough to output formats

Overview

Metanorma provides mechanisms to pass through content to output formats without modification. This is useful for including raw markup or code snippets that should not be processed by Metanorma.

Using external template processing

Metanorma uses Metanorma AsciiDoc, which is a superset of normal AsciiDoc markup.

For example, the syntax {{…​}} is used for concept mentions in Metanorma AsciiDoc, but is not recognized in basic AsciiDoc, and also can be confused by templating engines such as Liquid which uses the same syntax for variable interpolation.

  • If you pass dynamic templates (e.g. Liquid) through Metanorma AsciiDoc, you will need to ensure that the templating engine generates fully-formed Metanorma AsciiDoc output for Metanorma to process.

  • If you pass Metanorma AsciiDoc directly through other text processing tools, it is likely that such tools will misinterpret Metanorma-specific markup.

Escape Metanorma processing of markup-like text (skipping markup)

If you want to render text that looks like Metanorma AsciiDoc in a Metanorma document, e.g. to explain the use of {{…​}} itself, you will need to prevent Metanorma from interpreting it as markup.

This can be done by using passthrough markup mechanisms described below.

  • Blocks: ++++

  • Inline markup:

    • Simple escapes: ++

    • Complex escapes: Unicode Zero-Width joiner, ‍.

Note
 The Asciidoctor processor for basic AsciiDoc uses backslash to escape some characters, but it is not consistent.
For example, if you want {{A}} to display in a document, you will need to enter it as ++{{A}}++.

If you have more complex markup, ++ may not be adequate; the Unicode Zero-Width joiner, ‍, may be necessary to force Metanorma not to process the markup.

For example, if you want {{A}} to display in a document, \++{{A}}++ ends up displaying +{A}+.

You can obtain a display of ++{{A}}++ by writing +‍+{{A}}++ instead: ‍ does not display, but is a character which prevents Metanorma from recognising ++ as markup.

There are other mechanisms to prevent recognition of markup:

  • Using backquotes for monospace formatting always prevent recognition of markup: `{{A}}` is not processed as markup.

  • Using XML escapes for characters, e.g. + for +, will also prevent it.

Passthrough blocks

Passthrough text, such as XML tags, intended to be rendered in a target format unaltered, can be entered as a passthrough block [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.27].

This functionality enables automated processing, custom tagging, hacking into intermediary formats and experimental development of Metanorma output.

Warning
 A broken Metanorma XML file will cause rendering of target formats to also break. Use with caution.

Passthrough intended to be rendered in Metanorma XML (such as Metanorma XML tags), generated from Metanorma AsciiDoc input, can be entered as a passthrough block [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1], with no format indication.

Example 1. Using passthrough XML tags in the Metanorma XML target
++++
<bibitem>
++++
Warning
 Passthrough text may break the structure of the output format — it is the user’s responsibility to ensure the integrity of the resulting structure (e.g. XML) is retained.

Passthrough intended to be rendered in a target format must be specified with a format indication corresponding to one or more of the existing output formats of Metanorma in a comma-delimited manner (not limited to: html, doc, pdf, rfc, sts).

Example 2. Using passthrough XML tags in the RFC XML target
[format=rfc]
++++
<artset>
<artwork>
++++

Passthrough inline text

Metanorma AsciiDoc supports the following syntaxes for inline passthrough.

Passthrough of text that does not involve XML structural syntax can be realized in any of the following syntaxes:

// syntax 1
+this is passed through+

// syntax 2
+++this is passed through too+++

// syntax 3
pass:[also passed-through]
Example 3. Example of specifying passthrough text
This is a special pass:[𝒞𝓪𝓼𝓮].

For passthrough of XML syntax or tags to Metanorma XML, which will require special character processing, use the following command:

pass:c[xml-content]

Where:

xml-content

content that contains XML or SGML tags

Example 4. Example of specifying passthrough XML content
pass:c[<u format="num-lit">ᏚᎢᎵᎬᎢᎬᏒ</u>]

If the passthrough text is intended for one or more target formats, the formats needs to be specified with the pass-format command [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.7].

pass-format:FORMAT[...]

Where:

FORMAT

comma-delimited list of target formats.

Possible values are:

metanorma

Metanorma Semantic XML

html

HTML

doc

Word DOC

pdf

PDF

sts

STS XML

ieee

IEEE XML

rfc

RFC XML v3

txt

TXT

html_alt

HTML with alternative styling, for ISO only

isosts

ISO STS XML

all

all possible formats [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.3].

straightquotes

Text with smart quotes ignored [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.5].

Example 5. Example of specifying passthrough for selected target formats
pass-format:rfc[<u format="num-lit">ᏚᎢᎵᎬᎢᎬᏒ</u>]
Note
 Text that is marked up as pass-format is not subject to substitutions such as smart quotes. It can be used to keep straight quotes in a document that otherwise uses smart quotes.

The value `pass-format:straightquotes["…​"] is used specifically to prevent dumb quotes from being substituted with smart quotes, but otherwise is treated as Metanorma XML.