RFC 7995 - PDF Format for RFCs

This document discusses options and requirements for the PDF rendering of RFCs in the RFC Series, as outlined in RFC 6949. It also discusses the use of PDF for Internet-Drafts, and available or needed software tools for producing and working with PDF.¶

3. Options and Requirements for PDF RFCs

This section lays out options and requirements for PDFs produced by the RFC Editor for RFCs. There are two subsections: Section 3.1 covers "visible" requirements related to how the PDF normally appears when it is viewed with a PDF viewer; Section 3.2 covers "invisible" options and requirements, which primarily affect the ability to process PDFs in other ways but do not ordinarily control the way the document appears. (Of course, a viewer UI might display processing capabilities, such as showing whether a document has been digitally signed.)¶

In many cases, the choice of PDF requirements is heavily influenced by the capabilities of available tools to create PDFs. Most of the discussion of tooling is to be found in Appendix C.¶

3.1. "Visible" Requirements

PDF supports rich visible layout of fixed-sized pages.¶

3.1.1. General Visible Requirements

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

3.1.2. Page Size and Margins

PDF files are laid out for a particular size of page and margins. There are two paper sizes in common use: "US Letter" (8.5x11 inches, 216x279 mm, in popular use in North America) and "A4" (210x297 mm, 8.27x11.7 inches, standard for the rest of the world). Usually, PDF printing software is used in a "shrink to fit" mode where the printing is adjusted to fit the paper in the printer. There is some controversy, but the argument that A4 is an international standard is compelling. However, if the margins and header positioning are chosen appropriately, the document can be printed 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 to look good on both paper sizes without scaling. Following the advice found in [RFC2346], this means that 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. There are a variety of options. Note that page headers and footers in PDF can be typeset in a way 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. However, the page headers and footers should be typeset in a way so as to be unobtrusive. The page headers and footers should be placed into the PDF in such a way that they do not interfere with screen readers.

3.1.4. Paragraph Numbering

One common feature of the Internet-Draft output formats is optional visible paragraph numbers, to aid in discussions. In the PDF, and thus in the printed rendition, it is possible to make paragraph numbers unobtrusive and even to impinge on the margins.¶

Recommendation:: When the XML "editing=yes" option has been chosen, show paragraph numbers in the right margin, typeset in a way so as to be unobtrusive. (The right margin instead of the left margin prevents the paragraph numbers from being confused with the section numbers.) If possible, the paragraph numbers should be coded in such a way that they do not interfere with screen readers.

3.1.5. Paged Content Layout

By its nature, PDF is paginated, so pagination issues must be considered. This is reflected in two areas: running headers and footers, and how text is laid out on a page for optimal reading.¶

Appendix B describes the process of creating a paged document from running text such that related material is present on the same page together and artifacts of pagination don't interfere with easy reading of the document.¶

Layout engines differ in the quality of the algorithms used to automate these processes. In some cases, the automated processes require some manual assistance to ensure, for example, that a text line intended as a heading is "kept" with the text for which it is a heading.¶

Recommendations: ¶

Headers and footers should be printed on each page. The information 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 may refer to a font by name, or it may use an embedded font. When a font is not embedded, a PDF viewer will attempt to locate a locally installed font of the same name. If it cannot find an exact match, it will find a "close match". If a close match is not available, it will fall back to something implementation dependent and usually undesirable.¶

In addition, the PDF/A standards mandate the embedding of fonts. Instead of using additional software to embed the fonts, the software generating the PDF files should produce PDF/A-conforming files directly, thus ensuring that all glyphs include Unicode mappings and embedded fonts from the outset.¶

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

The typefaces used by Internet-Drafts and by RFCs need not be identical.¶

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

Typefaces are typically licensed, and in many cases there is a fee for use by PDF creation tools; however, there is usually no fee for display or print of 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 doing page layout of running text, especially with narrow page width and long words, layout processors of English text often have the option of either hyphenating words or using existing hyphens as a place to introduce word breaks. However, inserting line breaks mid-word can be harmful when the "word" is actually 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.

3.1.8. Hyperlinks

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 is 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 ¶

could look like the text version of the document, or
could look like the text version of the document but with pictures rendered as pictures instead of using their ASCII art equivalent, or
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 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.
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.
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.
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 does not 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)

Guidelines for the accessibility of PDF <http://www.w3.org/TR/WCAG20-TECHS/PDF1.html> recommend that images, formulas, and other non-text items provide textual alternatives, using the "/Alt" Tag in PDF to provide human-readable text that can be vocalized by text-to-speech technology.¶

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 encodes information about the document authors, the document series, date created, etc. Having this metadata within the PDF file allows it to be used by search engines, viewers, and other reuse tools. PDF supports embedded metadata in a variety of ways, including using the Extensible Metadata Platform (XMP) [XMP]. The RFC Editor maintains metadata about an RFC on its info page.¶

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 supports an "outline" feature where sections of the document are marked; this could be used in addition to the table of contents as a navigation aid.¶

The section structure of an RFC can be mapped into the PDF elements for the document structure. This will allow the bookmark feature of PDF readers to be used to quickly access sections of the document.¶

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 has the capability of including other files; the files may be labeled by both a media type and a role, the AFRelationship key [PDFA3]. In this way, the PDF file also acts as a container.¶

Embedded content may be compressed.¶

Many PDF viewers support the ability to view and extract embedded files, although this capability is not universal.¶

Embedding content in the PDF file allows the PDF to act as a complete package that can be transformed, archived, and digitally signed. (Some sample code illustrating how items can be attached to a PDF file and subsequently extracted can be found 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 at times called to provide evidence that a particular RFC is the "original" and has not been modified; digital signatures can provide that verification. As signatures also apply to embedded content, embedding the XML source will provide a way of signing the source XML that was used to produce the PDF file as well.¶

PDF has supported digital signatures since PDF 1.2, and there are multiple methods and options available for signing PDF files. The method chosen for the signing of Internet-Drafts and RFCs will be determined 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.