Network Working Group R. Braden Internet-Draft USC/ISI Updates: 2223 (if approved) J. Klensin Expires: May 28, 2009 November 24, 2008 Images in RFCs draft-rfc-image-files-02.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 May 28, 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 images -- e.g., graphics, equations, or pictures. The historic solution to this requirement has allowed secondary PDF and/or Postscript files, but this approach has seldom been used because it is awkward for authors and publisher. This memo suggests a convenient scheme for logically including authoritative diagrams, illustrations, equations, or other graphics within RFCs. Braden & Klensin Expires May 28, 2009 [Page 1] Internet-Draft Images in RFCs November 2008 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. A New Scheme for Images: Composite RFCs . . . . . . . . . . . 4 3. Construction of an 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. Bundled Composites . . . . . . . . . . . . . . . . . . . . . . 8 7. Implementation Considerations . . . . . . . . . . . . . . . . 9 8. RFC Repository File Formats . . . . . . . . . . . . . . . . . 10 9. Internationalization Considerations . . . . . . . . . . . . . 11 10. Approval and Authorization . . . . . . . . . . . . . . . . . . 11 11. Security Considerations . . . . . . . . . . . . . . . . . . . 11 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 14.1. Normative References . . . . . . . . . . . . . . . . . . . 12 14.2. Informative References . . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 Intellectual Property and Copyright Statements . . . . . . . . . . 14 Braden & Klensin Expires May 28, 2009 [Page 2] Internet-Draft Images in RFCs November 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 great 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 solution to this dilemma has been to allow multiple versions of an RFC: a primary ASCII version as well as 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 scheme as "txt/ps/pdf" representation. The three versions of an RFC using the txt/ps/pdf representation 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/ps/pdf approach has been awkward for both editor and author, and it is error-prone. Therefore, it has seldom been used (roughly 50 out of 5000+ RFCs). The problem is that, in general, only the author has the tools to edit the PDF and Postscript versions. The RFC Editor can readily edit only the primary ASCII text, and then the author must incorporate 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, which may lead to editorial errors, reader confusion. It may also lengthen publication time. 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. The txt/ps/pdf 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 May 28, 2009 [Page 3] Internet-Draft Images in RFCs November 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: Composite RFCs Under the suggested scheme, an RFC would be either a single ASCII file as generally 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 minor exceptions described below. An image file would contain one or more items that will be known collectively as "figures", whether they are actually diagrams, pictures, tables, equations, artwork, or other non-textual constructions. If the approach of this document is adopted, terms like "the RFC" will refer to the combination of the base RFC file and an image file if the latter is supplied. Note that, just as with the txt/ps/pdf representations, an RFC is a logical entity whose complete representation requires multiple files. In particular, the IPR statement in the base file ("Rights Contributors Provide to the IETF Trust in Contributions BCP 78, RFC 5378 [RFC5378]) would apply to the composite, including the image file if one is present. 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/ps/pdf representations. This "image file" scheme was inspired by a tradition of book publishing, in which 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/ ps/pdf representations, the PDF format has become a de facto standard Braden & Klensin Expires May 28, 2009 [Page 4] Internet-Draft Images in RFCs November 2008 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. 3. Construction of an 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 PDF generators 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 IANA Considerations or references, must be completely understandable from the base text file. Any figures referenced from those sections may contain only supplemental material. The image file would be paginated using the same 8.5 x 11" format as the base document, and the image file pages would be consecutively numbered. The first page number of the image file would follow the last page number of the base RFC. 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. Since editing the base file may change its pagination, it may be simplest to ask the RFC Editor to overlay the headers and footers onto the image file near the completion of editing. Each page would need blank space at the top and bottom for this purpose. The amount of blank space is to be determined, but 0.5" might be a reasonable value. Figures included in the image file would have to be labeled in a fashion that facilitated referencing from the base RFC. The labels should normally be numeric and monotonic. Simple consecutive integers 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 Braden & Klensin Expires May 28, 2009 [Page 5] Internet-Draft Images in RFCs November 2008 clarity should consult 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. 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 would 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 May 28, 2009 [Page 6] Internet-Draft Images in RFCs November 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 not have corresponding material in the image file. Groups of mathematical equations form one particular case in wich it may be desirable for a base file to include ASCII artwork approximations. This will ease searching for such documents using equation terminology. equations. There are well-established conventions for approximating fairly complex equations using ASCII artwork. 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. Braden & Klensin Expires May 28, 2009 [Page 7] Internet-Draft Images in RFCs November 2008 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 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 could be submitted without headers or footers. The RFC Editor could then overlay the image file with the appropriate headers and footers, with correct pagination. The RFC Editor would do no editing of the image file beyond adding headers and paginated footers. If editing the base file revealed problems with figures in the image file, the authors would be asked to create a new image file. 6. Bundled Composites The base/image file split should be very convenient for the process of editing and publishing RFCs, and all tools that return RFC meta- data should alert the reader to the composite structure. However, users may sometimes prefer to obtain an existing composite RFC as a single file in a bundled format. Our suggestion for such bundling is to again use PDF encoding. Thus, corresponding to the composite file pair (rfcN.txt, rfcN.img.pdf), there would be a new file with a name like "rfcN.bun.pdf". The .bun.pdf file would be a single PDF file containing a facsimile of the .txt file (like the current .txt.pdf files) followed by the image file. It is important to understand what is being suggested here. The .bun.pdf files would never be submitted for publication by authors; instead, the RFC Editor would mechanically generate the .bun.pdf files upon publication of the .txt and .img.pdf files (just as .txt.pdf files are now generated automatically). Some users might choose to consider the bundled .bun.pdf file as "the RFC", but the RFC Editor would consider "the RFC" to be the {.txt, .img.pdf) file pair. We note that: Braden & Klensin Expires May 28, 2009 [Page 8] Internet-Draft Images in RFCs November 2008 The composite is logically a single RFC that can be normative for a standards-track document. The .bun.pdf bundle, whch would be mechanically derived from the composite pair, might reasonably be declared in the future to be equally normative. The continued existence of a base file that is readily editable by the RFC Editor and readily searchable by users would maintain the advantages of the present ASCII-based scheme. We are not suggesting that, at least in the near term, the composite structure with its ASCII text component be abandoned. On the other hand, the .bun.pdf bundle could be a transitional step towards a future world where RFCs are published in pure .pdf. 7. Implementation Considerations Implementation of the image file 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. 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 and that the original image can be overlaid with headers and footers. 5. Some RFC Editor scripts and tools would need extensions. 6. Small extensions to xml2rfc [RFC2629] would be useful to create base/image file cross-references in header and footers, and to build a Figure section. Braden & Klensin Expires May 28, 2009 [Page 9] Internet-Draft Images in RFCs November 2008 8. 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 format other than that combination (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, nor are any of the traditional non-ASCII formats. 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 rfcN.txt: ASCII-only file. In the traditional system, complete normative file. In the new system, text (base) part of normative composite RFC, or stand-alone normative text file when no image file is necessary. o rfcN.ps: Traditional system -- a Postscript file that includes figures and whose text is intended to be the same as the normative .txt file, but is generally non-informative itself. No new rfcN.ps files would be created after adoption of the image file proposal. o rfcN.pdf: Traditional system -- a PDF file that includes figures and whose text is intended to be the same as the normative .txt file, but is generally non-nformative itself. o rfcN.txt.pdf: Traditional system: Facsimile of corresponding .txt file. o rfcN.img.pdf: New system: image file component of a composite RFC. o rfcN.bun.pdf: New system: bundled composite file. Braden & Klensin Expires May 28, 2009 [Page 10] Internet-Draft Images in RFCs November 2008 9. 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 examples that illustrate 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. [Note in Draft: A separate proposal [Hoffman-RFC-UTF8] is under consideration to permit UTF-8 strings to appear directly in text RFCs under restricted circumstances.] 10. Approval and Authorization [[anchor14: Placeholder: In its capacity as the body that approves the general policy followed by the RFC Editor (see), the IAB would eventually need to review and sign off on this proposal.]][RFC2850] 11. Security Considerations This specification 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 Braden & Klensin Expires May 28, 2009 [Page 11] Internet-Draft Images in RFCs November 2008 should exercise due care to ensure that no such references or scripts appear in the archives. 12. 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. 13. Acknowledgments The impetus for this specification arose during a discussion during an RFC Editorial Board meeting after one of the IETF's many discussions about "modern" formats for RFCs. 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, Alfred Hoenes, Olaf Kolkman, and Henrik Levkowetz. 14. References 14.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. [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide to the IETF Trust", BCP 78, RFC 5378, November 2008. 14.2. Informative References [Hoffman-RFC-UTF8] Hoffman, P. and T. Bray, "Using non-ASCII Characters in RFCs", November 2008, . Braden & Klensin Expires May 28, 2009 [Page 12] Internet-Draft Images in RFCs November 2008 [ISO19005-1] 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)", 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 May 28, 2009 [Page 13] Internet-Draft Images in RFCs November 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 May 28, 2009 [Page 14]