RFC 7995

PDF Format for RFCs

📅 published December 2016, from ietf

RFC 7995: PDF Format for RFCs 🎀

okay bestie, this one is SO good 💖 It's from the Internet Architecture Board (IAB), written by T. Hansen, Ed. (AT&T Laboratories), L. Masinter, and M. Hardy (Adobe). It's Informational (not Standards Track), ISSN 2070-1721, dated December 2016. Its title block doesn't list anything it obsoletes or updates. ✨ (Part 1 of 4)

Abstract

okay so the vibe here 🦋 This doc covers the options and requirements for PDF rendering of RFCs in the RFC Series, as outlined in RFC 6949. It also talks about using PDF for Internet-Drafts, plus the software tools that exist (or are still needed) for making PDFs and working with them 💅

Status of This Memo

Not gonna lie, this part is very official 🙈 This document is not an Internet Standards Track specification. It's published for informational purposes.

It's a product of the Internet Architecture Board (IAB) and represents information the IAB decided was valuable to keep on permanent record. It represents the consensus of the IAB. Documents the IAB approves for publication are not a candidate for any level of Internet Standard. (See Section 2 of RFC 7841 for that.) 🧚

For the current status, any errata, and how to send feedback, check http://www.rfc-editor.org/info/rfc7995 🍓

The legal bit 💜 Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they're in effect on the date of publication. Please read these carefully, because they describe your rights and restrictions for this document. 🫶

Table of Contents

1. Introduction ....................................................3
2. Choosing PDF Versions and Standards .............................3
3. Options and Requirements for PDF RFCs ...........................4
   3.1. "Visible" Requirements .....................................5
        3.1.1. General Visible Requirements ........................5
        3.1.2. Page Size and Margins ...............................5
        3.1.3. Headers and Footers .................................5
        3.1.4. Paragraph Numbering .................................6
        3.1.5. Paged Content Layout ................................6
        3.1.6. Typeface Choices ....................................7
        3.1.7. Hyphenation and Line Breaks .........................8
        3.1.8. Hyperlinks ..........................................8
        3.1.9. Similarity to Other Outputs .........................9
   3.2. "Invisible" Options and Requirements ......................10
        3.2.1. Internal Text Representation .......................10
        3.2.2. Unicode Support ....................................11
        3.2.3. Image Processing (Artwork) .........................12
        3.2.4. Text Description of Images (Alt-Text) ..............12
        3.2.5. Metadata Support ...................................12
        3.2.6. Document Structure Support .........................13
        3.2.7. Embedded Files .....................................13
   3.3. Digital Signatures ........................................14
4. Security Considerations ........................................15
5. References .....................................................16
   5.1. Normative References ......................................16
   5.2. Informative References ....................................17
Appendix A. History and Current Use of PDF with RFCs and
            Internet-Drafts .......................................18
  A.1. RFCs .......................................................18
  A.2. Internet-Drafts ............................................18
Appendix B. Paged Content Layout Quality ..........................18
Appendix C. Tooling ...............................................19
  C.1. PDF Viewers ................................................19
  C.2. Printers ...................................................19
  C.3. PDF Generation Libraries ...................................20
  C.4. Typefaces ..................................................20
  C.5. Other Tools ................................................20
IAB Members at the Time of Approval ...............................21
Acknowledgements ..................................................21
Authors' Addresses ................................................22

1. Introduction ✨

the RFC Series is evolving 🌸 as outlined in RFC 6949. Future documents will use a canonical format, XML, with renderings in various formats, including PDF.

PDF can do a LOT, so not all PDFs are "equal" 🙈 For example, two documents that look visually similar could be made of scanned or rasterized images, or they could include text layout options, hyperlinks, embedded fonts, and digital signatures. (See [APP-PDF] for a history of PDF.)

This document explains some of the relevant options and makes recommendations, for both the RFC Series and Internet-Drafts. 💅

