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: &x2b;&x2b;&x2b;&x2b;
• Inline markup:
  • Simple escapes: &x2b;&x2b;
  • Complex escapes: Unicode Zero-Width joiner, ‍.

For example, if you want {{A}} to display in a document, you will need to enter it as &x2b;+{{A}}&x2b;+.

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

There are other mechanisms to prevent recognition of markup:

• Using backquotes for monospace formatting always prevent recognition of markup: &x0060;++{{A}}++&x0060; 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.

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.

.Using passthrough XML tags in the Metanorma XML target

++++
<bibitem>
++++

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

.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 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 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 of specifying passthrough for selected target formats

pass-format:rfc[<u format="num-lit">ᏚᎢᎵᎬᎢᎬᏒ</u>]

The value pass-format:straightquotes["..."] is used specifically to prevent dumb (straight) quotes from being substituted with smart quotes, while otherwise treating the content as ordinary text (Metanorma Semantic XML). Use it for runs of text that must retain literal straight quotes — for example, characters quoted verbatim from a specification, such as the ” and ‘ string-delimiter operators defined in PDF (ISO 32000-2).

.Keeping literal straight quotes within smart-quoted text

The PDF string delimiters pass-format:straightquotes["] and
pass-format:straightquotes['] are left as straight quotes.

This per-instance opt-out is distinct from the document-wide `:smartquotes:` attribute: :smartquotes: false turns automatic conversion of bare quotes off for the whole document, whereas pass-format:straightquotes["..."] keeps specific runs straight while the rest of the document is still smart-quoted. Note that AsciiDoc's native plus-delimited inline passthrough (+...+) does not prevent smart-quote conversion, because Metanorma applies smart quotes in postprocessing, after AsciiDoc passthroughs have already been resolved; use pass-format (or ...) instead.