Network Working Group                                         C. Bormann
Internet-Draft                                    Universität Bremen TZI
Intended status: Informational                              27 July 2023
Expires: 28 January 2024


                    Terminology for RFCXML Evolution
                   draft-bormann-rswg-terminology-00

Abstract

   The canonical format for RFCs is called RFCXML, with the currently
   effective details originally documented in the RFC 799x series.  This
   format has experienced some uncontrolled evolution since, partially
   caused by an unwillingness to recognize the need for overt,
   deliberate evolution.

   Controlled RFCXML evolution is going to be complex.  Its discussion
   will need agreed terminology, without which it will devolve into a
   Tower of Babel.

About This Document

   This note is to be removed before publishing as an RFC.

   Status information for this document may be found at
   https://datatracker.ietf.org/doc/draft-bormann-rswg-terminology/.

   Discussion of this document takes place on the rswg Working Group
   mailing list (mailto:rswg@ietf.org), which is archived at
   https://mailarchive.ietf.org/arch/browse/rswg/.  Subscribe at
   https://www.ietf.org/mailman/listinfo/rswg/.

   Source for this draft and an issue tracker can be found at
   https://github.com/cabo/rswg-terminology.

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






Bormann                  Expires 28 January 2024                [Page 1]

Internet-Draft      Terminology for RFCXML Evolution           July 2023


   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 28 January 2024.

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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Conventions and Definitions . . . . . . . . . . . . . . .   3
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Format  . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.2.  Instances . . . . . . . . . . . . . . . . . . . . . . . .   4
     2.3.  Evolution . . . . . . . . . . . . . . . . . . . . . . . .   5
     2.4.  Types of Evolution  . . . . . . . . . . . . . . . . . . .   6
     2.5.  Correcting Errors . . . . . . . . . . . . . . . . . . . .   7
   3.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
   5.  Normative References  . . . . . . . . . . . . . . . . . . . .   7
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   7
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   7

1.  Introduction

   The canonical format for RFCs is called RFCXML, with the currently
   effective details originally documented in the RFC 799x series.  This
   format has experienced some uncontrolled evolution since, partially
   caused by an unwillingness to recognize the need for overt,
   deliberate evolution.

   Controlled RFCXML evolution is going to be complex.  Its discussion
   will need agreed terminology, without which it will devolve into a
   Tower of Babel.






Bormann                  Expires 28 January 2024                [Page 2]

Internet-Draft      Terminology for RFCXML Evolution           July 2023


1.1.  Conventions and Definitions

   Although this document is not an IETF Standards Track publication, it
   adopts the conventions for normative language to provide clarity of
   instructions to the implementer.  The key words "MUST", "MUST NOT",
   "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
   "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in BCP 14 [RFC2119]
   [RFC8174] when, and only when, they appear in all capitals, as shown
   here.

2.  Terminology

   Ultimately, this document should turn into a definitions section of
   some other document.  For now, we will use a mix of prose and
   definition styles.