The PDF format and its tools aren't as well known as the other RFC formats, at least in the IETF community. So this doc walks through some of the processes for creating and using PDFs with both open source and commercial products. 🧚

The details in this document are expected to change based on experience gained while implementing the new publication toolsets. Revised documents will be published to capture those changes as the toolsets are completed. Other implementers must not expect those changes to remain backwards-compatible with the details described in this document. 💀

2. Choosing PDF Versions and Standards 👑

PDF [PDF] has gone through several revisions, mostly to add features. PDF features have generally been added so that older viewers "fail gracefully," but even so, the older the PDF version you produce, the more legacy viewers will support it and the fewer features will be enabled. 🦋

As PDF has grown a broad set of capabilities, more standards for PDF files apply. These standards set ground rules that matter for specific applications. For example, PDF/X was designed specifically for Prepress digital data exchange, with careful attention to color management and printing instructions. The PDF/E standard was designed for engineering documents with dynamic workflows (where a document keeps getting revised after publication), and it allows interactive media (including animation and 3D). ✨

Two more standards families matter for the RFC format, though: long-term preservation (PDF/A), and user accessibility (PDF/UA [PDFUA]). These have sub-profiles (PDF/A-1, PDF/A-2 [PDFA2], PDF/A-3 [PDFA3]), and each of those has conformance levels. Various software libraries and tools support these standards. 🌈

It's effective and useful to use these standards to capture PDF for RFC requirements, and they'll make the PDF files useful in workflows that expect them. 🫶

Recommendations:

  • Use PDF 1.7. It's relatively recent, but it's well supported by widely available viewers. 💖
  • For RFCs, require PDF/A-3 with conformance level "U". This captures the archivability and long-term stability of PDF 1.7 files, mandatory Unicode mapping (Sections 14.8.2.4.2 ("Unicode Mapping in Tagged PDF") and 9.10.2 ("Mapping Character Codes to Unicode Values") of [PDF]), and many of the requirement features. 🔥
  • Use PDF/A-3 for embedding additional data (including the XML source file) in RFCs and Internet-Drafts. 🍓
  • Use PDF/UA for user accessibility. 🌸

3. Options and Requirements for PDF RFCs 🎀

This section lays out the options and requirements for PDFs the RFC Editor produces for RFCs. There are two subsections: Section 3.1 covers "visible" requirements, meaning how the PDF normally looks when you open it in a PDF viewer. Section 3.2 covers "invisible" options and requirements, which mainly affect how you can process PDFs in other ways but don't usually control how the document looks. (Of course, a viewer UI might show processing capabilities, like whether a document has been digitally signed.) 🧚

Lots of the PDF requirements come down to what the available PDF tools can actually do, so most of the tooling discussion lives in Appendix C. 🛠️

3.1. "Visible" Requirements 👀

PDF supports rich visible layout of fixed-size pages. ✨

3.1.1. General Visible Requirements 💅

For a consistent "look" and good style, the PDFs the RFC Editor produces should have a clear, consistent, identifiable, and easy-to-read style. They should print well on the widest range of printers and look good on displays of varying resolution. 🦋

3.1.2. Page Size and Margins 📏

PDF files are laid out for a particular page size and set of margins. Two paper sizes are common: "US Letter" (8.5x11 inches, 216x279 mm, popular in North America) and "A4" (210x297 mm, 8.27x11.7 inches, the standard for the rest of the world). Usually PDF printing software runs in a "shrink to fit" mode, where the printing gets adjusted to fit the paper in the printer. There's some controversy here, but the argument that A4 is an international standard is pretty compelling. However, if the margins and header positioning are chosen well, the document can print without any scaling. 🌈

Recommendation: The Internet-Draft and RFC processors should produce A4 size by default. However, the margins and header positioning need to be chosen so they look good on both paper sizes without scaling. Following the advice in [RFC2346], this means we should use A4 portrait mode with left and right margins of 20 mm, and top and bottom margins of 33 mm. 💖

