Network Working Group P. Hoffman
Internet-Draft VPN Consortium
Intended status: Standards Track June 15, 2012
Expires: December 17, 2012
Proposal for Canonical and Other Formats for RFCs
draft-hoffman-rfcformat-canon-others-02
Abstract
This document proposes a new, XML-based canonical format for RFCs
that explicitly allows external art as a normative part of the RFC.
If the RFC Editor chooses this format, they will also publish non-
canonical versions of RFCs in order to accomodate the largest target
audience of readers. Having a simple, stable canonical format and a
varying number of non-canonical formats that can change over time
allows the RFC Editor to add useful formats, particularly in HTML,
that can keep up with the needs of all RFC readers.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on December 17, 2012.
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
Hoffman Expires December 17, 2012 [Page 1]
Internet-Draft RFCs: Canonical and Others June 2012
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
1. Introduction
A clear result of the decades-long discussion about the format of
published RFCs is that different RFC readers have different needs and
desires. No single format will be sufficient, or even useful, to all
people who read RFCs. Another clear result is that the format
described in [RFC2223] and its follow-ons is no longer the best
format for publishing protocols, process descriptions, research
findings, and the many other types of documents that are part of the
modern RFC series.
This document proposes to deal with these issues in a way that meets
the needs and desires of the widespread RFC-reading community. For
every RFC, the RFC Editor will publish all of the following:
o A canonical version of the RFC that is in XML format
o Canonical versions of any art referred to in the canonical RFC
o Multiple additional forms of the RFC, most notably at least in one
or more HTML formats
Submission to the RFC Editor (the "input format") will be in the same
XML format as the canonical version of an RFC. This allows an author
to use differencing tools to track all changes that are made to the
document that they submitted to the RFC Editor.
Today, all RFCs are easily retrievable by all readers. In the
future, all of the versions of an RFC and its art must be easily
accessible as well. To make this easier, the RFC Editor will
establish a permanent URL template for each RFC that leads to a page
that lists all of the versions and art; a copy of that URL will be
included near the beginning of the RFC in the boilerplate so that new
RFC readers can find it. Further, it will be easy for advanced RFC
users to mirror the entire collection of RFC material.
A major motivation behind the "one canonical, many non-canonical"
proposal here is to allow the RFC Editor to easily change the non-
canonical formats in the future without having to change the
canonical format. For example, the recent discussion of RFC formats
has shown that many people strongly desire good HTML versions of
RFCs, but there is not agreement of exactly what format the HTML
should take. Further, it is completely clear that the HTML standard
Hoffman Expires December 17, 2012 [Page 2]
Internet-Draft RFCs: Canonical and Others June 2012
will evolve in the coming years and decades, and some of the new
features that will be added will be quite useful in RFCs. Allowing
the RFC Editor to add additional HTML formats to the RFC collection,
even for RFCs that have been published in the past, gives the
greatest value to RFC readers without forcing any changes on the
canonical RFC format.
Similarly, it is clear that HTML is not the only useful format for
RFCs. Some people really like plain text; others want PDFs or other
printer-ready paginated formats; still others want different formats
that can be converted to different reading devices. Some people want
detailed metadata for RFCs so that they can better mine them for
relevant information. All of these people can be accommodated by the
RFC Editor publishing multiple non-canonical versions of RFCs. The
canonical version of the RFC and all the non-canonical versions of
the RFC should have predictable URLs so that tools can easily find
(for example) an RFC in the reader's preferred HTML style just by
knowing the RFC number.
The method that the RFC Editor uses to create the non-canonical
formats for RFCs is left up to the RFC Editor. For example, they
might generate it directly from the input files, through an
intermediate format, or something else.
2. Canonical RFC Format and Content
Canonical RFCs are in XML format. The most salient rules for the
format and content of those files are:
o The format for the XML will be specified by the RFC Editor. It is
likely that the XML format will be similar to that which is now
referred to as "xml2rfc" ([RFC2629] and its informal successors),
and it is also likely that the format will be different from
"xml2rfc" in that the IETF community has found many problems with
that format.
o It is explicitly allowed to have art in external files. Those
files are referred to in figures in the RFC as URLs that point to
the RFC Editor's web site. These art files might be instead of
text art in a document (such as for a diagram that is too complex
to render well in text), or might be better variants for text art.
The RFC Editor will determine which graphic formats are allowed,
and it is likely that at least one vector format and one pixel-
based format will be permitted.
o The text encoding for the document is UTF-8.
Hoffman Expires December 17, 2012 [Page 3]
Internet-Draft RFCs: Canonical and Others June 2012
o The RFC Editor can decide where it is and is not appropriate to
use non-ASCII characters from the Unicode repertoire in the RFC.
For example, the RFC Editor might make rules about using non-ASCII
characters in people's names, reference titles, examples in text,
and so on.
o Text art that internal to the document is limited to 95 columns.
This is reasonable for printing on laser printers from the past 25
years, and allows much more expressive art than the current
maximum of approximately 70 columns.
Text art encompasses many types of content. The unifying feature is
that it is one or more lines of text that must be rendered with a
monospace font in order to be fully understood in the context of the
document. Thus, text art includes graphical representations such as
packet diagrams, flow diagrams, and flow charts, but it also includes
other text that needs to have column alignment such as multi-line
ABNF.
This proposal does not deal with how mathematical equations might be
included in the canonical RFC format. An author can do it as text or
as art in an external file. The RFC Editor might allow an equation-
specific format from external art files.
3. Additional Formats Provided by the RFC Editor
The RFC Editor will derive and publish non-canonical documents in
multiple formats from the RFC. If the RFC-reading community agrees
on a single HTML format, that will certainly be published. If the
RFC-reading community cannot agree on just one HTML format, the RFC
Editor might publish non-canonical versions of an RFC in multiple
HTML formats.
Depending on interest from the RFC-reading community, the RFC Editor
will also publish non-canonical versions in other formats. For
example, it is likely that the RFC Editor will publish in at least
one format of PDF. Because some tools in widespread use rely on the
current RFC format, the RFC Editor might also publish a non-canonical
version in using the rules in RFC 2333 (line lengths, page headers,
and so on).
The RFC Editor will also publish metadata for each canonical RFC. It
will include document-wide metadata including title, author
information, date of publication, list of references, a structured
table of contents, and so on. The metadata will be available in a
file separate from the canonical RFC to which it refers.
Hoffman Expires December 17, 2012 [Page 4]
Internet-Draft RFCs: Canonical and Others June 2012
4. IANA Considerations
None
5. Security Considerations
None
6. Informative References
[RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors",
RFC 2223, October 1997.
[RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
June 1999.
Author's Address
Paul Hoffman
VPN Consortium
Email: paul.hoffman@vpnc.org
Hoffman Expires December 17, 2012 [Page 5]