2.1.  Format

   XML does not define the meaning of its instances.  Saying "this
   document is in XML" doesn't tell you much more about its semantics
   than "this document is in ASCII".

   When we talk about the specific semantics instilled into an XML
   document by the RFCXML format, we will therefore always use the term
   RFCXML.  This term can be split into several aspects:

   *  *syntactic* aspects.  As XML is (mostly) a tree, this is often
      reduced to a (tree) *grammar* of XML elements and XML attributes.
      However, there are other syntactical aspects, such as for the text
      in elements and attribute values (*lexical* aspects): the meaning
      of specific characters (e.g., format effectors; hyphenation
      semantics) and even whether some text is allowed in certain
      elements or attribute values.

   *  *semantic* aspects.  The elements and attributes carry specific
      semantics.  These semantics are perceived by document users
      through *renderings*.  Semantic markup is about keeping the
      semantics mostly at a domain level, with an ability to infer the
      right kind of *layout* (in a wide sense, e.g., including font
      choice) in a rendering process.  However, there are also semantics
      that are defined at a rendering level, e.g., those of <em> and
      <strong>.  (Officially, these are also semantic markup, but as
      soon as a "Conventions" section says "Newly defined terms are
      shown in italics", that is no longer true.)






Bormann                  Expires 28 January 2024                [Page 3]

Internet-Draft      Terminology for RFCXML Evolution           July 2023


   Semantic aspects that are not rendered are *hidden* semantics.  E.g.,
   the <keywords> element is entirely not rendered in today's
   renderings; it is intended for processes outside of rendering/human
   consumption (e.g., search).  The <sourcecode name= attribute is
   rendered only in certain cases, but can be used by sourcecode
   extraction processes (e.g., for CI or for re-use of pseudo-code in
   other contexts) in other cases, too.

   RFCXML currently has three rendering *targets* offered by the RFC
   editor: *TXT*, *HTML*, *PDF*. HTML and PDF are *typographic*
   renderings, TXT is a *typewriter* rendering.  IETF datatracker also
   has a forth and fifth rendering target, which uses HTML or PDF, but
   tries to emulate TXT rendering while doing so.

   Some semantics is hidden in some of these renderings, but not others.
   E.g., the <tt> element serves to identify text as different from
   normal running text, semantically similar to the way <sourcecode> and
   <artwork> do, but syntactically more like <em> or <strong>.  Since
   xml2rfc 3.10.0, the semantics of <tt> are *suppressed* in TXT
   renderings, which leads to problems (not just the middle-of-the-river
   semantic change, but also for new documents: the inability to express
   certain semantics in a way that they are recognizable in TXT but not
   distracting in the typographic renderings).  A recent poll whether
   <em> should also be suppressed in TXT ended with a negative result.

   Note that suppression of certain semantics in certain rendering
   targets is fine if the semantics is *ancillary*.  Different documents
   differ in their usage of certain markup semantics, and even different
   authors of the same document may disagree whether some usage is
   ancillary or *essential* (i.e., of semantic intent, conveying
   meaning): From an author's view, usage of specific markup can be for
   aesthetic purposes, it can increase ease of use of the document, it
   can help prevent a misunderstanding (which can have very different
   levels of likelihood to occur), or it can be essential.

2.2.  Instances

   RFCs are *instances* of RFCXML, specifically the *publishing* subset
   of RFCXML.  As of today, these instances are *immutable*. Format
   evolution may call for a way to evolve the instances along with an
   evolved format specification.

   Most RFCs are the result of a *consensus* process, either full IETF
   consensus or maybe just the review of a smaller group whether the
   document should be published (IAB, IRTF RG, ISE review).






Bormann                  Expires 28 January 2024                [Page 4]

Internet-Draft      Terminology for RFCXML Evolution           July 2023


   This consensus is almost exclusively formed by review processes that
   involve reviewing renderings, only very rarely by looking at the
   RFCXML instance itself.  These review processes are often extremely
   expensive, as they involve contributions from sought-after experts in
   the field.  Their output constitutes much of the value of the RFC
   series.

   During the review processes, the document instance is not an RFC.
   Specifically, the *authoring* subset of RFCXML is used, which has
   slightly different characteristics from the publishing subset.  As
   mentioned, we sometimes also use different renderers during the
   authoring/reviewing process (e.g., datatracker's distinct HTML/PDF
   renderings), reducing the congruence of the reviewed document with
   what its users will see.

2.3.  Evolution

   The definition of RFCXML will evolve, by adding functionality, or by
   taking elements and attributes out of service (sometimes called
   *deprecating*, but see below) that have been obsoleted in some way.

   This is relatively straightforward for new documents.

   Documents that have been in the authoring process and have already
   received expensive review generally need a *transition* strategy,
   such as translation from the format defined by an older RFCXML
   specification to a newer one.  This transition often needs to be
   synchronized with tool development more than with consensus processes
   on the format itself, which can give tools a de-facto normative role.

   Documents that already have been published cannot benefit from format
   evolution as long as their XML instances are immutable.  This can be
   accommodated by keeping RFCXML able to process published documents —
   just those, not the entirety of potential instances of a previous
   RFCXML specification.  This support would be tagged as for backwards
   compatibility only.  (Backwards compatibility for documents in
   authoring/reviewing stage would reduce disruption.)

   The corpus of published RFCXML-form documents is large enough that
   any translation processes to a new RFCXML specification need to be
   *automated*. Such automated processes can then also be made available
   for authoring/reviewing (xml2rfc's --v2v3 process is a nicely carried
   out example for that) or just focused on the finite set of documents
   published to a previous RFCXML specification.

   A format change can affect the Syntax (grammar, other syntactic
   details not captured in the grammar), the Semantics, and/or the
   Rendering (possibly hiding some information in some renderings).



Bormann                  Expires 28 January 2024                [Page 5]

Internet-Draft      Terminology for RFCXML Evolution           July 2023


2.4.  Types of Evolution

   A term that has been used in a non-standard way in the creation of
   RFCXMLv3 is *deprecation*.  In RFC799x, it means that the deprecated
   feature is no longer available for publishing.  It is still available
   during authoring/reviewing, with an understanding that these
   processes provide a way to do a reviewed manual translation or to at
   least review automated translation.

   *  Backwards compatibility (*BC*) means the ability of new systems to
      work with old data.

   *  Forward compatibility means the ability of old systems to work
      with new data.  Forward compatibility is of little interest for
      the current discussion, as we generally view tooling as updated in
      sync with evolution processes. xml2rfc's input validation actively
      prevents forward compatibility, there is no "ignore-unknown"
      functionality even for semantics that could be ancillary.

   Here, Backwards compatibility often can only be ascertained by manual
   review: It is not sufficient that the new system does not crash with
   the old data, the old data MUST be useful in the sense that it would
   survive the same review processes.  (These are generally too
   expensive to be redone just for an RFCXML format change.)

   A non-backwards-compatible (*NBC*) change to the RFCXML format can
   have *detectable* impact on a document, e.g., by now failing its
   validation.  Or the impact can be *non-detectable*, i.e., requiring
   human review to detect, such as a semantic change that creates a
   different rendering that (potentially) has a different meaning.

   A *semantic refinement* allows instances of the updated RFCXML
   specification to express more detailed information than previously
   possible.  E.g., the <em> element could be split into usages for term
   definitions, true emphasis, and other usages of italic type.  It
   could carry hints as to how to emulate it in typewriter renderings.

   A semantic refinement can be done in a roughly backwards-compatible
   way, by retaining the unrefined alternative (e.g. <em>).  Giving that
   alternative more limited semantics (e.g., by adding an attribute with
   a default value) is no longer truly backwards-compatible, as it is a
   (usually hidden!) semantic change.  Retaining it without
   "deprecating" it will require some will-power --- but many documents
   may not have a need for the specific refinement (e.g., proposed in
   the example) and would be well-served by retaining the unrefined
   alternative.





Bormann                  Expires 28 January 2024                [Page 6]

Internet-Draft      Terminology for RFCXML Evolution           July 2023


2.5.  Correcting Errors

   If there is a need to translate RFC instances to new format
   specifications, they are no longer immutable (and/or their names need
   to be augmented by a revision indicator, possibly with a way added to
   obtain the most recent revision).

   Opening up mutability provides an opportunity to correct errors in
   the originally published document, such as errata.

   Such an *instance update* also can be used to replace now deprecated
   (in the English sense) markup by modern one.

   An example for a detectable NBC change would be to only allow digits
   and single spaces between them in <rfc updates= attributes.
   Correcting this in the now failing instances would probably be done
   by manual intervention, as the number of instances is too small to
   justify automation.

3.  Security Considerations

   TBD

4.  IANA Considerations

   This document has no IANA actions.

5.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

Acknowledgments

   TBD

Author's Address








Bormann                  Expires 28 January 2024                [Page 7]

Internet-Draft      Terminology for RFCXML Evolution           July 2023


   Carsten Bormann
   Universität Bremen TZI
   Postfach 330440
   D-28359 Bremen
   Germany
   Phone: +49-421-218-63921
   Email: cabo@tzi.org












































Bormann                  Expires 28 January 2024                [Page 8]