| Network Working Group | H. Flanagan |
| Internet-Draft | RFC Editor |
| Intended status: Informational | August 21, 2014 |
| Expires: February 22, 2015 |
RFC Format Framework
draft-flanagan-rfc-framework-00
The canonical format for the RFC Series has been plain-text, ASCII-encoded for several decades. After extensive community discussion and debate, the RFC Editor will be transitioning to XML as the canonical format, with different publication formats rendered from that base document. These changes are intended to increase the usability of the RFC Series by offering documents that match the needs of a wider variety of stakeholders. With these changes, however, comes an increase in complexity for authors, consumers, and the publisher of RFCs. This document serves as the framework that describes the problems being solved and summarizes the many documents that capture the specific requirements for each aspect of the change in format.
Discussion of this draft takes place on the rfc-interest mailing list (rfc-interest@rfc-editor.org), which has its home page at https://www.rfc-editor.org/mailman/listinfo/rfc-interest.
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 February 22, 2015.
Copyright (c) 2014 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 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.
In [RFC6949], "RFC Series Format Requirements and Future Development," the need for additional features within RFCs such as non-ASCII characters to respect author names, more advanced artwork than ASCII art, and documents that could display properly on a wide variety of devices was discussed. Based on the discussions with the IETF community as well as other communities of interest, the decision was made by the RFC Series Editor to explore a change to the format of the Series [XML-ANNOUNCE]. This document serves as the framework that describes the problems being solved and summarizes the documents created to-date that capture the specific requirements for each aspect of the change in format.
Key changes to the publication of RFCs are highlighted, and a description of the transition plan that will take the Series from a plain-text, ASCII-only format to the new formats are described [RFC-INTEREST].
This document is concerned with the production of RFCs, focusing on the published formats. It does not address any changes to the processes each stream uses to develop and review their submissions (specifically, how Internet-Drafts will be developed). While I-Ds have a similar set of issues and concerns, directly addressing those issues for I-Ds will be discussed within each document stream.
When the first RFCs were published 45 years ago, the tools to create and read RFCs were limited. Distribution was in effect restricted to individuals who had access to the network that became the Internet.
Today, there are nearly three billion people connected to the Internet, and individuals from 45 countries or more regularly attending IETF meetings over the last 5 years [ISTATS] [IETF numbers are unpublished figures from the Secretariat; one could dig them out from the plenary proceedings--how to reference?]. The Internet is now global, and while the world has changed from when the first RFCs were published, the Series remains critical to defining protocols, standards, best practices, and more for this global network that continues to grow. In order to make RFCs easily viewable to the largest number of people possible, across a wide array of devices, and to respect the diversity of authors and reference materials, it is time to change from the tightly prescribed format of the RFC Series.
All changes to the format of the RFC Series must consider the requirements of a wide set of communities, over an extended length of time. Existing authors and implementors, lawyers that argue Intellectual Property Rights (IPR), and policy-makers that need to know what to list in potential RFPs for their organizations, all have preferences and requirements for their specific needs. The immediate needs of today's communities must balance with the needs for long-term archival storage.
RFC 2119 keywords are not used in this document.
Terminology as described in RFC 6949:
Requirements, use cases, concerns, and suggestions were collected from the communities of interest at every stage of the RFC format update project. Input was received through the rfc-interest mailing list, as well as in several face-to-face sessions at IETF meetings. Updates regarding the status of the project were offered to the IETF community during the IETF Technical Plenary as well as Format BoFs or IAB sessions at IETF 84, IETF 85, IETF 88, IETF 89, and IETF 90 [IETF84] [IETF85] [IETF88] [IETF89] [IETF90].
The first document published, RFC 6949, provided the first solid documentation on what the requirements were for the Series and in effect was the output from the first year of discussion on the topic of RFC format. That RFC was published as an IAB stream document, thus following the process described in RFC 4845, "Process for Publication of IAB RFCs" [RFC4845].
After the high-level requirements were published, an RFC Format Design Team was brought together to start working out the necessary details to develop the code needed to create new and changed formats. While the bi-weekly calls for this team were limited to Design Team members, review of the drafts produced by this team were done publicly through requests for feedback on the rfc-interest mailing list. Several of the drafts produced by the Design Team, including the XML v2 and v3 drafts and the SVG profile drafts, were sent through an early GenART review before starting the process to be accepted as an IAB stream draft [GEN-ART].
While the IETF community provided the majority of input on the process, additional outreach opportunities were sought to gain input from an even broader audience. Informal discussions were held with participants at several International Association of Scientific, Technical, and Medical Publisher events, and presentations made at technical conferences such as the TERENA Networking Conference 2014 and NORDUnet 2014 [TNC2014] [NORDUnet link TBD].
In order to respond to concerns regarding responses to subpoenas and to understand the requirements for lawyers, advice was requested from the IETF Trust legal team regarding what format or formats would be considered reasonable when responding to a subpoena request for an RFC.
Given that several other standards development organizations (SDOs) do not offer plain-text documents, and in fact may offer more than one format for their standards, informal input was sought from them regarding their experience with supporting one or more non-plain-text formats for their standards.
Finally, the entire process was reviewed regularly with the RFC Series Oversight Committee and regular updates provided to the IAB and IESG [RSOC].
Where consensus was not reached during the process, the RSE made any necessary final decisions, as per the guidance in RFC 6635, "RFC Editor Model (Version 2)" [RFC6635].
At the highest level, the changes being made to the RFC Format involve breaking away from a pure-ASCII mode and moving to canonical format that includes all the information required for rendering a document into a wide variety of publication formats. The RFC Editor will become responsible for more than just the canonical plain-text file and the PDF-from-text format created at time of publication; they will be creating several different formats in order to meet the diverse requirements of the community.
The final XML file produced by the RFC Editor will be considered the canonical format for RFCs; it is the lowest common denominator that holds all the information intended for an RFC. PDF/A-3 will the the publication format offered in response to subpoenas for RFCs published through this new process, and will be developed with an eye towards long-term archival storage. HTML will be the focus of providing the most flexible set of features for an RFC, including JavaScript to provide pointers to errata and other metadata. Plain-text will continue to be offered in order to support existing tool chains where practicable and the individuals who prefer to read RFCs in this format.
A short summary of changes for each document format is listed below. For more detail, please see the sections later in this document and review the drafts.
XML:
HTML:
PDF:
Plain text:
[draft-reschke-xml2rfc] - Describes the xml2rfc v2 vocabulary. While in wide use today, this vocabulary had not been formally documented. In order to understand what needed to change in the vocabulary to allow for a more simple experience and additional features for authors, the current vocabulary needed to be fully described. This document, when published, will be obsoleted by the RFC published from draft-hoffman-xml2rfc.
[draft-hoffman-xml2rfc] - Describes the xml2rfc v3 vocabulary. The design goals in this vocabulary were to make the vocabulary more intuitive for authors, and to expand the features to support the changes being made in the publication process. This draft, when published, will obsolete the RFC published from draft-reschke-xml2rfc.
[draft-hildebrand-html-rfc] - Describes the semantic HTML that will be produced by the RFC Editor from the xml2rfc v3 files.
[draft-hansen-rfc-use-of-pdf] - Describes the tags and profiles that will be used to create the new PDF format, including both the internal structure and the visible layout of the file. A review of the different versions of PDF is offered, with a recommendation of what PDF standard should apply to RFCs.
[draft-flanagan-plaintext] - Describes the details of the plain text format, focusing in particular on what is changing from the existing plain-text output.
This format is intended for use by ebook readers and will be available for RFCs after the requirements have been defined. No draft is currently available.
[draft-brownlee-svg-rfc] - describes the profile for SVG line art. SVG is an XML-based vocabulary for creating line drawings; SVG information will be embedded within the canonical XML at time of publication.
[draft-flanagan-nonascii] - There are security and readability implications to moving outside the ASCII range of characters. This draft focuses on exactly where and how non-ASCII characters may be used in an RFC, with an eye towards keeping the documents as secure and readable as possible given the information that needs to be expressed.
[draft-iab-styleguide] - The RFC Style Guide was revised to remove as much page formatting information as possible, focusing instead on grammar, structure, and content of RFCs. Some of the changes recommended, however, informed the XML v3 vocabulary.
Requirements under development; a draft will be posted and described here in a later revision of this framework.
During document review and approved for submission phase, authors and stream-approving body will select drafts to run through the new process, noting that final publication will continue to be in plain text only. In order to limit the amount of time the RFC Production Center (RPC) spends on testing and QA, note that their priority is to edit and publish documents, community assistance will be necessary to help move this stage along.
Purpose of testing phase: to work with the community to identify and fix bugs in the process and the code, before producing canonical, immutable XML, and to collect additional feedback on the usability of the new publication formats.
Criteria to indicate success: RPC and Tools Development team to review bugs and decide when all show-stoppers have been dealt with.
Documents submitted with an XML file will go through the new process to produce a canonical XML document and the available publication formats. Documents submitted as plain text will be published as plain text only; they will not be converted to XML by the RPC.
Purpose of transition phase: to introduce the new publication process to the community at large, and to identify and fix any additional bugs in the code and the workflow.
Known risks: More work on the part of the RPC to support both old and new publication processes for some unknown period of time. There is potential for confusion as consumers of RFCs find some documents published at this time with a full set of outputs, while other documents only have plain text. There may be a delay in publication as new bugs are found that must be fixed before the files can be converted into the canonical format and associated publication formats.
Criteria to indicate success: All major and critical bugs are resolved. Rough consensus from the community regarding the utility of the new formats.
All drafts submitted for publication, including text, will be converted to XML and published as a Canonical XML file with available publication formats.
Known risks: Higher work load for the RPC as, in addition to the grammar and style editing, they also create and/or encourage best practice with the XML structure.
Criteria to indicate success: Costs and resources stabilize for the new process.
This document has no actions for IANA.
Changing the format for RFCs involves modifying a great number of components to publication. Understanding those changes and the implications for the entire tool chain is critical so as to avoid unintended bugs that would allow unintended changes to text. Unintended changes to text could in turn corrupt a standard, practice or critical piece of information about a protocol.
With many thanks to the RFC Format Design Team for their efforts in making this transition successful: Nevil Brownlee (ISE), Tony Hansen, Joe Hildebrand, Paul Hoffman, Ted Lemon, Julian Reschke, Adam Roach, Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler
| [RFC6949] | Flanagan, H. and N. Brownlee, "RFC Series Format Requirements and Future Development", RFC 6949, May 2013. |
| [draft-reschke-xml2rfc] | Reschke, J., "The 'XML2RFC' version 2 Vocabulary", draft-reschke-xml2rfc-10 , July 2014. |
| [draft-hoffman-xml2rfc] | Hoffman, P., "The 'XML2RFC' version 3 Vocabulary", draft-hoffman-xml2rfc-09 , July 2014. |
| [draft-brownlee-svg-rfc] | Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", draft-brownlee-svg-rfc-07 , July 2014. |
| [draft-hildebrand-html-rfc] | Hildebrand, J. and H. Flanagan, ed, "HyperText Markup Language Request For Comments Format", draft-hildebrand-html-rfc-03 , June 2014. |
| [draft-hansen-rfc-use-of-pdf] | Hansen, T., Masinter, L. and M. Hardy, "PDF for an RFC Series Output Document Format", draft-hansen-rfc-use-of-pdf-02 , July 2014. |
| [draft-flanagan-plaintext] | Flanagan, H., "Requirements for Plain Text RFCs", draft-flanagan-plaintext-01 , July 2014. |
| [draft-flanagan-nonascii] | Flanagan, H., "The Use of Non-ASCII Characters in RFCs", draft-flanagan-nonascii-03 , July 2014. |