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. |
schemas/schema.txt
fileThis 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.
In PDF, attachments are embedded in the PDF can be saved from the PDF file when using a compatible PDF reader.