Images in RFCs
draft-rfc-image-files-00.txt

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on February 23, 2009.

Abstract

Documents in the RFC series normally use only plain-text ASCII characters and a fixed-width font. However, there is sometimes a need to supplement the ASCII text with graphics or picture images. The historic solution to this requirement, allowing secondary PDF and Postscript files, is seldom used because it is awkward for authors and publisher. This memo sugests a more convenient scheme for attaching authoritative diagrams, llustrations, or other graphics to RFCs.

Table of Contents

1.  Introduction
2.  A New Scheme for Images
3.  Construction of the Image File
4.  Requirements for the Base File
    4.1.  Overview
    4.2.  Figures Section
    4.3.  Formatting Changes
5.  Submission and Processing of the Image File
6.  Implementation Issues
7.  RFC Repository File Formats
8.  Internationalization Considerations
9.  Security Considerations
10.  IANA Considerations
11.  Acknowledgments
12.  References
    12.1.  Normative References
    12.2.  Informative References
§  Authors' Addresses
§  Intellectual Property and Copyright Statements

1.  Introduction

Published documents in the RFC series normally use only plain-text ASCII characters and a fixed-width font [RFC2223] (Postel, J. and J. Reynolds, “Instructions to RFC Authors,” October 1997.). This simple convention has the advantage of a stable encoding for which a wide variety of tools are readily available for viewing, searching, editing, etc..

Inclusion of diagrams, state machines, and other graphics in RFC text has generally relied on the imaginative use of ASCII characters ("ASCII artwork".) However, in a few cases over the years, ASCII artwork has been inadequate for images needed or desired in RFCs. The old solution to this dilemma has been to allow three versions of an RFC: a primary ASCII version and secondary versions that are encoded using PDF and Postcript. The PDF and Postscript versions are "complete", containing a copy of the text as well as the full images [RFC2223] (Postel, J. and J. Reynolds, “Instructions to RFC Authors,” October 1997.). The textual content and layout of the PDF/PS version is required to match the base version as closely as possible. However, the ASCII text version is considered the official expression of the RFC, and it is always normative for standards track documents. We will refer to this old approach as ".txt+.pdf+.ps" encoding.

