Internet DRAFT - draft-rswg-rfc7990-updates
draft-rswg-rfc7990-updates
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 28 February 2024
Expires: 31 August 2024
Updated RFC Format Framework
draft-rswg-rfc7990-updates-05
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 31 August 2024.
Hoffman & Flanagan Expires 31 August 2024 [Page 1]
Internet-Draft Format Framework February 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 and RFC 9280 . . . . . . . . . . . . 3
1.2. Key Changes from the Earlier RFC Process . . . . . . . . 4
2. Definitive Version of an RFC . . . . . . . . . . . . . . . . 4
2.1. Updating the Definitive Version of an RFC . . . . . . . . 5
2.2. Expected Updates to XMLRFC . . . . . . . . . . . . . . . 5
3. Publication Versions . . . . . . . . . . . . . . . . . . . . 6
3.1. HTML . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.3. Plain Text . . . . . . . . . . . . . . . . . . . . . . . 7
4. Archived Documents . . . . . . . . . . . . . . . . . . . . . 7
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
6. Security Considerations . . . . . . . . . . . . . . . . . . . 8
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 8
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.1. Normative References . . . . . . . . . . . . . . . . . . 8
8.2. Informative References . . . . . . . . . . . . . . . . . 9
Appendix A. Advice on Regenerating Publication Versions . . . . 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 31 August 2024 [Page 2]
Internet-Draft Format Framework February 2024
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 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 and RFC 9280
[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 "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 [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.
Hoffman & Flanagan Expires 31 August 2024 [Page 3]
Internet-Draft Format Framework February 2024
* 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
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.
Section 7.6 of "RFC Editor Model (Version 3)" [RFC9280] says "Once
published, RFC Series documents are not changed." Section 2.1 and
Section 3 in this document update that policy.
1.2. 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 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 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 31 August 2024 [Page 4]
Internet-Draft Format Framework February 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 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.
2.1. 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 preserve to the greatest extent
possible the semantics expressed in the original 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 any RFC, and give
a short description of its reasoning for each change. This policy
explicitly updates the stability policy from [RFC9280] for the
definitive version.
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.
Hoffman & Flanagan Expires 31 August 2024 [Page 5]
Internet-Draft Format Framework February 2024
3. 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. When the XML in a definitive version 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 but not
required 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 [RFC9280] for
publication versions.
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.
Hoffman & Flanagan Expires 31 August 2024 [Page 6]
Internet-Draft Format Framework February 2024
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.
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.
Appendix A gives some non-normative advice created by the RSWG.
5. IANA Considerations
This document has no IANA considerations.
Hoffman & Flanagan Expires 31 August 2024 [Page 7]
Internet-Draft Format Framework February 2024
6. 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 consequences 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.
7. 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.
8. References
8.1. Normative References
[RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990,
DOI 10.17487/RFC7990, December 2016,
<https://www.rfc-editor.org/rfc/rfc7990>.
[RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
RFC 7991, DOI 10.17487/RFC7991, December 2016,
<https://www.rfc-editor.org/rfc/rfc7991>.
[RFC7992] Hildebrand, J., Ed. and P. Hoffman, "HTML Format for
RFCs", RFC 7992, DOI 10.17487/RFC7992, December 2016,
<https://www.rfc-editor.org/rfc/rfc7992>.
[RFC7993] Flanagan, H., "Cascading Style Sheets (CSS) Requirements
for RFCs", RFC 7993, DOI 10.17487/RFC7993, December 2016,
<https://www.rfc-editor.org/rfc/rfc7993>.
[RFC7994] Flanagan, H., "Requirements for Plain-Text RFCs",
RFC 7994, DOI 10.17487/RFC7994, December 2016,
<https://www.rfc-editor.org/rfc/rfc7994>.
Hoffman & Flanagan Expires 31 August 2024 [Page 8]
Internet-Draft Format Framework February 2024
[RFC7995] Hansen, T., Ed., Masinter, L., and M. Hardy, "PDF Format
for RFCs", RFC 7995, DOI 10.17487/RFC7995, December 2016,
<https://www.rfc-editor.org/rfc/rfc7995>.
[RFC7996] Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC",
RFC 7996, DOI 10.17487/RFC7996, December 2016,
<https://www.rfc-editor.org/rfc/rfc7996>.
[RFC7997] Flanagan, H., Ed., "The Use of Non-ASCII Characters in
RFCs", RFC 7997, DOI 10.17487/RFC7997, December 2016,
<https://www.rfc-editor.org/rfc/rfc7997>.
8.2. Informative References
[RFC20] Cerf, V., "ASCII format for network interchange", STD 80,
RFC 20, DOI 10.17487/RFC0020, October 1969,
<https://www.rfc-editor.org/rfc/rfc20>.
[RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format
Requirements and Future Development", RFC 6949,
DOI 10.17487/RFC6949, May 2013,
<https://www.rfc-editor.org/rfc/rfc6949>.
[RFC8153] Flanagan, H., "Digital Preservation Considerations for the
RFC Series", RFC 8153, DOI 10.17487/RFC8153, April 2017,
<https://www.rfc-editor.org/rfc/rfc8153>.
[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, <https://www.rfc-editor.org/rfc/rfc8650>.
[RFC9280] Saint-Andre, P., Ed., "RFC Editor Model (Version 3)",
RFC 9280, DOI 10.17487/RFC9280, June 2022,
<https://www.rfc-editor.org/rfc/rfc9280>.
Appendix A. 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 [RFC9280]. This appendix contains advice and considerations for
the process of regeneration that came out of discussions of the
policy changes in this document.
Hoffman & Flanagan Expires 31 August 2024 [Page 9]
Internet-Draft Format Framework February 2024
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.
Authors' Addresses
Paul Hoffman
ICANN
Email: paul.hoffman@icann.org
Heather Flanagan
Spherical Cow Consulting
Email: hlf@sphericalcowconsulting.com
Hoffman & Flanagan Expires 31 August 2024 [Page 10]
