INFORMATIONAL

Internet Architecture Board (IAB) H. Flanagan Request for Comments: 7990 RFC Editor Category: Informational December 2016 ISSN: 2070-1721 RFC Format Framework Abstract 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. Status of This Memo 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 Notice 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. Flanagan Informational [Page 1]

RFC 7990 RFC Format Framework December 2016 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 3 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Overview of the Decision-Making Process . . . . . . . . . . . 4 5. Key Changes . . . . . . . . . . . . . . . . . . . . . . . . . 6 6. Canonical Format Documents . . . . . . . . . . . . . . . . . 6 6.1. XML for RFCs . . . . . . . . . . . . . . . . . . . . . . 6 7. Publication Format Documents . . . . . . . . . . . . . . . . 8 7.1. HTML . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7.2. PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7.3. Plain Text . . . . . . . . . . . . . . . . . . . . . . . 9 7.4. Potential Future Publication Formats . . . . . . . . . . 9 7.4.1. EPUB . . . . . . . . . . . . . . . . . . . . . . . . 9 8. Figures and Artwork . . . . . . . . . . . . . . . . . . . . . 9 8.1. SVG . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 9. Content and Page Layout . . . . . . . . . . . . . . . . . . . 10 9.1. Non-ASCII Characters . . . . . . . . . . . . . . . . . . 10 9.2. Style Guide . . . . . . . . . . . . . . . . . . . . . . . 10 9.3. CSS Requirements . . . . . . . . . . . . . . . . . . . . 10 10. Transition Plan . . . . . . . . . . . . . . . . . . . . . . . 10 10.1. Statement of Work and RFP for Tool Development . . . . . 10 10.2. Testing and Transition . . . . . . . . . . . . . . . . . 10 10.3. Completion . . . . . . . . . . . . . . . . . . . . . . . 12 11. Security Considerations . . . . . . . . . . . . . . . . . . . 12 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 12.1. Normative References . . . . . . . . . . . . . . . . . . 12 12.2. Informative References . . . . . . . . . . . . . . . . . 13 IAB Members at the Time of Approval . . . . . . . . . . . . . . . 15 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 Flanagan Informational [Page 2]

RFC 7990 RFC Format Framework December 2016 1 . Introduction 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. 2 . Problem Statement 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. Flanagan Informational [Page 3]

RFC 7990 RFC Format Framework December 2016 3 . Terminology RFC 6949, repeated below for convenience. ASCII: Coded Character Set - 7-bit American Standard Code for Information Interchange, ANSI X3.4-1986 [ASCII] Canonical format: the authorized, recognized, accepted, and archived version of the document Metadata: information associated with a document so as to provide, for example, definitions of its structure, or of elements within the document such as its topic or author Publication format: display and distribution format as it may be read or printed after the publication process has completed Reflowable text: text that automatically wraps to the next line in a document as the user moves the margins of the text, either by resizing the window or changing the font size Revisable format: the format that will provide the information for conversion into a Publication format; it is used or created by the RFC Editor Submission format: the format submitted to the RFC Editor for editorial revision and publication 4 . Overview of the Decision-Making Process Flanagan Informational [Page 4]

RFC 7990 RFC Format Framework December 2016 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 Flanagan Informational [Page 5]

RFC 7990 RFC Format Framework December 2016 RSOC] and regular updates provided to the IAB and IESG. They have offered support and input throughout the process. Where consensus was not reached during the process, the RSE made any necessary final decisions, as per the guidance in "RFC Editor Model (Version 2)" [RFC6635]. 5 . Key Changes 6 . Canonical Format Documents 6.1 . XML for RFCs Flanagan Informational [Page 6]

RFC 7990 RFC Format Framework December 2016 RNC]. o The final XML file will contain, verbatim, the appropriate boilerplate as applicable at time of publication specified by RFC 7841 [RFC7841] or its successors. o The final XML will be self-contained with all the information known at publication time. For instance, all features that reference externally defined input will be expanded. This includes all uses of xinclude, src attributes (such as in <artwork> or <sourcecode> elements), include-like processing instructions, and externally defined entities. o The final XML will not contain comments or processing instructions. o The final XML will not contain src attributes for <artwork> or <sourcecode> elements. [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]. [RFC7991] describes the xml2rfc v3 vocabulary. The design goals were to make the vocabulary more intuitive for authors and to expand the features to support the changes being made in the publication process. It obsoletes RFC 7749. Flanagan Informational [Page 7]

RFC 7990 RFC Format Framework December 2016 7 . Publication Format Documents 7.1 . HTML RFC7992] describes the semantic HTML that will be produced by the RFC Editor from the xml2rfc v3 files. Key points regarding the HTML output: o The HTML will be rendered from the XML file; it will not be derived from the plain-text publication format. o The body of the document will use a subset of HTML. The documents will include Cascading Style Sheets (CSS) for default visual presentation; it can be overwritten by a local CSS file. o SVG is supported and will be included in the HTML file. o Text will be reflowable. o JavaScript will be supported on a limited basis. It will not be permitted to overwrite or change any text present in the rendered HTML. It may, on a limited basis, add text that provides post- publication metadata or pointers, if warranted. All such text will be clearly marked as additional. 7.2 . PDF 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: o The PDF file will be rendered from the XML file; it will not be derived from the plain-text publication format. o The PDF publication format will conform to the PDF/A-3 standard and will embed the canonical XML source. o The PDF will look more like the HTML publication format than the plain-text publication format. o The PDF will include a rich set of tags and metadata within the document. Flanagan Informational [Page 8]