The three versions of an RFC using .txt+.pdf+.ps encoding are in separate files in the primary RFC repository (http://www.rfc-editor.org/rfc/"), with suffixes ".txt", ".pdf", and ".ps". The RFC Editor search engine returns links to all three versions when they are present in the repository.

Unfortunately, the .txt+.pdf+.ps scheme has been awkward for both editor and author, and it is error-prone, so it has seldom been used (roughly 50 out of 5000+ RFCs). The problem is that, in general, only the author has the tools to prepare the PDF and Postscript versions. The RFC Editor edits (only) the primary text version, and then the author must incorporate all the resulting changes into the PDF/PS version while maintaining the "look" of the RFC to the extent possible. There is no practical way for the RFC Editor to verify that this is done correctly, perhaps leading to editorial errors and usually lengthening publication time for these documents.

This memo suggests a much better scheme for including figures, illustrations, and graphics to an RFC. We hope that the method proposed here will solve the image problem for RFC publication, although the .txt+.pdf+.ps approach would still be possible (and in any case, RFCs using the historic scheme will continue to exist in the RFC repository forever).

2.  A New Scheme for Images

Under our scheme, an RFC may be either a single ASCII file as commonly used today, or a composite of two files: an ASCII-only "base file" containing the text of the RFC, and an "image file". When present, the image file would be a PDF file that contained only images, captions, and title information. Neither file of the composite would be complete without the other, and a reference to the RFC would be considered a reference to both files. An RFC would then be a logical entity whose complete representation could require two files, base and image.

The base file would be formatted exactly like current ASCII RFCs, with three minor exceptions described below.

The intellectual property boilerplate in the base file ("Rights in Contributions BCP 78, RFC 4748 (Bradner, S., “RFC 3978 Update to Recognize the IETF Trust,” October 2006.) [RFC4748] ) would apply equally to the image file. An image file would contain one or more items that will be known collectively as "figures", whether they are actually diagrams, pictures, tables, artwork, or other non-textual constructions.

This scheme was inspired by the tradition in book publishing, where pictures, figures, or "plates" may be grouped together following the text ("end figures"), or even bound separately from the main body of the text.

In principle, we could allow an image file to be encoded using both PDF and Postscript, since mechanical translation is possible in both directions. However, in the 20 years since the adoption of the .txt+.pdf+.ps scheme, the PDF format has become a defacto standard for electronic documents, and readers for it are universally available. Furthermore, PDF is being standardized as a format for document archiving, as discussed further in the next section. Therefore, we propose to allow only PDF for image files, simplifying the new approach by not including a Postscript file option.

An ASCII RFC traditionally uses a file name in the form of "rfcN.txt", where N is integer RFC number without leading zeros. The image file that is associated with RFC number N could be named "rfcN.img.pdf". As noted earlier, the repository contains RFCs with file names "rfcN.ps" and "rfcN.pdf", using the historic .txt+.pdf+.ps scheme.

3.  Construction of the Image File

An image file would be a single PDF file, consistent with the description in [RFC3778] (Taft, E., Pravetz, J., Zilles, S., and L. Masinter, “The application/pdf Media Type,” May 2004.) and defined in [ISO32000‑1] (International Organization for Standardization (ISO), “Document management -- Portable document format -- Part 1: PDF 1.7,” 2008.). The particular PDF form must be version-stable and must not contain any external references in scripts or otherwise. Those requirements are satisfied by the PDF/A (International Organization for Standardization (ISO), “Document management -- Electronic document file format for long-term preservation -- Part 1: Use of PDF 1.4 (PDF/A-1),” 2005.) [ISO19005‑1] profile. The RFC Editor may authorize other variants of PDF in the future.

There is an issue of whether particular generators of PDF that claim to satisfy PDF/A actually do so. Future experience may require published guidelines on PDF-generating software that claims to satisfy PDF/A but does not.

Except as otherwise specified in this document, an image file should contain only figures, supporting labels and captions, headers, and footers. It should not contain explanatory text or other materials that could reasonably be expressed in plain-text form in the base file

Pages of the image file would be consecutively numbered. The first page number of the image file would follow the last page number of the base RFC, exclusive of the number of the end-of-RFC boilerplate page. The page number of the end-of-RFC boilerplate (in the base RFC file) would be the first page number after those in the image file. Each page of the image file would contain the same headers and footers as the base file, except for one change in the footer, suggested below.

Figures included in the image file would have to be labeled in a fashion that facilitated referencing from the base RFC. They should normally be numeric and monotonic. Simple consecutive integer will usually be the best choice, but in some cases it might be desirable to use a hierarchical scheme like: <section #>.<fig #>. An author who believes that another labeling scheme would increase clarity should check with the RFC Editor.

4.  Requirements for the Base File

4.1.  Overview

A base file would be unchanged by the presence of an image file, except for the following.

• The page number of the end-of-RFC boilerplate page would be changed to be logically one page after the last image file page.
• A new unnumbered "Figures" section would be required. This is described below.
• For a composite RFC, a minor modification to the first-page header of the base file and to the footers of both base and image files could tie the two files together. This is described below.

4.2.  Figures Section

An RFC that used this scheme (and had any figures) would need to include a Figures section in the ASCII base file. The Figures section should immediately following the Table of Contents, if any, and precede the body of the document. The Figures section should list all figures in tabular form, indicating for each one the figure identification, title, and page number(s).

The style for the Figures section has not yet been fully specified. Here is a suggested example.

___________________________________________________________________________
Table of Contents

  1. Introduction .................................................... 1
  2. Philosophy ...................................................... 7
      2.1 Elements of the Internetwork System ........................ 7
      2.2 Model of Operation ......................................... 8
      2.3 The Host Environment ....................................... 8
(etc)

Figures

  Figure 1: Protocol Layering . .....................................  2
  Figure 2: Protocol Relationships ..................................  9
  Figure 3: TCP Header Format .................................. 15, *86
  Figure 4: Send Sequence Space ..................................... 20
  Figure 5: Receive Sequence Space .................................. 20
  Figure 6: TCP Connection State Diagram ....................... 23, *87
  Figure 7: Basic 3-Way Handshake for Connection Synchronization 31, *88
(etc)

*Page in Image file

(Page 1 follows)
___________________________________________________________________________

An RFC that includes a base file may include ASCII artwork that is suggestive of a figure in the image file, but there is no requirement to do so. When such an approximate figure appears as ASCII artwork in the base file, its figure identification and caption must match those of the corresponding figure in the image file, and the entry in the Figures table should specify the page numbers in both the base and image file, In the example shown above, image file page numbers are marked with an asterisk. Note that very simple ASCII artwork need not appear in the image file.

4.3.  Formatting Changes

It would be necessary to tie the base and image files together, to make clear they are part of one RFC. Here is an initial suggestion for formatting, which needs further consideration before it is adopted.

The header line "Request for Comments: nnnn" in the base file could be changed to "Request for Comments: nnnn/Base". For consistency, the lefthand footer could become "RFC nnnn/Base". The lefthand footer in the image file could then be: "RFC nnnn/Image.

The following sentence could be placed in the "Status of this Memo" section: "This RFC is a composite of this base file and a PDF image file."

5.  Submission and Processing of the Image File

If an image file is needed, it should be submitted as an .img.pdf file along with the ASCII text file. The image file should be submitted without headers or footers. The RFC Editor will overlay the image file with the appropriate headers and footers, with correct pagination. The RFC Editor will not normally do any editing of the image file beyond this. If editing the base file reveals problems with figures in the image file, the authors will be asked to create a new image file.

6.  Implementation Issues

This acheme has a number of implications.

1. The Internet Draft repository must allow submission and retrieval of both base and (when present) image files.
2. Internet Draft file names could be draft-...-vv.txt and (optionally) draft-...-vv.img.pdf, where "vv" is the normal version number. Updating either file of the composite RFC should increase the version numbers "vv" in both files. We DO NOT want two separate version numbers for one I-D
3. The RFC Editor would need to be able to overlay headers, footers, and page numbers on a given image file. It is claimed that at least Adobe Acrobat Professional includes this capability, and that it also has limited editing capability.
4. The RFC Editor would also need a tool to verify that a given image file satisfies the constraints of PDF/A.
5. Some RFC Editor scripts and tools would need small extensions.
6. Some small extensions to xml2rfc to include image files would be useful. It should generate the boilerplate with a non-sequential page number. For example, an attribute on <back>, might specify the number of pages of image file. One could presumably add a mechanism to generate the Figures section.

7.  RFC Repository File Formats

A frequent reaction to the suggestion given in this memo is some confusion over the different file formats that appear in the RFC repository. Here is a brief summary.

If a PDF image file exists along with a base ASCII RFC, then RFCs in any other format (e.g., complete PDF files, HTML, or Postscript) remain supplemental, with the reader taking responsibility for assuring that they are equivalent to the base RFC and image file. That arrangement is identical to the relationship between traditional all-ASCII RFCs and supplemental forms: the RFC Editor has never taken responsibility for guaranteeing that the two are identical in content.

The existing .txt.pdf files are not affected by this proposal. The .txt.pdf files are facsimiles of .txt (base files) in PDF, introduced to help Windows users read RFCs online. However, Microsoft has more recently provided an elementary ASCII editor, which probably makes the .txt.pdf files unnecessary in any case.

In summary:

• .txt: ASCII-only file. In old scheme, complete normative file. In new scheme, text part of composite RFC, or stand-alone text file.
• .ps: Old scheme -- a Postscript file that includes figures and whose text is intended to be the same as the normative .txt file.
• .pdf: Old scheme -- a PDF file that includes figures and whose text is intended to be the same as the normative .txt file.
• .img.pdf: New scheme: image file part of a composite with .txt file.
• .txt.pdf: Old scheme: Facsimile of corresponding .txt file.

We note that it would be possible to combine the base and image files into a single PDF file, which would have to follow a naming convention to distinguish it from the .pdf case listed above. However, we regard this an an undesirable step away from the principle of universal ASCII encoding of the text of the document.

8.  Internationalization Considerations

Our scheme of image files does not, and is not intended to, support character set internationalization for RFCs. It does not allow an author to omit the ASCII text from the base file and instead include the entire RFC text as one (very large) image file.

However, we should note two special cases.

1. RFC 3743 [RFC3743] (Konishi, K., Huang, K., Qian, H., and Y. Ko, “Joint Engineering Team (JET) Guidelines for Internationalized Domain Names (IDN) Registration and Administration for Chinese, Japanese, and Korean,” April 2004.) on internationalized domain names for Chinese, Japanese,, and Korean contains a number of examples that may be hard to follow because they can represent those characters only in "U+nnnn" form. An image file could be used that would show the alternative Chinese characters for the examples. This would not diminish either the ability to search the base text or index the document or its readability for those of us for whom reading Chinese characters is difficult, but it should help those who can read them.
2. Suppose that a proposed RFC contained a section derived from Japanese text. The author might put an English translation into that section of the base document, note that the original was really in Japanese, and attach the Japanese as an appendix in an image file. This should raise no difficulties for informative documents. For normative documents, however, the existence of the Japanese original would raise some issues about what was actually authoritative, which is very undesirable.

9.  Security Considerations

This specifications addresses documentation standards and adding additional flexibility to them. It does not, in general, raise any security issues. However, unless the specifications of this document are carefully followed, the image format recommended, PDF, may potentially contain external references or scripts that could introduce security problems. The RFC Editor and other publishers should exercise due care to ensure that no such references or scripts appear in the archives.

10.  IANA Considerations

This document requires no actions by the IANA.

11.  Acknowledgments

The impetus for this specification arose during a discussion during an RFC Editorial Board meeting in the aftermath of one of the IETF's seeming-interminable discussions about allowing RFC's in "modern" formats. Aaron Falk made several specific suggestions that have been reflected in the document. The RFC Editor staff and other Editorial Board members contributed suggestions without which this version would not have been possible.

12.  References

12.1. Normative References

12.2. Informative References

Authors' Addresses

Full Copyright Statement

Copyright © The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.