Internet DRAFT - draft-hoffman-rfcformat-canon-others
draft-hoffman-rfcformat-canon-others
Network Working Group P. Hoffman
Internet-Draft VPN Consortium
Intended status: Standards Track July 12, 2012
Expires: January 13, 2013
Proposal for Canonical and Other Formats for RFCs
draft-hoffman-rfcformat-canon-others-03
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 January 13, 2013.
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 January 13, 2013 [Page 1]
Internet-Draft RFCs: Canonical and Others July 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 both a canonical version of
the RFC that is in XML format and multiple additional forms of the
RFC, most notably at least in one or more HTML formats. The XML
format used will likely be an updated version of that from [RFC2629],
most notably to include in-line graphic art.
It is noted that XML files are not easily readable. However, it is
also noted that the canonical version of an RFC doesn't need to be
easily readable: only the non-canonical formats derived from the
canonical version need to be readable.
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 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
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,
Hoffman Expires January 13, 2013 [Page 2]
Internet-Draft RFCs: Canonical and Others July 2012
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; such metadata can be contained in either XML or
HTML formats. 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 an improvement to that which is
now referred to as "xml2rfc" ([RFC2629] and its informal
successors).
o The XML format will allow for art to be contained in the file.
This art 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 XML format will contain all of the metadata needed to produce
any of the non-canonical formats for an RFC.
o The text encoding for the document is UTF-8.
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
Hoffman Expires January 13, 2013 [Page 3]
Internet-Draft RFCs: Canonical and Others July 2012
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. The RFC Editor will oversee the development of the
tools needed to produce the non-canonical 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).
4. Input to the RFC Series
The RFC Editor will allow submission of RFCs 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.
Hoffman Expires January 13, 2013 [Page 4]
Internet-Draft RFCs: Canonical and Others July 2012
The RFC Editor will also possibly allow additional formats for
submission based on agreement with the RFC streams. If other
submission formats are allowed, the RFC Editor will convert the
submission to the canonical format before performing any editing so
that all editorial changes are easily tracked within the canonical
format. This is similar to what they do currently with submissions
that are not in the format the RFC Editor uses for its internal
tooling.
This proposal in this document does not affect the allowed format for
the publication of Internet-Drafts. The IETF Chair has indicated
that such a change might happen after the choices are made for RFC
format.
5. Metadata Needed to Create RFCs
The canonical format for RFCs must contain all of the body text for
the RFC as well as all of the metadata that is used to mark up the
RFC. RFC metadata is useful for many things such as finding RFCs
with particular types of content and for making it clearer to a
reader what the RFC author intended.
The following is a list of the metadata that needs to be part of the
canonical RFC format. This list will probably be controversial, but
the eventual list needs to contain all of the metadata that is
intended for the final RFC format so that the format can be fully
specified. Items marked with an asterisk are especially likely to
need much more work.
Status
Category
RFC stream
Obsoletes
Updates
Date published
Draft derived from
Title and short title
Per-author
Name
Initials
Company
Postal
Email
URL
Role (editor, other)
Front content
Abstract
Hoffman Expires January 13, 2013 [Page 5]
Internet-Draft RFCs: Canonical and Others July 2012
Copyright
Other legal *
Headings
Level
Number
Paragraphs
Indented for quoting or emphasis
Lists
Style (bulleted, numbered, unmarked)
Nesting
Elements
Definitions
Validatable formats
ABNF
XML
JSON
ASN.1
Inline art
Datagram layout
State diagram
Flow chart
Pseudocode
Table *
Non-validatable fragments of validatable formats
Other
Tables *
Special sections
Security Considerations
IANA Considerations
Normative References
Informative References
Cross-references
To internal sections
To reference
To section in reference
References *
RFCs
Specific versions of IDs
Non-specific versions of IDs
Common non-IETF documents (IEEE, ITU, ISO, ANSI, Unicode)
Corner cases
6. IANA Considerations
None
Hoffman Expires January 13, 2013 [Page 6]
Internet-Draft RFCs: Canonical and Others July 2012
7. Security Considerations
None
8. 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 January 13, 2013 [Page 7]
