wdiff draft-rfc-image-files-00.txt draft-crocker-rfc-media-00.txt

Network Working Group R. Braden
RFC D. Crocker
Internet-Draft USC/ISI
Updates: 2223 (if approved) J. Klensin Brandenburg InternetWorking
Intended status: Standards Track August 27, 2008
Expires: February 23, 28, 2009 August 22, 2008

Images in

Media Format Choices for RFCs
draft-rfc-image-files-00.txt
draft-crocker-rfc-media-00

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, 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 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 suggests a more convenient scheme for
attaching authoritative diagrams, llustrations, illustrations, or other graphics to
RFCs. It further proposes conventions for additional input and
display formats, to improve readability. This proposal is based on
draft-rfc-image-files-00, by Braden and Klensin, and revises it as
little as possible, while expanding the goals of the effort.

Table of Contents

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

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.. 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. Postscript. 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, 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 scheme, for including figures,
illustrations, and graphics to an RFC. RFC, as well as for maintaining a
single copy of base text which can be turned into multiple
presentation forms. 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).

This proposal is based on draft-rfc-image-files-00, by Braden and
Klensin, and revises it as little as possible. As an expedient, the
References section has been omitted from this initial version of the
draft.

1.1. Goals

The list of goals in the current proposal expands upon the ones of
the draft-rfc-image-files-00 proposal:

1. There is a single, master file for document text.

2. Base text is able to be edited, viewed, compared and searched
with extremely minimal set of tools, such as a classic text
editors, and the like.

3. The master file is subject to formatting constraints, to improve
readability when using simple display tools.

4. All formats use strictly open standards.

5. Any mapping from the master file to a presentation format must
only depend upon well-tested, reliable tools that are available
as open-source.

6. Multiple display forms must be supported, notably scroll-form
for screen display and paginated form for printing, as well as
classic, basic IETF ASCII paginated format.

7. Figures can be encoded in classic ASCII art and/or in a graphics
format.

8. Enhanced display formats can support basic font changes, within
IETF-defined criteria, since this can enhance readability.

9. Naming conventions tightly link additional files that are used
by the master file.

10. Changes seek to have as much automation as possible for the
technical aspects of RFC development and production.

11. Format for the master file should facilitate later revision
efforts.

2. A New Scheme for Images Representation

Under our scheme, an RFC may be either a single ASCII file as
commonly used today, or a composite of two multiple files: an ASCII-only
"base file" containing the text of the RFC, and an one or more "image file".
files". The ASCII file may optionally conform to xml2rfc format.
When present, the image file would be a PDF {{standard image} file that contained
contains only images, captions, and title information. Neither The base file of the
composite would be complete without the other,
may contain classic "ASCII art" and a reference to the
RFC would be considered a reference refer to both files. external image files as
alternatives. An RFC which is displayed in any form other than
simple ASCII would then be a logical entity whose complete complete, or
preferred, representation could require two multiple files, base and image.
image(s).

The base file would may be formatted exactly like current ASCII RFCs, with
three minor exceptions described below. Alternatively, it may be
formatted using xml2rfc. The xml2rfc convention is well-established
within the IETF and RFC community. It permits having a single,
textual document base, which can easily produce .txt+.pdf+.html
formats. In addition, it can contain a text-only version of art,
while using external image files, when available and appropriate to
the output form.

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 de facto 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".
"rfcN.{image name}.{image format extension}". As noted earlier, the
repository already contains RFCs with file names "rfcN.ps" and
"rfcN.pdf", using the historic .txt+.pdf+.ps scheme.

3. Construction of the Image File

Each image file would be in a single PDF {image format} file, containing only
that image and consistent with the description in [RFC3778] and
defined in [ISO32000-1]. The particular
PDF {image format} 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 authorizes the future. set of {image
formats} that are permitted for use.

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

Except as otherwise specified in this document, an image file should
contain only figures, a single figure, 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

For xml2rfc output that produces .html or .pdf, images are produced
inline and are consecutively numbered.

For .txt output, pages of the image file files 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 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 may be
numeric and monotonic. monotonic or it may use textual image names. 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.

o The For .txt format, 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 additional 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, ................................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. {Image Name}.

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
format} image file." files."

5. Submission and Processing of the Image File

If an a image file is files are needed, it they should be submitted as an .img.pdf
file a .{image
name>.{image format} files along with the ASCII text file. The image file
files 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 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, draft-...-vv.{image name}.{image format}, where "vv"
is the normal version number. Updating either any 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. {image format}.{image
format}.

5. Some RFC Editor scripts and tools would need small extensions.

6. Some small extensions to xml2rfc to include already supports external image files would be
useful. It should generate the boilerplate with a non-sequential
page number. For example, files, as an attribute on <back>, might specify
the number of pages of image file. One could presumably add a
mechanism to generate the Figures section. adjunct to,
or replacement of, textual art and is used when available, for
.html and .pdf formats..

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 format} image file exists along with a base ASCII RFC,
then RFCs in any other format (e.g., complete PDF {image format} 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 composite RFC, or stand-alone 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: .{image name}.{image format}: New scheme: image file file(s) part of a
composite with .txt or xml2rfc 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
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] 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, {image format},
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

[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.

12.2. Informative References

[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.

[ISO32000-1]
International Organization for Standardization (ISO),
"Document management -- Portable document format -- Part
1: PDF 1.7", ISO 32000-1:2008, 2008.

[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,

Author's Address

Dave Crocker
Brandenburg InternetWorking
675 Spruce Drive
Sunnyvale, CA 90292 94086
USA

Phone: +1 310 448 9173 +1.408.246.8253
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 dcrocker@bbiw.net

Full Copyright Statement

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.

Acknowledgment

Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).