Network Working Group R. Braden Internet-Draft USC/ISI Updates: 2223 (if approved) J. Klensin Expires: March 29, 2009 September 25, 2008 Images in RFCs draft-rfc-image-files-01.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 March 29, 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, illustrations, equations or other graphics to RFCs. Braden & Klensin Expires March 29, 2009 [Page 1] Internet-Draft Images in RFCs September 2008 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. A New Scheme for Images . . . . . . . . . . . . . . . . . . . 4 3. Construction of the Image File . . . . . . . . . . . . . . . . 5 4. Requirements for the Base File . . . . . . . . . . . . . . . . 6 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.2. Figures Section . . . . . . . . . . . . . . . . . . . . . 6 4.3. Formatting Changes . . . . . . . . . . . . . . . . . . . . 7 5. Submission and Processing of the Image File . . . . . . . . . 8 6. Implementation Issues . . . . . . . . . . . . . . . . . . . . 8 7. RFC Repository File Formats . . . . . . . . . . . . . . . . . 9 8. Internationalization Considerations . . . . . . . . . . . . . 10 9. Approval and Authorization . . . . . . . . . . . . . . . . . . 10 10. Security Considerations . . . . . . . . . . . . . . . . . . . 10 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 13.1. Normative References . . . . . . . . . . . . . . . . . . . 11 13.2. Informative References . . . . . . . . . . . . . . . . . . 11 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 Intellectual Property and Copyright Statements . . . . . . . . . . 13 Braden & Klensin Expires March 29, 2009 [Page 2] Internet-Draft Images in RFCs September 2008 1. Introduction Published documents in the RFC series normally use only plain-text ASCII characters and a fixed-width font [RFC2223]. 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, complex equations, 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]. The textual content and layout of the PDF/PS version is required to match the base version as closely as possible. However, except in a few rare exception cases (see, e.g., [RFC1129]) 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, while preserving the convenience, stability, and searchability of ASCII base documents, 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). Braden & Klensin Expires March 29, 2009 [Page 3] Internet-Draft Images in RFCs September 2008 Discussion of this document is being moved to the rfc-interest mailing list. For subscription information and archives, see http://www.rfc-editor.org/mailman/listinfo/rfc-interest. 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 [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 has been 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. Braden & Klensin Expires March 29, 2009 [Page 4] Internet-Draft Images in RFCs September 2008 3. Construction of the Image File An image file would be a single PDF file, consistent with the description in [RFC3778] and defined in [ISO32000-1]. 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 [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. In particular, required sections of RFCs, such as considerations for IANA or references, must be completely understandable from base RFC text. Any figures referenced from those sections must contain only supplemental material. Figures in the image file may be used to show groups of equations in highly formatted forms that are easier to understand than ASCII layouts. However, since it is probable that documents will be searched for terms of equations, it is preferable (and the RFC Editor may require) that ASCII forms be present in the base RFC. 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:
.. An author who believes that another labeling scheme would increase clarity should check with the RFC Editor. Braden & Klensin Expires March 29, 2009 [Page 5] Internet-Draft Images in RFCs September 2008 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. o The page number of the end-of-RFC boilerplate page would be changed to be logically one page after the last image file page. o A new unnumbered "Figures" section would be required. This is described below. o 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 follow 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. Braden & Klensin Expires March 29, 2009 [Page 6] Internet-Draft Images in RFCs September 2008 ___________________________________________________________________________ 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 have corresponding material 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. Braden & Klensin Expires March 29, 2009 [Page 7] Internet-Draft Images in RFCs September 2008 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 scheme 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. vspace/>[[anchor10: Placeholder: it has been proposed that documents using this model, whether I-Ds, RFCs, or both, should be retrievable from the repository in a bundled format (e.g., a zip or tar file), in addition to the separate .txt and .img files. The RFC Editor may require submissions to be unbundled, in which case they would do the bundling upon publication. This option needs further discussion. It would clearly change the discussion about naming conventions.]] 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 or the ability to generate combined files (the original image and the overlaid headers and footers) in which they had confidence. Braden & Klensin Expires March 29, 2009 [Page 8] Internet-Draft Images in RFCs September 2008 5. Some RFC Editor scripts and tools would need small extensions. 6. Some small extensions to xml2rfc [RFC2629] to include image files would be useful. It should generate the boilerplate with a non- sequential page number. For example, an attribute on 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: o .txt: ASCII-only file. In old scheme, complete normative file. In new scheme, text part of normative composite RFC, or stand- alone normative text file. o .ps: Old scheme -- a Postscript file that includes figures and whose text is intended to be the same as the normative .txt file. o .pdf: Old scheme -- a PDF file that includes figures and whose text is intended to be the same as the normative .txt file. o .img.pdf: New scheme: image file part of a composite with .txt file. o .txt.pdf: Old scheme: Facsimile of corresponding .txt file. We note that it would be possible to combine the base and image files Braden & Klensin Expires March 29, 2009 [Page 9] Internet-Draft Images in RFCs September 2008 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, by example, two special cases. 1. RFC 3743 [RFC3743] 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. Approval and Authorization [[anchor14: Placeholder: In its capacity as the body that approves the general policy followed by the RFC Editor (see), the IAB will eventually need to review and sign off on this proposal.]][RFC2850] 10. 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 Braden & Klensin Expires March 29, 2009 [Page 10] Internet-Draft Images in RFCs September 2008 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. 11. IANA Considerations This document requires no actions by the IANA. An intentional consequence of the model is that IANA will not need to inspect the image file in order to carry out its task of evaluating proposed RFCs for potential actions. 12. 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 as did Steve Bellovin, Olaf Kolkman, and Henrik Levkowetz. 13. References 13.1. Normative References [ISO32000-1] International Organization for Standardization (ISO), "Document management -- Portable document format -- Part 1: PDF 1.7", ISO 32000-1:2008, 2008. [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", RFC 2223, October 1997. [RFC3778] Taft, E., Pravetz, J., Zilles, S., and L. Masinter, "The application/pdf Media Type", RFC 3778, May 2004. [RFC4748] Bradner, S., "RFC 3978 Update to Recognize the IETF Trust", BCP 78, RFC 4748, October 2006. 13.2. Informative References [ISO19005-1] International Organization for Standardization (ISO), Braden & Klensin Expires March 29, 2009 [Page 11] Internet-Draft Images in RFCs September 2008 "Document management -- Electronic document file format for long-term preservation -- Part 1: Use of PDF 1.4 (PDF/A-1)", ISO 19005-1:2005, 2005. [RFC1129] Mills, D., "Internet Time Synchronization: The Network Time Protocol", RFC 1129, October 1989. [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. [RFC2850] Internet Architecture Board and B. Carpenter, "Charter of the Internet Architecture Board (IAB)", BCP 39, RFC 2850, May 2000. [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", RFC 3743, April 2004. Authors' Addresses Robert Braden USC/ISI 4676 Admiralty Way Marina del Rey, CA 90292 USA Phone: +1 310 448 9173 Email: braden@isi.edu John C Klensin 1770 Massachusetts Ave, #322 Cambridge, MA 02140 USA Phone: +1 617 491 5735 Email: john-ietf@jck.com Braden & Klensin Expires March 29, 2009 [Page 12] Internet-Draft Images in RFCs September 2008 Full Copyright Statement Copyright (C) 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. Braden & Klensin Expires March 29, 2009 [Page 13]