Skip to content

Commit

Permalink
feat: update pdf attachment blog post
Browse files Browse the repository at this point in the history
  • Loading branch information
@ronaldtse
ronaldtse committed Aug 27, 2024
1 parent 88cf183 commit b348bb7
Showing 1 changed file with 249 additions and 54 deletions.
303 changes: 249 additions & 54 deletions _posts/2024-08-20-pdf-attachments.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,105 +4,300 @@ title: "Metanorma now supports PDF attachments"
date: 2024-08-20
categories: documentation
authors:
-
name: Ronald Tse
email: ronald.tse@ribose.com
social_links:
- https://github.com/ronaldtse
-
name: Alexander Dyuzhev
email: dyuzhev@gmail.com
social_links:
- https://www.linkedin.com/in/alexander-dyuzhev/
- https://github.com/Intelligent2013/
-
name: Ronald Tse
email: ronald.tse@ribose.com
social_links:
- https://github.com/ronaldtse

excerpt: >-
Metanorma-generated PDFs now support attachments.
Metanorma-generated PDFs now support attachments, offering a more robust
method for bundling related documents and resources.
---
== Introduction

NOTE: PDF attachments feature is available *from* Metanorma v1.10.0.
Metanorma now supports PDF attachments, allowing you to embed additional
resources directly within a PDF document generated by Metanorma.

Increasingly, organizations are issuing PDFs that contain attachments in order
to incorporate machine-readable content.
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.

Metanorma allows specifying the attachments for PDF documents, and generates the
hyperlinks to the attachments.
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.

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

Metanorma supports per-document attachments so that users that only deal
with one document file can easily incorporate and link to the
incorporated attachments as native document elements.
This article focuses on how to use PDF attachments, which allows you to embed
additional resources directly within a PDF document generated by Metanorma.

Sometimes Metanorma document needs to link to non-Metanorma documents (files),
but which need to be distributed together with the document, for instance:
NOTE: The PDF attachments feature is available *from* Metanorma v1.10.0.

* program code,

* XML, JSON, YAML files,
== Electronic attachments to standards

* PDF files,
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.

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

Metanorma already supports the PDF attachments for math formulas in BIPM SI Brochure,
see our post link:../2021-08-26-pdf-accessibility-for-math-formulas[Making math accessible in Metanorma PDFs],
but now we extend this feature for used-defined attachments for all flavors.
* OGC GML has reference tests provided by the
https://github.com/opengeospatial/ets-gml32[OGC Executable Test Suite for GML 3.2].

The attachment can be added into the Metanorma document in two steps:
* ITU-T H.265 provides a number of video files in its conformance test data
(https://www.itu.int/rec/T-REC-H.265.1/en[ITU-T H.265.1]) and reference software
(https://www.itu.int/rec/T-REC-H.265.2/en[ITU-T H.265.2]).

. encode file attachments in the bibliography section of a Metanorma document
+
```
* [[[anchor,attachment:(file path of attachment relative to current file identifier)]]]
```
* The ISO 10303 series provides STEP EXPRESS schema files as "electronic inserts".

. use the cross-reference to `<<anchor>>` in the document

== A unified deliverable with attachments

.Example of attaching the `sources/program.c` program code file
====
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.

```
== Scope
* Simplifies version control and distribution by ensuring all relevant materials are
included together.

The sample C program: <<file1>>
* Preserves context by bundling attachments with the main document, reducing
the risk of misinterpretation or misuse.

[bibliography]
== Bibliography
* Allows offline access, as all attachments are included in the document and
can be accessed without an internet connection.

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

```
== Types of attachments to include in a standard

Any cross-references to `<<file1>>` will be point to the attachment.
====
These are good reasons why a standard or specification chooses to provide
electronic attachments:

.The resulted PDF with hyperlink to the attachment
image::/assets/blog/2024-08-20_1.png[]
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.

.PDF attachments can be saved from the PDF file in the compatible PDF reader (Adobe Reader example)
image::/assets/blog/2024-08-20_2.png[]
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

== PDF attachments support in the PDF readers
=== General

Not every PDF reader supports PDF attachments!
Not many people know that PDFs can contain attachments!

.PDF attachment support in PDF readers on different platforms
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
link:blog/2021-08-26-pdf-accessibility-for-math-formulas/["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.

.PDF attachment support on different platforms
[cols="a,a,a",options="header"]
|===
| Support | Platform | Application

| ✓ | Windows | Adobe Reader
| ✓ | macOS | Adobe Reader
| ✗ | macOS | Preview
| ✗ | macOS | Skim
| ✅ | 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:

[source,adoc]
----
* [[[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:

[source,adoc]
----
<<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:

[source,adoc]
----
== 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:

.Hyperlink to a PDF attachment
image::/assets/blog/2024-08-20_1.png[]

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

.Saving a PDF attachment using a compatible PDF reader (Adobe Reader)
image::/assets/blog/2024-08-20_2.png[]


== 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

* https://www.metanorma.org/author/topics/sections/attachments/[Attachments]
* https://www.metanorma.org/author/topics/sections/attachments/[Metanorma Attachments]
* https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdf_reference_archive/pdf_reference_1-7.pdf[Adobe Systems Incorporated. (2006). PDF Reference, sixth edition: Adobe Portable Document Format version 1.7.]
* https://www.iso.org/standard/63500.html[ISO 32000-2:2017]. Document management — Portable document format — Part 2: PDF 2.0

0 comments on commit b348bb7

Please sign in to comment.