| Internet Architecture Board (IAB) | H. Flanagan |
| Request for Comments: 7990 | RFC Editor |
| Category: Informational | December 2016 |
| ISSN: 2070-1721 |
In order to improve the readability of RFCs while supporting their archivability, the canonical format of the RFC Series will be transitioning from plain-text ASCII to XML using the xml2rfc version 3 vocabulary; different publication formats will be rendered from that base document. With these changes comes an increase in complexity for authors, consumers, and the publisher of RFCs. This document serves as the framework that provides the problem statement, lays out a road map of the documents that capture the specific requirements, and describes the transition plan.¶
This document is not an Internet Standards Track specification; it is published for informational purposes.¶
This document is a product of the Internet Architecture Board (IAB) and represents information that the IAB has deemed valuable to provide for permanent record. It represents the consensus of the Internet Architecture Board (IAB). Documents approved for publication by the IAB are not a candidate for any level of Internet Standard; see Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7990.¶
Copyright (c) 2016 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.¶
"RFC Series Format Requirements and Future Development" [RFC6949] discusses the need to improve the display of items such as author names and artwork in RFCs as well as the need to improve the ability of RFCs to be displayed properly on various devices. Based on the discussions with communities of interest, such as the IETF, the RFC Series Editor decided 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 transition plan that will take the Series from a plain text, ASCII-only format to the new formats is described on the rfc-interest mailing list [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.¶
The details described in this document are expected to change based on experience gained in implementing the new publication toolsets. Revised documents will be published capturing those changes as the toolsets are completed. Other implementers must not expect those changes to remain backwards compatible with the details described in this document.¶
There are nearly three billion people connected to the Internet [ISTATS] and individuals from at least 45 countries have regularly attended IETF meetings over the last five years. 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 while still recognizing the archival aspects of the Series, it is time to update the tightly prescribed format of the RFC Series.¶
All changes to the format of the RFC Series must be made with consideration to the requirements of a wide set of communities over an extended length of time. Examples of the preferences and specific needs are those of existing authors and implementers, lawyers that argue Intellectual Property Rights (IPR), educators, managers, and policymakers that need to know what to list in potential Request for Proposals (RFPs) for their organizations. The immediate needs of today's communities must be balanced with the needs for long-term archival storage.¶
This document uses terminology from RFC 6949, repeated below for convenience.¶
Requirements, use cases, concerns, and suggestions were collected from the communities of interest at every stage of the project to update the RFC format. Input was received through the rfc-interest mailing list, as well as in several face-to-face sessions at IETF meetings. Regular conversations were held with the Chairs of the IETF, IRTF, IAB, and IAOC as well as the Independent Stream Editor to discuss high-level stream requirements. Updates regarding the status of the project were provided to the IETF community during the IETF Technical Plenary as well as Format BoFs or IAB sessions at several IETF meetings [IETF84] [IETF85] [IETF88] [IETF89] [IETF90].¶
The output from the first year of discussion on the topic of RFC format was published as RFC 6949, which provided the first solid documentation on the requirements for the Series. RFC 6949 is a product of the IAB stream (following the process described in "Process for Publication of IAB RFCs" [RFC4845]). This is also the case with all of the RFCs that informed the format update work.¶
After the high-level requirements were published, the RFC Series Editor (RSE) brought together an RFC Format Design Team to start working out the necessary details to develop the code needed to create new and changed formats. The Design Team discussed moving away from the existing xml2rfc vocabulary, but with such a strong existing support base within the community and no clear value with other XML vocabularies or schemas, the decision was made to work with the xml2rfc version 2 (xml2rfc v2) [RFC7749] model and use it as the base for the new format environment. Part of this discussion included a decision to stop using an XML document type definition (DTD) in favor of a Regular Language for XML Next General (RELAX NG) model using a defined vocabulary. While the biweekly calls for this team were limited to Design Team members, review of the decisions as documented in the documents produced by this team was done publicly through requests for feedback on the rfc-interest mailing list. Several of the documents produced by the Design Team, including those on xml2rfc v2 [RFC7749] and v3 [RFC7991] and the SVG profile [RFC7996], were sent through an early GenART review [GEN-ART] before starting the process to be accepted by the IAB stream.¶
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 [STM], and presentations made at technical conferences such as the TERENA Networking Conference 2014 [TNC2014] and NORDUnet 2014 [NDN2014].¶
In order to respond to concerns regarding responses to subpoenas and to understand the legal requirements, 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.¶
At the highest level, the changes being made to the RFC format involve breaking away from solely ASCII plain text and moving to a 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 plain-text file and the PDF-from-text format created at time of publication; the RFC Editor 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 be 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.¶
Key points regarding the XML format:¶
[RFC7749] describes the xml2rfc v2 vocabulary. While in wide use at the time of writing, this vocabulary had not been formally documented prior to the publication of RFC 7749. 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. RFC 7749 will be obsoleted by [RFC7991].¶
[RFC7992] describes the semantic HTML that will be produced by the RFC Editor from the xml2rfc v3 files.¶
Key points regarding the HTML output:¶
[RFC7995] 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.¶
Key points regarding the PDF output:¶
[RFC7994] describes the details of the plain-text format; in particular, it focuses on what is changing from the existing plain-text output.¶
Key points regarding the 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 document on this topic is currently available.¶
There are security and readability implications to moving outside the ASCII range of characters. [RFC7997] 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.¶
Existing tools for the creation of RFCs will need to be updated, and new tools created, to implement the updated format. As the requirements-gathering effort, described in the various documents described earlier in this document, finishes the bulk of the work, the Tools Development Team of the IETF will work with the RSE to develop Statements of Work (SoWs). Those SoWs will first be reviewed within the Tools Development Team and the Tools Management Committee, and it will then go out for a public comment period. After public review, the SoWs will be attached to an RFP and posted as per the IETF Administrative Support Activity (IASA) bid process [IASA-RFP].¶
Once bids have been received, reviewed, and awarded, coding will begin.¶
During the I-D review and approval process, authors and stream-approving bodies will select drafts to run through the proposed new publication process. The RFC Editor will process these documents after they have been approved for publication using xml2rfc v2 and will simultaneously test the selected I-Ds with the xml2rfc v3 process and tools. While the final RFCs published during this time will continue as plain text and immutable once published, the feedback process is necessary to bootstrap initial testing. These early tests will target finding issues with the proposed xml2rfc v3 vocabulary that result in poorly formed publication formats as well as issues that prevent proper review of submitted documents.¶
Feedback will result in regular iteration of the basic code and XML vocabulary. In order to limit the amount of time the RFC Production Center (RPC) spends on testing and quality assurance (QA), their priority will be to edit and publish documents; therefore, community assistance will be necessary to help move this stage along. A mailing list and experimental source directory on the RFC Editor website will be created for community members willing to assist in the detailed review of the XML and publication formats. Editorial checks of the publication formats by the community are out of scope; the focus will be the QA of each available output, checking for inconsistencies across formats.¶
The purpose of the testing phase is 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.¶
Any modifications to the document review process, up to and including AUTH48, will happen with the community and the stream-approving bodies as we learn more about the features and outputs of the new publication tools. Defining those processes is out of scope for this document.¶
Success will be measured by the closure of all bugs identified by the RPC and the Tools Development Team as fatal in addition to reaching rough consensus with the community on the readiness of the XML vocabulary and final output files for publication. The actual rendering engine can go through further review and iteration, as the publication formats may be republished as needed.¶
Authors are not required to submit their approved drafts to the RFC Editor in an XML format, though they are strongly encouraged to do so; plain text will also remain an option for the foreseeable future. However, documents submitted as plain text cannot include such features as SVG artwork. The RPC will generate an XML file if necessary for basic processing and subsequent rendering into the approved output formats.¶
A known risk at this point of the transition is the difficulty in quantifying the resources required from the RPC. This phase will require more work on the part of the RPC to support both old and new publication processes for at least six months. There is potential for confusion as consumers of RFCs find some documents published at this time with a full set of outputs, while older 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.¶
Authors may submit XML (preferred) or plain-text files. The XML files submitted for publication will be converted to canonical XML format and published with all available publication formats. All authors will be expected to review the final documents as consistent with the evolving procedures for reviewing documents.¶
Success for this phase will be measured by a solid understanding by the RSE and the IAOC of the necessary costs and resources required for long-term support of the new format model.¶
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.¶
The IAB members at the time this memo was approved were (in alphabetical order): ¶
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.¶