Internet DRAFT - draft-hoffman-rfc7990-updates

draft-hoffman-rfc7990-updates







Network Working Group                                         P. Hoffman
Internet-Draft                                                     ICANN
Updates: 7990 (if approved)                                  17 May 2023
Intended status: Informational                                          
Expires: 18 November 2023


                          RFC Format Framework
                    draft-hoffman-rfc7990-updates-03

Abstract

   This document updates RFC 7990 by changing the definition of the
   "canonical format" for RFCs and describing the archival versions of
   RFCs in more depth.

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 18 November 2023.

Copyright Notice

   Copyright (c) 2023 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.








Hoffman                 Expires 18 November 2023                [Page 1]

Internet-Draft              Format Framework                    May 2023


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Updated Definition of "Canonical Format" and "Archive"  . . .   2
     2.1.  Reasons for Updating the Canonical XML Files  . . . . . .   3
   3.  Updating Publication Format Documents . . . . . . . . . . . .   4
   4.  Archived Documents  . . . . . . . . . . . . . . . . . . . . .   4
     4.1.  An Initial Proposal for File Naming . . . . . . . . . . .   4
     4.2.  Explaining Reasons for Updating Files . . . . . . . . . .   5
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   5
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   6
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

1.  Introduction

   [RFC7990] defines 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 talks 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.

   The first RFC to be published using the group of RFCs described in
   [RFC7990] was [RFC8651], published in October 2019.  In the time
   since then, all published RFCs have followed the general plan from
   [RFC7990].

   After extensive experience with publishing RFCs in the XML format, it
   has been decided that an RFC's XML file can be updated for narrowly
   limited purposes.  This document updates [RFC7990] in that it changes
   the definition of the canonical format for RFCs and lists the
   purposes which can cause the RFC Editor to change the contents of the
   XML file.  This document also specifies how older versions of the XML
   file for an RFC are archived and made available for historical
   purposes.

   This document explicitly does not update the other documents
   referenced in [RFC7990].

2.  Updated Definition of "Canonical Format" and "Archive"

   Section 3 of [RFC7990] defines the canonical format as:

      Canonical format: the authorized, recognized, accepted, and
      archived version of the document




Hoffman                 Expires 18 November 2023                [Page 2]

Internet-Draft              Format Framework                    May 2023


   The definition of "canonical format" in Section 3 of [RFC7990] is
   updated to be:

      Canonical format: the authorized, recognized, accepted, and most
      recent version of the document published by the RFC Editor

   Section 5 of [RFC7990] says:

      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.

   This wording does not take into account the need to later change the
   XML file to fix XML errors.  XML format errors, and better design
   choices, have been discovered by the community since the first RFCs
   were published using the XML format.  In order to allow the RFC
   Editor to publish correct XML for all RFCs, Section 5 of [RFC7990] is
   updated to say:

      The 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.  The RFC
      Editor may change the file over time to incorporate changes in the
      XML format.

      The RFC Editor must keep archived sets of all versions of the XML
      file for an RFC and the published publication formats (HTML, PDF,
      and plain text) that were published.  These archived sets must be
      available using the same access methods as for the canonical XML
      and the published publication formats.

2.1.  Reasons for Updating the Canonical XML Files

   The canonical XML file can be updated for the following reasons:

   *  The XML vocabulary in [RFC7991] changes

   *  An error is discovered in the XML for an RFC

   During the development of this document, many other reasons for
   updating the canonical XML file were suggested.  Those reasons are
   not in scope for this document, and may be adopted later after the
   community has experience with the updating mechanisms described in
   this document.







Hoffman                 Expires 18 November 2023                [Page 3]

Internet-Draft              Format Framework                    May 2023


3.  Updating Publication Format Documents

   Seciton 7 of [RFC7990] describes the HTML, PDF, and plain text
   versions of an RFC that are published by the RFC Editor.  The section
   is titled "Publication Format Documents", so that term is used here
   to refer to the documents that are derived from the XML for an RFC.
   When the canonical XML changes, the RFC Editor will also regenerate
   the publication format documents and publish those new versions.

   The RFC Editor might also regenerate one or more of the publication
   format documents for an RFC if it sees errors in the generated
   output.  This has already happened in cases where PDF files had
   display errors in them.

   Whenever the RFC Editor publishes regenerated publication format
   documents, it must keep archived sets of all versions of the
   publication format documents files.  These archived sets must be
   available using the same access methods as for the canonical XML and
   the published publication formats.

4.  Archived Documents

   WHen the RFC Editor 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.

   To make the files easier to find, they should be stored in the same
   Internet-accessable locations as the current RFCs.  They should be
   stored in a directory under the directory where the current RFCs are
   kept so that replication of the main directory using rsync or FTP
   will replicate the archival files as well.

   The naming of the archival files is a topic perfect for bike-shedding
   by IETF participants.  Before this document is finished, hundreds (or
   thousands!) of messages, many with firm opinions of the best naming
   method, will be published.  Heck, even the name of the directory for
   archival files is fodder for vigorous bike-shedding.

4.1.  An Initial Proposal for File Naming

   The file names for archived documents will be appended with a
   datestamp indicating the last day that the file was published as the
   canonical XML or publication format documents.  For example, if the
   XML for RFC 8888 is updated on March 4, 2024, the RFC Editor will
   publish the updated files as rfc8888.xml, rfc8888.html, rfc8888.pdf,
   and rfc8888.txt in the normal locations.  It will also publish in the
   archival directory the files rfc8888-2024-03-04.xml,
   rfc8888-2024-03-04.html, rfc8888-2024-03-04.pdf, and



Hoffman                 Expires 18 November 2023                [Page 4]

Internet-Draft              Format Framework                    May 2023


   rfc8888-2024-03-04.txt.

   The same naming scheme is used when just a publication format
   document is published.  For example, if the PDF of RFC 9432 had
   rendering issues that the RFC Editor fixes on January 8, 2024, the
   RFC Editor will publish tne updated file as rfc9432.pdf.  It will
   also publish in the archival directory the file
   rfc9432-2023-01-08.pdf.

4.2.  Explaining Reasons for Updating Files

   During the development of this document, members of the community
   said that the archived XML should contain an explanation for why the
   document was updated.  Some suggested methods include:

   *  An XML comment in the document; except for the fact that [RFC7990]
      prohibits XML comments.

   *  A new element such as <comment> this would require an update to
      [RFC7991]

   *  A <cref> element with a new attribute that would suppress
      inclusion in the publication format documents; this would require
      an update to [RFC7991]

   *  An additional file in the archival directory; this would require
      the reader to find the file when looking at the XML

   Because each of these has a downside, choosing between them is not
   bike-shedding.

5.  IANA Considerations

   This document has no IANA considerations.

6.  Security Considerations

   This document has the same security considerations as [RFC7990].
   Those are:

   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.

7.  References



Hoffman                 Expires 18 November 2023                [Page 5]

Internet-Draft              Format Framework                    May 2023


7.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>.

7.2.  Informative References

   [RFC8651]  Cheng, B., Wiggins, D., and L. Berger, Ed., "Dynamic Link
              Exchange Protocol (DLEP) Control-Plane-Based Pause
              Extension", RFC 8651, DOI 10.17487/RFC8651, October 2019,
              <https://www.rfc-editor.org/rfc/rfc8651>.

Author's Address

   Paul Hoffman
   ICANN
   Email: paul.hoffman@icann.org





























Hoffman                 Expires 18 November 2023                [Page 6]