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: <section #>.<fig #>. 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 <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:
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]