-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: update pdf attachment blog post
- Loading branch information
Showing
1 changed file
with
249 additions
and
54 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,105 +4,300 @@ title: "Metanorma now supports PDF attachments" | |
| date: 2024-08-20 | ||
| categories: documentation | ||
| authors: | ||
| - | ||
| name: Ronald Tse | ||
| email: [email protected] | ||
| social_links: | ||
| - https://github.com/ronaldtse | ||
| - | ||
| name: Alexander Dyuzhev | ||
| email: [email protected] | ||
| social_links: | ||
| - https://www.linkedin.com/in/alexander-dyuzhev/ | ||
| - https://github.com/Intelligent2013/ | ||
| - | ||
| name: Ronald Tse | ||
| email: [email protected] | ||
| 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 | ||