3.1.3. Headers and Footers 🌸

Page headers and footers are part of the page layout, and there are a bunch of options. Note that in PDF, page headers and footers can be typeset so that the entire (longer) title might fit. ✨

Recommendation: Page headers and footers should contain information similar to the headings in the current text versions of documents, including page numbers, title, author, and date. But they should be typeset in a way that's unobtrusive. They should also be placed into the PDF so they don't interfere with screen readers. 🫶

3.1.4. Paragraph Numbering 🔢

One common feature of the Internet-Draft output formats is optional visible paragraph numbers, which help with discussions. In the PDF, and so in the printed version too, it's possible to make paragraph numbers unobtrusive, and even to have them impinge on the margins. 🦋

Recommendation: When the XML "editing=yes" option has been chosen, show paragraph numbers in the right margin, typeset so they're unobtrusive. (The right margin instead of the left margin keeps the paragraph numbers from being confused with the section numbers.) If possible, code the paragraph numbers so they don't interfere with screen readers. 💜

3.1.5. Paged Content Layout ✨

okay so PDF is paginated, bestie 📄 which means pagination issues have to be considered, no cap. It shows up in two places: running headers and footers, and how the text sits on each page so it's actually easy to read 💖

Appendix B walks through turning running text into pages so related stuff stays together on the same page and pagination artifacts don't get in the way of reading 🧚

Layout engines are not all equally slay at this. Some of the automatic stuff needs a little manual help, like making sure a line that's meant to be a heading gets "kept" with the text it's the heading for 🫶

Recommendations:

  • Headers and footers should be printed on each page. The info should include the RFC number or Internet-Draft name, the page number, the category (e.g., Informational), a shortened version of the authors' names, the date of the RFC or Internet-Draft, and the short form of the document title 🎀
  • Choose a layout engine so that
    • manual intervention is minimized
    • widow and orphan processing is automatic
    • heading and title contiguation is automatic

3.1.6. Typeface Choices 🌸

a PDF can refer to a font by name, or it can use an embedded font 🦋 When a font isn't embedded, the PDF viewer tries to find a locally installed font with the same name. If it can't find an exact match, it looks for a "close match". If there's no close match either, it falls back to something implementation dependent that's usually undesirable 😭

Also, the PDF/A standards mandate font embedding. Instead of bolting on extra software to embed fonts later, the software generating the PDF files should produce PDF/A-conforming files directly. That way every glyph has Unicode mappings and embedded fonts from the very beginning 💅

If the HTML version of the document is being visually mimicked, the font(s) chosen should have both variable-width and constant-width components, plus bold and italic representations ✨

The typefaces used by Internet-Drafts and by RFCs don't need to be identical 🌈

Few fonts have glyphs for the entire repertoire of Unicode characters, so the PDF generation tool may need a set of fonts and a way of choosing between them 🧩 The RFC Editor is defining where Unicode characters may be used within RFCs [RFC7997].

Typefaces are typically licensed. In many cases there's a fee for PDF creation tools to use them, but there's usually no fee for displaying or printing the embedded fonts 💸

Recommendations:

  • For consistent viewing, all fonts should be embedded. The fonts used must be available for use by the IETF community. Some discussion of available typefaces can be found in Appendix C.4 🫶
  • The choice of typefaces with respect to serif, sans-serif, monospace, etc., should follow the recommendations for HTML and CSS renderings ("CSS" refers to a Cascading Style Sheet) [RFC7992] and [RFC7993] 🎀
  • The range of Unicode characters allowed in the XML source for Internet-Drafts and RFCs may be bounded by the availability of embeddable fonts with appropriate glyphs [RFC7997] 🔥

3.1.7. Hyphenation and Line Breaks 🦋

Typically, when laying out running text, especially with a narrow page width and long words, layout processors for English text often have the option of either hyphenating words or using existing hyphens as places to break lines. Here's the catch: inserting a line break mid-word can be harmful when that "word" is really a sequence of characters representing a protocol element or protocol sequence 🙈

