]> ICANN

paul.hoffman@icann.org

Spherical Cow Consulting

hlf@sphericalcowconsulting.com

Internet-Draft 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/. There is a repository for this draft at https://github.com/paulehoffman/draft-rswg-rfc7990-updates. Issues can be raised there, but probably should be on the mailing list instead.

Introduction "RFC Series Format Requirements and Future Development" 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. 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, just as the details in changed after publication. 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.

Changes to RFC 7990 and RFC 9280 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 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 (defined in , it has been decided that an RFC's XML file can be updated for narrowly limited purposes. This document changes in significant ways: It changes the phrase "canonical format" to "definitive version" and defines the use of the definitive version in the series. It changes the phrase "publication format" to "publication versions" and defines the use of the publication versions in the series. It changes the phrase "xml2rfc version 3" to "RFCXML". It defines a policy governing how the RFCXML format changes. It updates and 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", based on It changes the use of JavaScript in HTML to be fully supported as long as it doesn't change the text Historical text from 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. Section 7.6 of "RFC Editor Model (Version 3)" says "Once published, RFC Series documents are not changed." and in this document update that policy.

Key Changes from the Earlier RFC Process The first RFC to be published using the group of RFCs described in was , published in November 2019. In the time since then, all published RFCs have followed the general plan from . At the highest level, the changes that made to the RFC format involved breaking away from solely ASCII () 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 the PDF-from-text format created at time of publication; the RPC now creates several different formats 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 is the lowest common denominator that holds all the information intended for an RFC. Additonal file formats (HTML, PDF, and plain text) are also published by the RPC. The file formats are described in and fully specified in other RFCs.

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, as described in . See for the complete description of the XMLRFC syntax and semantics. The XML may contain SVG line art, as described in . That SVG will also appear in the HTML and PDF publication versions. The XML may contain non-ASCII characters, as described in . These characters will appear in all the publication versions. The XML file will not contain any XMLRFC vocabulary elements or attributes that have been marked deprecated. Authors may submit documents using the xml2rfc v2 vocabulary, but the final publication will be converted to use the XMLRFC vocabulary. The published XML file must contain all information necessary to render a variety of formats; 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 <artwork> or <sourcecode> elements. It does not contain comments or processing instructions.

Updating the Definitive Version of an RFC Historically, the published version of an RFC has been immutable. This document defines a new policy that the RPC is permitted to re-issue an RFC for changes that do not affect the semantics of the RFC. Reasons for such a change 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 and RFC, and give a short description of its reasoning for each change. This policy explicitly updates the stability policy from for the definitive version.

Expected Updates to XMLRFC It is anticipated that the syntax and semantics in 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 RFC XML 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 the RSWG carefully 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.

Publication Versions Publication version files may be republished as needed. XML format errors, and better design choices, have been discovered by the community since the first RFCs were published using the RFCXML format. As the RFC XML format of a document changes, publication versions can change, even if this might not result in observable differences. Similarly, as production tools change, publication versions can be regenerated to ensure a consistent presentation across the series. Publication versions and the contexts in which they are displayed can optionally provide additional details of the specific RFCXML version that they were generated from, or provide a means to discover alternative renderings. This document defines a new policy that the RPC is permitted to re-issue publication versions of an RFC. This can happen if the definitive version is updated, but can also happen due to other changes, such as updates to the RPC's tooling. This policy explicitly updates the stability policy from for publication versions.

HTML describes the semantic HTML produced by the RPC from the XMLRFC 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 . JavaScript in the HTML publication version is supported. It is not be permitted to overwrite or change any text present in the rendered HTML. It may add text that provides post-publication metadata or pointers.

PDF 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 and 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 , 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.

Plain Text describes the details of the plain-text format; in particular, it focuses on what changed from the earlier plain-text format for publishing RFCs. The plain-text format is UTF-8 encoded, and non-ASCII characters are allowed. A Byte Order Mark (BOM) is added at the start of each plain-text file. The plain-text file is unpaginated. Running headers and footers are not be used in the plain-text file. Authors may choose to have pointers to line art in other publication versions in place of ASCII art in the plain-text file.

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 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 RFC XML might be located or identified. The methods for storage and access will be determined by the RPC in consultation with the technical community. gives some non-normative advice created by the RSWG.

IANA Considerations This document has no IANA considerations.

Security Considerations 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 RSWG is responsible for managing the risk of semantic changes that would affect the interpretation of existing and future RFCs. Changes to content that has security implications would have security-relevant consequences.

Acknowledgments Martin Thomson wrote a great deal of the significant text here as part of draft-thomson-rswg-syntax-change. This document has greatly benefitted from the input or the RSWG. In particular, Alexis Rossi, Brian Carpenter, Eliot Lear, Jay Daley, John Levine, and Pete Resnick, gave significant input on the early drafts of this document.

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 defines the "xml2rfc" version 3 vocabulary: an XML-based language used for writing RFCs and Internet-Drafts. It is heavily derived from the version 2 vocabulary that is also under discussion. This document obsoletes the v2 grammar described in RFC 7749. In order to meet the evolving needs of the Internet community, the canonical format for RFCs is changing from a plain-text, ASCII-only format to an XML format that will, in turn, be rendered into several publication formats. This document defines the HTML format that will be rendered for an RFC or Internet-Draft. The HTML format for RFCs assigns style guidance to a Cascading Style Sheet (CSS) specifically defined for the RFC Series. The embedded, default CSS as included by the RFC Editor is expected to take into account accessibility needs and to be built along a responsive design model. This document describes the requirements for the default CSS used by the RFC Editor. The class names are based on the classes defined in "HTML for RFCs" (RFC 7992). In 2013, after a great deal of community discussion, the decision was made to shift from the plain-text, ASCII-only canonical format for RFCs to XML as the canonical format with more human-readable formats rendered from that XML. The high-level requirements that informed this change were defined in RFC 6949, "RFC Series Format Requirements and Future Development". Plain text remains an important format for many in the IETF community, and it will be one of the publication formats rendered from the XML. This document outlines the rendering requirements for the plain-text RFC publication format. These requirements do not apply to plain-text RFCs published before the format transition. This document discusses options and requirements for the PDF rendering of RFCs in the RFC Series, as outlined in RFC 6949. It also discusses the use of PDF for Internet-Drafts, and available or needed software tools for producing and working with PDF. This document specifies SVG 1.2 RFC -- an SVG profile for use in diagrams that may appear in RFCs -- and considers some of the issues concerning the creation and use of such diagrams. In order to support the internationalization of protocols and a more diverse Internet community, the RFC Series must evolve to allow for the use of non-ASCII characters in RFCs. While English remains the required language of the Series, the encoding of future RFCs will be in UTF-8, allowing for a broader range of characters than typically used in the English language. This document describes the RFC Editor requirements and gives guidance regarding the use of non-ASCII characters in RFCs. This document updates RFC 7322. Please view this document in PDF form to see the full text. This document describes the current requirements and requests for enhancements for the format of the canonical version of RFCs. Terms are defined to help clarify exactly which stages of document production are under discussion for format changes. The requirements described in this document will determine what changes will be made to RFC format. This document updates RFC 2223. The RFC Editor is both the publisher and the archivist for the RFC Series. This document applies specifically to the archivist role of the RFC Editor. It provides guidance on when and how to preserve RFCs and describes the tools required to view or re-create RFCs as necessary. This document also highlights gaps in the current process and suggests compromises to balance cost with best practice. This document provides a RESTCONF binding to the dynamic subscription capability of both subscribed notifications and YANG-Push. This document specifies version 3 of the RFC Editor Model. The model defines two high-level tasks related to the RFC Series. First, policy definition is the joint responsibility of the RFC Series Working Group (RSWG), which produces policy proposals, and the RFC Series Approval Board (RSAB), which approves such proposals. Second, policy implementation is primarily the responsibility of the RFC Production Center (RPC) as contractually overseen by the IETF Administration Limited Liability Company (IETF LLC). In addition, various responsibilities of the RFC Editor function are now performed alone or in combination by the RSWG, RSAB, RPC, RFC Series Consulting Editor (RSCE), and IETF LLC. Finally, this document establishes the Editorial Stream for publication of future policy definition documents produced through the processes defined herein. This document obsoletes RFC 8728. This document updates RFCs 7841, 8729, and 8730.

Advice on Regenerating Publication Versions This document does not include specific guidance regarding the generation of publication versions from the RFCXML source for the definitive version of an RFC. Decisions about how to maintain publication versions are not a matter governed by policy as specified in . This appendix contains advice and considerations for the process of regeneration that came out of discussions of the policy changes in this document. Changes to the RFCXML for existing RFCs might result in changes to the documents rendered from that XML. At the same time, the tools used to generate renderings are under active maintenance. Making it possible for a fresh rendering to replace existing publication versions is a goal supported by the policy changes in this document. This creates a risk that a rerendered documents change in unexpected ways when they are regenerated. This risk of unintentional change can be managed by implementing validation processes: Tools can be continuously checked by producing renderings for existing RFCs. Any change in the rendered document can then be compared with previous outputs and validated. This will ensure that changes in tooling are deliberate and understood. When a change to the XML format occurs, rendered documents can be regenerated and any change in the rendering can be validated. Validation should be aided by automated tooling that is able to disregard inconsequential changes in renderings, like changes in timestamps and other annotations. Validation of tooling can be continuous, for which automation is essential. The decision to make renderings available as the publication versions for an RFC is a decision that can be made on a case-by-case basis. Making fresh renderings available more often could mean a greater risk that people seeking to read RFCs will obtain a copy that contains accidental errors. However, errors in publication versions might persist if they are not replaced as tool quality and reliability improves. Old copies of replaced publication versions will be retained to provide the ability to isolate changes and understand the evolution of documents.