Metanorma: Aequitate Verum

Author's documentation

Attachments

Purpose

A Metanorma document can hyperlink to separate files that are distributed together with the document, even when they are not themselves Metanorma documents. These are called attachments.

Attachments 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)]]], {attachment-desc}

Where:

file-path

the file location of the attachment relative to the current document root file.

attachment-desc

the description of the attachment.

Note
 Attachment description is needed for accessibility and required for 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 base64-encoded within the output 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.

PDF attachments

PDF attachments can be embedded in the PDF output of a Metanorma document.

PDF supports the following attributes for attachments:

  • Volatile: indicates that the attachment is volatile and should not be cached.

  • AFRelationship: indicates the relationship of the attachment to the document.

Note
 PDF attachment attributes are not supported in HTML output. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8].

These attributes are realized in Metanorma through the bibliographic span syntax:

... span:classification.pdf-{Key}[{Value}] ...

For Volatile, the syntax is span:classification.pdf-volatile[true].

For AFRelationship, the syntax is span:classification.pdf-AFRelationship[EncryptedPayload].

Example 2. Example of encoding a PDF attachment with attributes
* [[[file1,attachment:(attachments/pdf-sample.pdf)]]],
  span:surname[Wyatt], span:givenname[Peter],
  span:date.issued[2021].
  span:date[2021].
  span:title[_Demystifying PDF through a machine-readable definition_].
  In span:series[LangSec Workshop at IEEE Security & Privacy, May 27th and 28th, 2021].
  span:publisher[IEEE].
  span:uri.citation[https://langsec.org/spw21/papers.html#pdfReadable].
  span:type[inproceedings]
  span:classification.pdf-volatile[true]
  span:classification.pdf-AFRelationship[EncryptedPayload]

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.