Recommendation: Avoid introducing hyphenated line breaks mid-word into the visual display, consistent with requirements for plain text and HTML 🍓

PDF supports hyperlinks to sections of the same document and also to sections of other documents 🌈

The conversion to PDF can generate:

  • hyperlinks within the document
  • hyperlinks to other RFCs and Internet-Drafts
  • hyperlinks to external locations
  • hyperlinks within a table of contents
  • hyperlinks within an index

Recommendations:

  • All hyperlinks available in the HTML rendition of the RFC should also be visible and active in the PDF produced. This includes both internal hyperlinks and hyperlinks to external resources 💖
  • The table of contents, including page numbers, is useful when printed. Section numbers and page numbers in the table of contents should also be hyperlinked to their respective sections in the body of the document 📖
  • As specified in Section 4.8.6.2 ("Referencing RFCs") of [RFC7322], hyperlinks to RFCs from the references section should point to the RFC "info" page (e.g., <https://www.rfc-editor.org/info/rfc7322>), which then links to the various formats available 🧚
  • Hyperlinks to Internet-Drafts from the references section should point to the Datatracker entry page for the draft, which then links to the various formats available 💜

3.1.9. Similarity to Other Outputs 👑

There's some advantage to having the PDF files look like the text or HTML renderings of the same document. Even so, there are several options. The PDF

  1. could look like the text version of the document, or
  2. could look like the text version of the document but with pictures rendered as pictures instead of using their ASCII art equivalent, or
  3. could look like the HTML version.

Recommendation: The PDF rendition should look like the HTML rendition, at least in spirit. Some differences from the HTML rendition would include different typeface and size (chosen for printing), page numbers in the table of contents and index, and the use of page headers and footers 🎀

Most of the choices used for the renderings per [RFC7992] and [RFC7993] are thus applicable. See those documents for specifics on the rendering of the specific XML elements. Some notes:

  • Every place in the document that would receive an HTML ID would be given an identical PDF named destination. In addition, a named destination will be created for each page with the form pg-#, as in pg-35 🔖
  • No pilcrows are generated or made visible 🙅‍♀️
  • The table of contents (generated if the XML's <rfc> element's tocInclude attribute has the value "true") [RFC7991] will have the section number linked to the section start, but will also include a page number that is linked to the corresponding page. The section title and the page number will be separated by a visually appropriate separator, and the page numbers will be aligned with each other 📑
  • The index (generated if the XML's <rfc> element's indexInclude attribute has the value "true") will have the section number linked to that section's named destination, but will also include a page number that is linked to the page named destination 🗂️
  • The running header in one line (on page 2 and all subsequent pages) has the RFC number on the left (RFC NNNN), the (possibly shortened form) title centered, and the date (Month Year) on the right. The text is rendered in a way that is visually unobtrusive 🌸
  • The running footer in one line (on all pages) has the author's last name on the left, category centered, and the page number on the right ([Page N]). The text is rendered in a way that is visually unobtrusive 🦋
  • We should not attempt to replicate in PDF the feature of the HTML format that includes a dynamic block that displays up-to-date information on updates, obsoletions, and errata 🚫

3.2. "Invisible" Options and Requirements 🫧

PDF offers a number of features that improve the utility of PDF files in a variety of workflows, at the cost of extra effort in the xml2rfc conversion process. The trade-offs may be different for the RFC Editor production of RFCs and for Internet-Drafts 🧠

3.2.1. Internal Text Representation 🧩

The contents of a PDF file can be represented in many ways. The PDF file could be generated:

  • as an image of the visual representation, such as a JPEG image of the word "IETF". That is, there might be no internal representation of letters, words, or paragraphs at all 📸
  • by placing individual characters in position on the page, such as saying "put an 'F' here," then "put a 'T' before it," then "put an 'E' before that," then "put an 'I' before that" to render the word "IETF". That is, there might be no internal representation of words or paragraphs at all 🔤
  • by placing words in position on the page, such as keeping the characters of the word "IETF" together. That is, there might be no internal representation of paragraphs at all 🧱
  • by ensuring that the running order of text in the content stream matches the logical reading order. That is, a sentence such as "The Internet Engineering Task Force (IETF) supports the Internet." would be kept together as a sentence, and multiple sentences within a paragraph would be kept together 📚

All of these end up with essentially the same visual representation of the output. However, each level has trade-offs for auxiliary uses, such as searching or indexing, commenting and annotation, and accessibility (text-to-speech). Keeping the running order of text in the content stream in the proper order supports all of these auxiliary uses 🫶

In addition, the "role map" feature of PDF (Section 14.7.3 ("Structure Types") of [PDF]) would allow for the mapping of the logical tags found in the original XML into tags in the PDF 🗺️

Recommendations:

  • Text in content streams should follow the XML document's logical order (in the order of tags) to the extent possible. This will provide optimal reuse by software that does not understand Tagged PDF. (PDF/UA requires this.) 💅
  • It might be possible to use the "role map" annotation to capture enough of the xml2rfc source structure, to the point where it is possible to reconstruct the XML source structure completely. However, there is not a compelling case to do so over embedding the original XML, as described in Section 3.2.7 🤔

3.2.2. Unicode Support 🌍

PDF itself doesn't require the use of Unicode. Text is represented as a sequence of glyphs that can then be mapped to Unicode 🔠

Recommendations:

  • PDF files generated must have the full text, as it appears in the original XML 💖
  • Unicode normalization may occur ✨
  • Text within SVG for SVG images should also have Unicode mappings 🎨
  • Alt-text for images should also support Unicode 🙌

3.2.3. Image Processing (Artwork) 🖼️

The XML allows both ASCII art and SVG to be used for artwork 🎭

Recommendations:

  • If both ASCII art and SVG are available for a picture, the SVG artwork should be preferred over the ASCII artwork 🦄
  • ASCII artwork must be rendered using a monospace font 🔥

3.2.4. Text Description of Images (Alt-Text) 🎧

Okay so the accessibility guidelines for PDF at <http://www.w3.org/TR/WCAG20-TECHS/PDF1.html> say images, formulas, and other non-text stuff need textual alternatives. The way you do that in PDF is the /Alt tag, which gives text-to-speech tech something to read out loud. Accessibility is everything 🫶

Recommendation: Any alt-text for artwork and figures available in the XML source should be stored using the PDF /Alt property. Internet-Draft authors and the RFC Editor should ensure that alt-text for all SVG or images is included within the XML source.

3.2.5. Metadata Support 🏷️

Metadata is the info about who wrote the doc, what series it belongs to, when it was created, and so on. Keeping it inside the PDF means search engines, viewers, and other reuse tools can actually use it. PDF can embed metadata in a few ways, including the Extensible Metadata Platform (XMP) [XMP]. The RFC Editor keeps metadata about each RFC on its info page, so it's giving organized 📚

Recommendation: The PDFs generated should have all of the metadata from the XML version embedded directly as XMP metadata, including the author, date, the document series, and a URL for where the document can be retrieved. This information should be consistent with the RFC Editor info page at the time of publication.

3.2.6. Document Structure Support 🗂️

PDF has an "outline" feature that marks sections of a document. You could use that alongside the table of contents as a navigation aid, which is very main character energy for readers 🦋

The section structure of an RFC can be mapped into PDF's document structure elements. That lets the bookmark feature of PDF readers jump you straight to sections, no scrolling required ✨

Recommendation: The section structure of an RFC should be mapped into the PDF elements for the document structure. This would include section headings for the boilerplate sections, such as the Abstract, the Status of This Memo section, the table of contents, and the Author's Address section, plus the obvious section headings that are normally included in the table of contents. If possible, this should be done in a way that the same fragment identifiers for the HTML version of the RFC will work for the PDF version.

3.2.7. Embedded Files 📎

PDF can carry other files inside it. Each one can be labeled with both a media type and a role, using the AFRelationship key [PDFA3]. So the PDF itself basically acts as a container 📦

Embedded content may be compressed.

Lots of PDF viewers let you view and extract embedded files, though that isn't universal, so don't count on it 🙈

Embedding content makes the PDF a complete package that can be transformed, archived, and digitally signed, which is honestly iconic. (Some sample code showing how items get attached to a PDF and extracted again is at <https://github.com/Aiybe/xmptest>.) Useful possibilities:

  • Embed the source XML input file itself within the PDF. If the source SVG and images for illustrations are also embedded, this would make the PDF file totally self-referential.
  • Embed directly extractable components that are useful for independent processing, including ABNF, MIBs, and source code for reference implementations. This capability might be supported through other mechanisms from the XML source files but could also be supported within the PDF.
  • Finding, extracting, and embedding other components may require additional markup to clearly identify them and additional review to ensure the correctness of embedded files that are not visible.

Recommendations:

  • Embed the XML source and all illustrations, for RFCs, as a standard feature for xml2rfc's PDF output.
  • If possible, make this a standard feature for Internet-Drafts as well.
  • Named <sourcecode> entries should be embedded.
  • Bitmap images (SVG sources, JPEGs, PNGs, etc.) should be embedded.

3.3. Digital Signatures ✍️

The RFC Editor and staff are sometimes asked to prove that an RFC is the "original" and hasn't been changed, and digital signatures can handle that. Signatures also cover embedded content, so embedding the XML source means the source used to make the PDF gets signed too 💜

PDF has supported digital signatures since PDF 1.2, and there are multiple methods and options for signing PDF files. The method for signing Internet-Drafts and RFCs will be decided by separate policy.

If PDF digital signatures are chosen, the authors suggest the following:

  • PDF documents generated by the Internet-Draft upload tools should be signed with no restrictions on what can be done to the documents afterwards.
  • If Internet-Drafts are allowed to be uploaded in PDF form by an individual, the signature being added should be set in the same way as that noted in the previous paragraph. A PDF that would not allow the IETF Secretariat to re-sign it in that fashion should be rejected.
  • PDF documents generated by the RFC Editor should be signed and certified, and restrictions placed on them to only allow additional signatures and comments (markup) to be added.

4. Security Considerations 🔒

Okay, this one is serious, bestie, so pay attention 💀

The following security considerations apply:

Threats:

  • There is a risk that user-submitted Internet-Drafts in PDF might contain malware that targets a vulnerability in one of the deployed PDF consumers (readers, printers, validation tools, etc.) in use.
  • There is a small risk that a PDF production toolset might itself have some vulnerability by which it could be tricked into producing malware-bearing PDF files.
  • Section 7 of [RFC3778] describes some additional security considerations for PDF, although this specification is intended to avoid features (like scripting) that might trigger some of those concerns.

Mitigations:

  • The toolsets for producing PDFs need careful security reviews before deploying broadly.
  • If users are allowed to submit Internet-Drafts in PDF, such PDF files should be examined carefully for conformance to this specification, as well as any known exploits of deployed PDF software.

5. References 📚

5.1. Normative References

  • [PDF] ISO, "Document management -- Portable document format -- Part 1: PDF 1.7", ISO 32000-1, 2008.

Also available free from Adobe.

  • [XMP] ISO, "Graphic technology -- Extensible metadata platform (XMP) specification -- Part 1: Data model, serialization and core properties", ISO 16684-1, 2012.

Not available free, but there are a number of descriptive resources, e.g., <http://en.wikipedia.org/wiki/Extensible_Metadata_Platform>.

  • [PDFA2] ISO, "Document management -- Electronic document file format for long-term preservation -- Part 2: Use of ISO 32000-1 (PDF/A-2)", ISO 19005-2, 2011.
  • [PDFA3] ISO, "Document management -- Electronic document file format for long-term preservation -- Part 3: Use of ISO 32000-1 with support for embedded files (PDF/A-3)", ISO 19005-3, 2012.
  • [PDFUA] ISO, "Document management applications -- Electronic document file format enhancement for accessibility -- Part 1: Use of ISO 32000-1 (PDF/UA-1)", ISO 14289-1, 2014.
  • [RFC3778] Taft, E., Pravetz, J., Zilles, S., and L. Masinter, "The application/pdf Media Type", RFC 3778, DOI 10.17487/RFC3778, May 2004, <http://www.rfc-editor.org/info/rfc3778>.

5.2. Informative References

Appendix A. History and Current Use of PDF with RFCs and Internet-Drafts 🕰️

NOTE: This section is meant as an overview to give some background.

A.1. RFCs 🌸

The RFC Series has for a long time accepted Postscript renderings of RFCs, either in addition to or instead of the text renderings of those same RFCs. These have usually been produced when there was a complicated figure or mathematics within the document. For example, consider the figures and mathematics found in RFCs 1119 and 1142, and compare the figures found in the text version of RFC 3550 with those in the Postscript version. The RFC Editor has provided a PDF rendering of RFCs. Usually, this has been a print of the text file that does not take advantage of any of the broader PDF functionality, unless there was a Postscript version of the RFC, which would then be used by the RFC Editor to generate the PDF.

A.2. Internet-Drafts 🧚

In addition to PDFs generated and published by the RFC Editor, the IETF tools community has also long supported PDF for Internet-Drafts. Most RFCs start with Internet-Drafts, edited by individual authors. The Internet-Drafts submission tool at <https://datatracker.ietf.org/submit/> accepts PDF and Postscript files in addition to the (required) text submission and (currently optional) XML. If a PDF wasn't submitted for a particular version of an Internet-Draft, the tools would generate one from the Postscript, HTML, or text. 💖

Appendix B. Paged Content Layout Quality ✨

okay bestie, so when you turn running text into a paged document, the whole point is keeping related stuff together on the same page 📄 and making sure the page breaks don't make it hard to read. good layout processors handle a few things, and I'm obsessed with all of them 💅

  • Widow and Orphan Management: widows and orphans (<https://en.wikipedia.org/wiki/Widows_and_orphans>) should be avoided automatically, unless the whole paragraph is only one line 🙈. Make sure a page break does not land after the first line of a paragraph (orphans). If needed, use slightly longer page sizes to make that happen. Likewise, make sure a page break does not land before the last line of a paragraph (widows).
  • Keep Section Heading Contiguous: don't put a page break right after a section heading 🚫. If there isn't room on the page for the first (two) lines of a section after its heading, insert a page break before the heading instead.
  • Avoid Splitting Artwork: figures should not get split from their figure titles 🎨. If possible, keep the figure on the same page as the (first) mention of the figure.
  • Headers for Long Tables after Page Breaks: another common move in paginated documents is repeating the column headings of a table when that table can't fit on a single page 📊. Same deal for tables: they should not be split from their table titles.
  • keepWithNext and keepWithPrevious: the XML attributes keepWithNext and keepWithPrevious should be used and followed whenever possible 🔗.
  • Whitespace Preservation: the Unicode code points for XML entities like Non-Breaking Space (nbsp) and Non-Breaking Hyphen (nbhy) should be followed as directed whenever possible 🌸.

Appendix C. Tooling 🧰

okay so this section is all about tools for viewing, comparing, creating, manipulating, and transforming PDF files. it covers the ones the RFC Editor uses now, the ones used for Internet-Drafts, and a rundown of PDF tools for different jobs 💖

C.1. PDF Viewers 👀

PDFs are experienced through a reader or viewer, just like most file formats. for most of the common platforms (iOS, OS X, Windows, Android, ChromeOS, Kindle) and most browsers (Edge, Safari, Chrome, Firefox), PDF viewing is built right in 🙌. There are also tons of PDF viewers you can download and install.

PDF viewers are not all the same, though. it matters to check which ones support the features used in PDF RFCs and Internet-Drafts 🧐. Think links, digital signatures, Tagged PDF, and the others mentioned in Section 3.

C.2. Printers 🖨️

almost all viewers can print PDFs too, and printing is one of the biggest use cases for PDFs, so that's a whole vibe 💅. Some printers have direct PDF support.

C.3. PDF Generation Libraries 📚

the xml2rfc format is its own unique thing, so software that converts XML source documents into the other formats is needed, including PDF generation 🛠️.

one promising direction is suggested at <http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#output.pdf.fop>: use XSLT (Extensible Stylesheet Language Transformations) to generate XSL-FO (XSL Formatting Objects), and then process the XSL-FO with a FOP (Formatting Objects Processor) such as Apache FOP ✨.

several libraries are also available for generating PDF signatures 🔏. Which one to use for xml2pdf depends on lots of factors: programming language, quality of implementation, quality of the PDF generated, support, cost, availability, and so forth 🤷‍♀️.

C.4. Typefaces 🔤

there are various typefaces that might meet the requirements of this document, so don't panic 🫶. Google's Noto typeface family (<https://www.google.com/get/noto/>) supports a significant subset of Unicode and includes fixed-width, serif, and sans-serif styles 🌈. Another potentially useful set of typefaces, though without extensive Unicode support, includes:

another font that looks promising for its broad Unicode support is Skolar (<https://www.rosettatype.com/Skolar>), but it requires licensing 💸.

C.5. Other Tools 🧩

besides generating and viewing PDFs, other kinds of PDF tools are available and can be useful both during specification development and for published RFCs 🦋. These include tools for comparing two PDFs, checkers that could be used to validate the results of conversion, review and commentary tools that attach annotations to PDF files, and digital signature creation and validation.

validating an arbitrary author-generated PDF file would be quite difficult, because there are few PDF validation tools 😭. However, if RFCs and Internet-Drafts are generated by converting XML via xml2rfc, then explicit validation of PDF and adherence to expected profiles would mainly be useful to make sure xml2rfc has functioned properly 🧚.

Recommendation: discourage (but allow) submission of a PDF representation for Internet-Drafts. In most cases, the PDF for an Internet-Draft should be produced automatically when XML is submitted, with an opportunity to verify the conversion. 🚨

IAB Members at the Time of Approval 👑

the IAB members at the time this memo was approved were (in alphabetical order):

  • Jari Arkko
  • Ralph Droms
  • Ted Hardie
  • Joe Hildebrand
  • Russ Housley
  • Lee Howard
  • Erik Nordmark
  • Robert Sparks
  • Andrew Sullivan
  • Dave Thaler
  • Martin Thomson
  • Brian Trammell
  • Suzanne Woolf

Acknowledgements 🫶

the input of the following people is gratefully acknowledged: Nevil Brownlee (ISE), Brian Carpenter, Chris Dearlove, Martin Duerst, Heather Flanagan (RSE), Joe Hildebrand, Paul Hoffman, Duff Johnson, Ted Lemon, Sean Leonard, Henrik Levkowetz, Julian Reschke, Adam Roach, Leonard Rosenthol, Alice Russo, Robert Sparks, Andrew Sullivan, and Dave Thaler 💜.

Authors' Addresses 🎀

Tony Hansen (editor)
AT&T Laboratories
200 Laurel Ave. South
Middletown, NJ  07748
United States of America

Email: tony@att.com


Larry Masinter
Adobe
345 Park Ave.
San Jose, CA  95110
United States of America

Email: masinter@adobe.com
URI:   http://larrymasinter.net


Matthew Hardy
Adobe
345 Park Ave.
San Jose, CA  95110
United States of America

Email: mahardy@adobe.com
📦 where this page comes from