Extension container

General

By default the single prefatory clause is identified with the pre-defined section titles:

metanorma-extension

`metanorma-extension` section

The metanorma-extension element in Metanorma XML contains miscellaneous data necessary for the processing of the document, that are not themselves part of the document.

If a preface clause is named metanorma-extension (case-insensitive), its contents are appended to the metanorma-extension element for the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7].

This can be used to add data into a document that is not to be rendered, but which is still needed for processing.

The following features utilize the metanorma-extension section:

detailed revision history encoding
UnitsML definitions of units referenced in the document, or identifiers used as aliases of anchors in the document.
custom CSS declaration

Embedding external files

External files can be included in the metanorma-extension section, which is useful for including data that is not part of the document, but which is still needed for downstream processing or attaching content to the document.

The source_include:path[] command specifies the inclusion of contents of an external file in the metanorma-extension section [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.9].

The file contents will be copied into a clause within metanorma-extension with the file location as its title, and the contents of the file will be nested in a source element.

Syntax:

source_include:path[]

Where,

path: is the location of the external file, which can be a relative path to the file it is defined.

Example 1. Including a file in the metanorma-extension section

[[clause1]]
== Clause
source_include:spec/fixtures/nested_file_1.yaml[]

Some content in the clause.

generates:

<!-- ... -->
<metanorma-extension>
  <clause obligation="normative">
    <title>spec/fixtures/nested_file_1.yaml</title>
    <source>---
name: nested file-main
description: nested description-main
one: nested one-main
two: nested two-main </source>
  </clause>
</metanorma-extension>

<!-- ... -->

<clause id="..." anchor="clause1" inline-header="false" obligation="normative">
  <title>Clause</title>
  <p id="...">Some content in the clause.</p>
</clause>

<!-- ... -->