Metanorma now supports PDF attachments

Alexander Dyuzhev Ronald Tse on 20 Aug 2024

Introduction

Metanorma now supports PDF attachments, allowing you to embed additional resources directly within a PDF document generated by Metanorma.

Standards today are increasingly rely on the digital realm, from atmospheric standards to metrology standards, all define software behavior or information models, leading to the incorporating machine-readable components as either part of the standard, as reference implementation, as machine-executable tests or simply as examples.

Previously, these components were either distributed as separate files or incorporated as plain text inside a textual document, both methods with significant drawbacks in terms of version control, readability, consistency, and interoperability.

Metanorma provides a solution to this problem by supporting attachments, covering both HTML and PDF outputs.

This article focuses on how to use PDF attachments, which allows you to embed additional resources directly within a PDF document generated by Metanorma.

Note	The PDF attachments feature is available from Metanorma v1.10.0.

Electronic attachments to standards

Standards that specify information models, software behavior, or data exchange formats often require additional resources to support their implementation and understanding. These resources can include reference implementations, test code and data samples.

Here are some notable standards that provide digital artifacts for these purposes:

• OGC GML has reference tests provided by the OGC Executable Test Suite for GML 3.2.

• ITU-T H.265 provides a number of video files in its conformance test data (ITU-T H.265.1) and reference software (ITU-T H.265.2).

• The ISO 10303 series provides STEP EXPRESS schema files as "electronic inserts".

A unified deliverable with attachments

Metanorma supports attachments in both HTML and PDF outputs. This has the benefit of providing a unified deliverable that includes all the necessary resources in one package.

• Simplifies version control and distribution by ensuring all relevant materials are included together.

• Preserves context by bundling attachments with the main document, reducing the risk of misinterpretation or misuse.

• Allows offline access, as all attachments are included in the document and can be accessed without an internet connection.

Types of attachments to include in a standard

These are good reasons why a standard or specification chooses to provide electronic attachments:

Reference implementations

A reference implementation helps developers understand how to implement the standard correctly. This is particularly useful for standards that describe complex behavior and require detailed technical specifications for correctly implementing the standard, such as cryptographic algorithms. For example, the NIST FIPS 140-2 standard provides reference implementations for cryptographic algorithms.

Compliance tests

Providing compliance tests as electronic attachments allows implementers to verify that their implementations conform to the standard. This is particularly useful

Example files

Example files can help users understand the expected data structures and formats described in the standard. For example, the OGC GML standard provides example snippets in the standard that illustrate the expected data structures and formats.

Machine-readable files

Standards that describe data exchange formats often feature machine-readable snippets in the document for illustration. These snippets are better provided as actual files than requiring the reader to copy and paste them for testing.

PDF attachments

General

Not many people know that PDFs can contain attachments!

This feature was first introduced in PDF version 1.3, released in 1999. Today, the only PDF reader that consistently supports this feature is Adobe Reader.

Some other PDF readers and creators do support PDF attachments, but the level of support and the user interface for accessing attachments can vary between different PDF readers.

Most system default PDF readers, such as Preview on macOS, do not support PDF attachments.

Metanorma as part of its "accessible math" effort, has implemented PDF attachments for making MathML snippets available for download, and has extended this feature for all types of attachments.

Reader support (or lack thereof)

Not all PDF readers support PDF attachments. This is the current list of attachment support in common PDF readers.

Table 1. PDF attachment support on different platforms

Support	Platform	Application
✅	Windows	Adobe Reader
✅	macOS	Adobe Reader
❌	macOS	Preview
❌	macOS	Skim
❌	Cross-platform	Firefox (built-in PDF viewer)
❌	Cross-platform	Chrome (built-in PDF viewer)

Note	When distributing PDFs with attachments, it is advisable to inform readers about the presence of attachments and recommend using a compatible PDF reader.

Considerations of delivering attachments in PDF

These are some considerations to be think about when providing attachments in PDF.

File size

Attachments can significantly increase the overall size of the PDF, potentially making it more challenging to share or download.

Compatibility

Not all PDF readers support attachments, which may limit accessibility for some users.

Extraction complexity

Depending on the PDF reader, extracting attachments might be less straightforward than working with separate files, potentially leading to user frustration.

Preview limitations

Unlike embedded multimedia content, attachments cannot be previewed from within the PDF without being extracted first, which can be inconvenient for users.

Metanorma support of PDF attachments

Metanorma supports attachments, making it possible to incorporate and link to attachments to HTML and PDF outputs.

Metanorma supports embedding of any kind of file to a PDF, including source code (e.g., .c, .java, .py files), data files (XML, JSON, YAML), other PDF documents, executable binaries, images and multimedia files, and spreadsheets and databases.

In HTML output, Metanorma handles attachments as individual files that are linked from content. These attachments are placed in a separate directory alongside the HTML file.

Given a Metanorma PDF files that contain attachments, users can easily download these attachments by clicking on the provided links.

Usage

Adding PDF attachments in Metanorma is a straightforward process.

Step 1: Encode file attachments in the bibliography

To add an attachment, you first need to encode it in the bibliography section of your Metanorma document.

Syntax:

* [[[attachment-anchor,attachment:({file-path-relative-to-root-document})]]]

Where,

file-path-relative-to-root-document

is the path to the file you want to attach, relative to the root document.

This syntax creates a bibliography entry for the attachment and assigns it an anchor that can be referenced later in the document.

Step 2: Reference the attachment in the document

Once the attachment is added to the bibliography, one can reference it anywhere in the document using the standard cross-reference syntax.

Syntax:

<<attachment-anchor>>

This will create a hyperlink to the attachment in the generated PDF.

Example: Attaching a C source file

Here’s an example of how to attach a C source file to your Metanorma document:

== Scope

The C reference implementation source: <<file1>>. (2)

[bibliography]
== Bibliography

* [[[file1,attachment:(sources/program.c)]]] (1)

1. The attachment is encoded in the bibliography section with the anchor file1.

2. The C reference implementation source is located at sources/program.c.

In the rendered document:

• The bibliography will be empty because attachments are never shown.

• Clicking on the link [file1] will open the attached C source file.

Visual representation

When the PDF is generated, the attachment will be accessible through a hyperlink in the document.

Here’s how it looks:

Figure 1. Hyperlink to a PDF attachment

Users can then save the attachment from the PDF file using a compatible PDF reader:

Figure 2. Saving a PDF attachment using a compatible PDF reader (Adobe Reader)

Conclusion

The addition of PDF attachment support in Metanorma marks a significant step forward in creating comprehensive, self-contained, and interactive standards documents. By allowing the seamless integration of supplementary materials, code samples, and machine-readable content, Metanorma empowers standards authors to create more valuable resources.

As the standards landscape continues to evolve, features like PDF attachments will play a crucial role in improving document interoperability, facilitating implementation, and enhancing the overall user experience. Metanorma’s implementation of this feature, coupled with its support for multiple output formats, positions it as a versatile and powerful tool for modern standards development.

We encourage Metanorma users to explore the possibilities offered by PDF attachments and leverage this feature to create richer, more informative standards documents. As always, we welcome feedback and suggestions from our user community to continue improving Metanorma and adapting it to the changing needs of standards developers worldwide.

References

• Metanorma Attachments

• Adobe Systems Incorporated. (2006). PDF Reference, sixth edition: Adobe Portable Document Format version 1.7.

• ISO 32000-2:2017. Document management — Portable document format — Part 2: PDF 2.0