Attachments

Purpose

There are often occasions where a Metanorma document needs to hyperlink to separate files, that are not themselves Metanorma documents, but which need to be distributed together with the document.

This could include source code, configuration files, executable binaries, or any other file — so long as it is expected to be hyperlinked by Metanorma instead of being processed as a Metanorma file.

Syntax

File attachments are encoded in the bibliography section of a Metanorma document.

The syntax is provided as follows [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.10]:

* [[[anchor,attachment:(file path of attachment relative to current fileidentifier)]]], attachment description

Note	attachment description is needed for accessibility and conformance with PDF/A and PDF/UA.

Example 1. Example of attaching the schemas/schema.txt file

This indicates that schemas/schema.txt is an attachment to the current document, and assigns the anchor file1 to it.

* [[[file1,attachment:(schemas/schema.txt)]]], Schema text

Any cross-references to [file1] are to be interpreted as hyperlinks to that file, and will be so rendered in output.

By default, attachments are binary-encoded within the Metanorma XML file, just as with images. If the references to attachments are to be kept as file references in the XML file, set the document attribute data-uri-attachment: false.

Output

General

When the Presentation XML output for a Metanorma document is generated (as a precursor to DOC, HTML and PDF output), the documents are output to the folder {document-filename}_attachments relative to the output HTML file.

HTML

In HTML, references to the attachments are hyperlinked from the bibliography to their disk location.

PDF

In PDF, attachments are embedded in the PDF can be saved from the PDF file when using a compatible PDF reader.