Network Working Group P. Hoffman Internet-Draft ICANN Obsoletes: 7990 (if approved) H. Flanagan Updates: 7995, 8153, 9280 (if approved) Spherical Cow Consulting Intended status: Informational 11 March 2024 Expires: 12 September 2024 Updated RFC Format Framework draft-rswg-rfc7990-updates-06 Abstract In order to improve the readability of RFCs while supporting their archivability, the definitive version of the RFC Series transitioned from plain-text ASCII to XML using the RFCXML vocabulary; different publication versions are rendered from that base document. This document is the framework that provides the problem statement, lays out a road map of the documents that capture the specific requirements, and describes how RFCs are published. This document obsoletes RFC 7990 and makes many significant changes to that document. It also updates the stability policy in RFC 9280. This draft is part of the RFC Series Working Group (RSWG); see https://datatracker.ietf.org/edwg/rswg/documents/ (https://datatracker.ietf.org/edwg/rswg/documents/). There is a repository for this draft at https://github.com/paulehoffman/draft- rswg-rfc7990-updates (https://github.com/paulehoffman/draft-rswg- rfc7990-updates). Issues can be raised there, but probably should be on the mailing list instead. 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 https://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 12 September 2024. Hoffman & Flanagan Expires 12 September 2024 [Page 1] Internet-Draft Format Framework March 2024 Copyright Notice Copyright (c) 2024 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 (https://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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Changes to RFC 7990 . . . . . . . . . . . . . . . . . . . 3 1.2. Changes to RFC 9280 . . . . . . . . . . . . . . . . . . . 4 1.3. Key Changes from the Earlier RFC Process . . . . . . . . 5 2. Definitive Version of an RFC . . . . . . . . . . . . . . . . 5 2.1. Updating the Definitive Version of an RFC . . . . . . . . 6 2.2. Expected Updates to XMLRFC . . . . . . . . . . . . . . . 6 3. Publication Versions . . . . . . . . . . . . . . . . . . . . 6 3.1. HTML . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2. PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.3. Plain Text . . . . . . . . . . . . . . . . . . . . . . . 8 4. Archived Documents . . . . . . . . . . . . . . . . . . . . . 8 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 8 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 8.2. Informative References . . . . . . . . . . . . . . . . . 9 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 1. Introduction "RFC Series Format Requirements and Future Development" [RFC6949] discussed 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. This document serves as the framework that describes the problems that were solved and summarizes the documents created to date that capture the specific requirements for each aspect of the change in format. Hoffman & Flanagan Expires 12 September 2024 [Page 2] Internet-Draft Format Framework March 2024 This document is concerned with the production of RFCs, focusing on the published documents. 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 continue to change over time as the community and the RPC gains further experience with the components of the framework. Implementors of those components are advised to avoid assuming that all such changes will be backwards-compatible. 1.1. Changes to RFC 7990 [RFC7990] defined a framework for how RFCs would be published after that document was published, including new formats and a new "canonical format" for archiving RFCs. It talked about "the XML file" as if there will only be one XML file for an RFC because this was the expectation at the time [RFC7990] was published. It also talked about "publication formats" as the versions of HTML, text, and PDF versions derived from the definitive version. After extensive experience with publishing RFCs in the RFCXML format [RFC7991], it has been decided that an RFC's XML file can be updated for narrowly limited purposes. This document changes [RFC7990] in significant ways: * It changes the phrase "xml2rfc version 3" to "RFCXML". * It defines four terms that replace the use of the term "canonical" and clarifies "format": - The "definitive format", which is RFCXML - The "definitive version", which is a published RFC in the definitive format - A "publication format", which is currently one of PDF, plain text, or HTML - A "publication version", which is a published RFC in one of the publication formats * It defines a policy governing how the RFCXML format changes. Hoffman & Flanagan Expires 12 September 2024 [Page 3] Internet-Draft Format Framework March 2024 * It updates [RFC7995] and [RFC8153] by changing the requirement from using the PDF/A-3 standard to using the PDF/A standard, and by dropping the requirement that the XML be embedded in the PDF publication version. * It defines a policy for when the definitive version of an RFC can be updated and older versions archived. * It defines a policy for when the publication versions of an RFC can be updated and older versions archived. * It changes the name of the body that publishes RFCs from "RFC Editor" to "RPC" * It changes the use of JavaScript in HTML to be fully supported as long as it doesn't change the text When using the new terminology, it is important to note that [RFC7990] used the term "canonical format" to mean two very different things. Quoting from 7990: Canonical format: the authorized, recognized, accepted, and archived version of the document and 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. This document uses two terms, "definitive version" and "definitive format", for the earlier term "canonical format". Historical text from [RFC7990] such as Section 2 ("Problem Statement"), Section 4 ("Overview of the Decision-Making Process"), and Section 10 ("Transition Plan") are not copied to this document. 1.2. Changes to RFC 9280 Section 7.6 of [RFC9280] currently says: Once published, RFC Series documents are not changed. This document replaces that sentence with: Hoffman & Flanagan Expires 12 September 2024 [Page 4] Internet-Draft Format Framework March 2024 Once published, RFC Series documents may be re-issued, but the semantic content of published documents shall be preserved to the greatest extent possible. This document also creates a new policy that would exist in Section 7 of [RFC9280]: 7.8. Consistency The series as a whole is consistently presented. RFCs are copyedited, formatted, published, and may be reissued to maintain a consistent presentation. Section 2.1 and Section 3 in this document are based on this updated policy in [RFC9280]. 1.3. Key Changes from the Earlier RFC Process The first RFC to be published using the group of RFCs described in [RFC7990] was [RFC8650], published in November 2019. In the time since then, all published RFCs have followed the general plan from [RFC7990]. At the highest level, the changes that [RFC7990] made to the RFC format involved breaking away from solely ASCII ([RFC20]) plain text and moving to a definitive version that includes all the information required for rendering a document into a wide variety of publication versions. The RPC became responsible for more than just the plain- text file and a PDF rendering that was created from the plain-text at the time of publication; the definitive version and three publication versions of the RFC in order to meet the diverse requirements of the community. The final XML file produced by the RPC is the definitive version for RFCs; it holds all the information intended for an RFC. Additional file formats (HTML, PDF, and plain text) are also published by the RPC. The file formats are described in Section 3 and fully specified in other RFCs. 2. Definitive Version of an RFC The definitive version produced by the RPC is the version that holds all the information intended for an RFC. The RPC may change the definitive version of an RFC over time (that is, change the XML file), as described in Section 2.1. See [RFC7991] for the original complete description of the RFCXML syntax and semantics. Hoffman & Flanagan Expires 12 September 2024 [Page 5] Internet-Draft Format Framework March 2024 The XML may contain SVG line art, as originally described in [RFC7996]. That SVG will also appear in the HTML and PDF publication versions. The XML may contain non-ASCII characters, as originally described in [RFC7997]. These characters will appear in all the publication versions. The published XML file must contain all information necessary to render the specified publication versions; any question about what was intended in the publication will be answered from this file. It is self-contained with all the information known at publication time. For instance, all features that reference externally defined input are expanded. It does not contain src attributes for or elements. It does not contain comments or processing instructions. 2.1. Updating the Definitive Version of an RFC RFCs may be re-issued, as described in Section 1.2. Such changes will seek to preserve the semantics expressed in the original RFC while maintaining consistency across the series. Reasons for such changes include updates to the RFCXML schema, errors discovered in the XML, and changes to the tooling used to generate the publication versions of the definitive XML version of the RFC. The RPC will keep a public record of when it re-issues any RFC, and give a short description of its reasoning for each change. 2.2. Expected Updates to XMLRFC It is anticipated that the syntax and semantics in [RFC7991] will be updated. Updates to the RFCXML specification that are applied to existing RFCs should preserve to the greatest extent possible the semantics expressed in the original RFC. The goal of limiting changes only to syntax is to preserve the semantic meaning encoded in the published document. This policy does not require that updates to RFCXML avoid all risk of introducing semantic changes to existing RFCs. Instead, it only requires that such updates consider the potential for semantic changes, take steps to understand the risk of a semantic change (either deliberate or inadvertent), and to limit those risks. 3. Publication Versions The RPC is permitted but not required to re-issue publication versions of an RFC, as described in Section 1.2. In deciding whether to update the publication versions of an RFC, the RPC will take into account both the risk of semantic changes and consistency of the series. Hoffman & Flanagan Expires 12 September 2024 [Page 6] Internet-Draft Format Framework March 2024 XML format errors and better design choices have been discovered by the community since the first RFCs were published using the RFCXML format. When the XML in a definitive version changes, the publication versions may change, even if this might not result in observable differences. Similarly, as production tools change, publication versions may be regenerated to ensure a consistent presentation. 3.1. HTML [RFC7992] describes the semantic HTML produced by the RPC from the XML files. The HTML file is rendered from the XML file; it is not derived from the plain-text publication version. The body of the document uses a subset of HTML. The documents include Cascading Style Sheets (CSS) for default visual presentation; the CSS can be overwritten by a local CSS file. The allowed CSS is described in [RFC7993]. JavaScript in the HTML publication version is supported. The JavaScript in the HTML is not permitted to change the meaning of the RFC. The JavaScript in the HTML may add text that provides post- publication metadata or pointers. 3.2. PDF [RFC7995] describes the different versions of PDF is offered, with a recommendation of what PDF standard should apply to RFCs. The PDF file is rendered from the XML file or from the HTML publication version; it is not derived from the plain-text publication version. The PDF publication version conforms to the PDF standard. The RPC can decide which PDF standard will be supported after consultation with the community. This document updates [RFC7995] and [RFC8153] by changing the requirement from the RPC use PDF/A-3 standard to instead using the PDF/A standard, and by dropping the requirement that the XML be embedded in the PDF publication version. Other parts of [RFC8153], particularly the need to archive metadata about RFCs, are not changed. The PDF looks more like the HTML publication version than the plain- text publication version. The PDF includes a rich set of tags and metadata within the document. Hoffman & Flanagan Expires 12 September 2024 [Page 7] Internet-Draft Format Framework March 2024 3.3. Plain Text [RFC7994] describes the details of the plain-text format. In particular, it focuses on what changed from the earlier plain-text format for publishing RFCs. 4. Archived Documents The RPC will keep archived set of all definitive versions of RFCs as well as archived sets of the publication versions for an RFC that were previously published. These archived sets must be available using the same access methods as for the XML and the published publication versions. Every archived set shall record the date that a document was created or revised. When the RPC archives documents, it does so in a manner that allows them to be found by people who want the historical (as compared to current) versions of those files. This document does not specify how archives are maintained or how archived documents might be located or identified. The methods for storage and access will be determined by the RPC in consultation with the technical community. 5. IANA Considerations This document has no IANA considerations. 6. Security Considerations Allowing changes to the definitive versions and publication versions of RFCs introduces risks. A significant risk is that unintended changes could occur in either the definitive version or publication versions of an RFC as a result of an editing error, or may be introduced into a publication version when it is regenerated from the definitive version. This may result in the corruption of a standard, practice, or critical piece of information about a protocol, and harm to the reputation of the RFC series. The RPC is expected to identify, track, and actively mitigate risks introduced by this new policy. 7. Acknowledgments Martin Thomson wrote a great deal of the significant text here as part of draft-thomson-rswg-syntax-change. Hoffman & Flanagan Expires 12 September 2024 [Page 8] Internet-Draft Format Framework March 2024 This document has greatly benefitted from the input or the RSWG. In particular, Alexis Rossi, Brian Carpenter, Eliot Lear, Jay Daley, Jean Mahoney, John Levine, and Pete Resnick, gave significant input on the early drafts of this document. 8. References 8.1. Normative References [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990, DOI 10.17487/RFC7990, December 2016, . [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", RFC 7991, DOI 10.17487/RFC7991, December 2016, . [RFC7992] Hildebrand, J., Ed. and P. Hoffman, "HTML Format for RFCs", RFC 7992, DOI 10.17487/RFC7992, December 2016, . [RFC7993] Flanagan, H., "Cascading Style Sheets (CSS) Requirements for RFCs", RFC 7993, DOI 10.17487/RFC7993, December 2016, . [RFC7994] Flanagan, H., "Requirements for Plain-Text RFCs", RFC 7994, DOI 10.17487/RFC7994, December 2016, . [RFC7995] Hansen, T., Ed., Masinter, L., and M. Hardy, "PDF Format for RFCs", RFC 7995, DOI 10.17487/RFC7995, December 2016, . [RFC7996] Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", RFC 7996, DOI 10.17487/RFC7996, December 2016, . [RFC7997] Flanagan, H., Ed., "The Use of Non-ASCII Characters in RFCs", RFC 7997, DOI 10.17487/RFC7997, December 2016, . 8.2. Informative References [RFC20] Cerf, V., "ASCII format for network interchange", STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969, . Hoffman & Flanagan Expires 12 September 2024 [Page 9] Internet-Draft Format Framework March 2024 [RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format Requirements and Future Development", RFC 6949, DOI 10.17487/RFC6949, May 2013, . [RFC8153] Flanagan, H., "Digital Preservation Considerations for the RFC Series", RFC 8153, DOI 10.17487/RFC8153, April 2017, . [RFC8650] Voit, E., Rahman, R., Nilsen-Nygaard, E., Clemm, A., and A. Bierman, "Dynamic Subscription to YANG Events and Datastores over RESTCONF", RFC 8650, DOI 10.17487/RFC8650, November 2019, . [RFC9280] Saint-Andre, P., Ed., "RFC Editor Model (Version 3)", RFC 9280, DOI 10.17487/RFC9280, June 2022, . Authors' Addresses Paul Hoffman ICANN Email: paul.hoffman@icann.org Heather Flanagan Spherical Cow Consulting Email: hlf@sphericalcowconsulting.com Hoffman & Flanagan Expires 12 September 2024 [Page 10]