RFC 7990 RFC Format Framework December 2016 7.3 . Plain Text 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: o The plain-text document will no longer be the canonical version of an RFC. o The plain-text format will be UTF-8 encoded; non-ASCII characters will be allowed. o A Byte Order Mark (BOM) will be added at the start of each file. o Widow and orphan control [TYPOGRAPHY] for the plain-text publication format will not have priority for the developers creating the rendering code. o Authors may choose to have pointers to line art in other publication formats in place of ASCII art in the .txt file. o An unpaginated plain-text file will be created. o Running headers and footers will not be used. 7.4 . Potential Future Publication Formats 7.4.1 . EPUB 8 . Figures and Artwork 8.1 . SVG RFC7996] 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 the time of publication. Flanagan Informational [Page 9]

RFC 7990 RFC Format Framework December 2016 9 . Content and Page Layout 9.1 . Non-ASCII 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. 9.2 . Style Guide RFC7322] 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. 9.3 . CSS Requirements RFC7993] describes how the CSS classes mentioned in "HyperText Markup Language Request for Comments Format" should be used to create an accessible and responsive design for the HTML format. 10 . Transition Plan 10.1 . Statement of Work and RFP for Tool Development IASA-RFP]. Once bids have been received, reviewed, and awarded, coding will begin. 10.2 . Testing and Transition Flanagan Informational [Page 10]

RFC 7990 RFC Format Framework December 2016 Flanagan Informational [Page 11]

RFC 7990 RFC Format Framework December 2016 IASA-RFP] IETF Administrative Support Activity, "RFPs and RFIs", <http://iaoc.ietf.org/rfps-rfis.html>. [IETF84] Flanagan, H., "IETF 84 Proceedings: RFC Format (rfcform)", July 2012, <http://www.ietf.org/proceedings/84/rfcform.html>. [IETF85] Flanagan, H., "IETF 85 Proceedings: RFC Format (rfcform)", November 2012, <http://www.ietf.org/proceedings/85/rfcform.html>. [IETF88] Flanagan, H., "IETF 88 Proceedings: RFC Format (rfcform)", November 2013, <http://www.ietf.org/proceedings/88/rfcform.html>. [IETF89] Flanagan, H., "IETF 89 Proceedings: RFC Format (rfcform)", March 2014, <http://www.ietf.org/proceedings/89/rfcform.html>. [IETF90] Flanagan, H., "IETF 90 Proceedings: RFC Format (rfcform)", July 2014, <http://www.ietf.org/proceedings/90/rfcform.html>. [ISTATS] "Internet Live Stats", <http://www.internetlivestats.com/internet-users/>. [NDN2014] "28th NORDUnet Conference 2014", 2014, <https://events.nordu.net/display/NORDU2014/ BoF%27s+and+side+meetings>. [RFC-INTEREST] RFC Editor, "rfc-interest -- A list for discussion of the RFC series and RFC Editor functions.", <https://www.rfc-editor.org/mailman/listinfo/ rfc-interest>. [RNC] Clark, J., "RELAX NG Compact Syntax", OASIS , November 2002, <http://www.oasis-open.org/committees/relax-ng/ compact-20021121.html>. [RSOC] IAB, "RFC Editor Program: The RSOC", <http://www.iab.org/activities/programs/ rfc-editor-program/>. [TNC2014] Flanagan, H., "IETF Update - 'What's Hot?' - RFC Update", 2014, <https://tnc2014.terena.org/core/presentation/84>. Flanagan Informational [Page 14]

RFC 7990 RFC Format Framework December 2016 STM] STM, "The global voice of scholarly publishing", <http://www.stm-assoc.org/>. [TYPOGRAPHY] Butterick, M., "Butterick's Practical Typography", <http://practicaltypography.com/ widow-and-orphan-control.html>. [XML-ANNOUNCE] Flanagan, H., "Subject: [rfc-i] Direction of the RFC Format Development effort", message to the rfc-interest mailing list, May 2013, <http://www.rfc-editor.org/pipermail/rfc-interest/ 2013-May/005584.html>. IAB Members at the Time of Approval The IAB members at the time this memo was approved were (in alphabetical order): Jari Arkko Ralph Droms Ted Hardie Joe Hildebrand Russ Housley Lee Howard Erik Nordmark Robert Sparks Andrew Sullivan Dave Thaler Martin Thomson Brian Trammell Suzanne Woolf Acknowledgements 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. Flanagan Informational [Page 15]

RFC 7990 RFC Format Framework December 2016 http://orcid.org/0000-0002-2647-2220 Flanagan Informational [Page 16]