From 65c49c435b4910abbfc07b112af4477f30228388 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Tue, 27 Aug 2024 13:53:16 +0800 Subject: [PATCH] feat: update pdf attachment blog post --- _posts/2024-08-20-pdf-attachments.adoc | 303 ++++++++++++++++++++----- 1 file changed, 249 insertions(+), 54 deletions(-) diff --git a/_posts/2024-08-20-pdf-attachments.adoc b/_posts/2024-08-20-pdf-attachments.adoc index c2f90209..49fdd8d3 100644 --- a/_posts/2024-08-20-pdf-attachments.adoc +++ b/_posts/2024-08-20-pdf-attachments.adoc @@ -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 `<>` 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: <> +* 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 `<>` 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] +---- +<> +---- + +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: <>. <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 `<>` 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