[Docs] [txt|pdf|xml] [Tracker] [Email] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 draft-iab-rfc-framework

Network Working Group                                        H. Flanagan
Internet-Draft                                                RFC Editor
Intended status: Informational                           August 21, 2014
Expires: February 22, 2015


                          RFC Format Framework
                    draft-flanagan-rfc-framework-00

Abstract

   The canonical format for the RFC Series has been plain-text, ASCII-
   encoded for several decades.  After extensive community discussion
   and debate, the RFC Editor will be transitioning to XML as the
   canonical format, with different publication formats rendered from
   that base document.  These changes are intended to increase the
   usability of the RFC Series by offering documents that match the
   needs of a wider variety of stakeholders.  With these changes,
   however, comes an increase in complexity for authors, consumers, and
   the publisher of RFCs.  This document serves as the framework that
   describes the problems being solved and summarizes the many documents
   that capture the specific requirements for each aspect of the change
   in format.

   Discussion of this draft takes place on the rfc-interest mailing list
   (rfc-interest@rfc-editor.org), which has its home page at
   https://www.rfc-editor.org/mailman/listinfo/rfc-interest.

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 http://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 February 22, 2015.







Flanagan                Expires February 22, 2015               [Page 1]


Internet-Draft            RFC Format Framework               August 2014


Copyright Notice

   Copyright (c) 2014 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
   (http://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.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Problem Statement . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
   4.  Overview of the Decision Making Process . . . . . . . . . . .   4
   5.  Key Changes . . . . . . . . . . . . . . . . . . . . . . . . .   6
   6.  Document Summary  . . . . . . . . . . . . . . . . . . . . . .   7
     6.1.  Canonical Format Documents  . . . . . . . . . . . . . . .   7
       6.1.1.  XML . . . . . . . . . . . . . . . . . . . . . . . . .   8
     6.2.  Publication Format Documents  . . . . . . . . . . . . . .   8
       6.2.1.  HTML  . . . . . . . . . . . . . . . . . . . . . . . .   8
       6.2.2.  PDF . . . . . . . . . . . . . . . . . . . . . . . . .   8
       6.2.3.  Plain Text  . . . . . . . . . . . . . . . . . . . . .   8
       6.2.4.  Potential Future Publication Formats  . . . . . . . .   8
     6.3.  Figures and Artwork . . . . . . . . . . . . . . . . . . .   9
       6.3.1.  SVG . . . . . . . . . . . . . . . . . . . . . . . . .   9
     6.4.  Content and Page Layout . . . . . . . . . . . . . . . . .   9
       6.4.1.  Non-ASCII Characters  . . . . . . . . . . . . . . . .   9
       6.4.2.  Style Guide . . . . . . . . . . . . . . . . . . . . .   9
       6.4.3.  CSS Requirements  . . . . . . . . . . . . . . . . . .   9
   7.  Transition Plan . . . . . . . . . . . . . . . . . . . . . . .   9
     7.1.  Testing Phase . . . . . . . . . . . . . . . . . . . . . .   9
     7.2.  Transition Phase  . . . . . . . . . . . . . . . . . . . .  10
     7.3.  Completion  . . . . . . . . . . . . . . . . . . . . . . .  10
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .  11
   10. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  11
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  11
     11.1.  Normative References . . . . . . . . . . . . . . . . . .  11
     11.2.  Informative References . . . . . . . . . . . . . . . . .  12
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  13




Flanagan                Expires February 22, 2015               [Page 2]


Internet-Draft            RFC Format Framework               August 2014


1.  Introduction

   In [RFC6949], "RFC Series Format Requirements and Future
   Development," the need for additional features within RFCs such as
   non-ASCII characters to respect author names, more advanced artwork
   than ASCII art, and documents that could display properly on a wide
   variety of devices was discussed.  Based on the discussions with the
   IETF community as well as other communities of interest, the decision
   was made by the RFC Series Editor to explore a change to the format
   of the Series [XML-ANNOUNCE].  This document serves as the framework
   that describes the problems being solved and summarizes the documents
   created to-date that capture the specific requirements for each
   aspect of the change in format.

   Key changes to the publication of RFCs are highlighted, and a
   description of the transition plan that will take the Series from a
   plain-text, ASCII-only format to the new formats are described
   [RFC-INTEREST].

   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.

2.  Problem Statement

   When the first RFCs were published 45 years ago, the tools to create
   and read RFCs were limited.  Distribution was in effect restricted to
   individuals who had access to the network that became the Internet.

   Today, there are nearly three billion people connected to the
   Internet, and individuals from 45 countries or more regularly
   attending IETF meetings over the last 5 years [ISTATS] [IETF numbers
   are unpublished figures from the Secretariat; one could dig them out
   from the plenary proceedings--how to reference?].  The Internet is
   now global, and while the world has changed from when the first RFCs
   were published, the Series remains critical to defining protocols,
   standards, best practices, and more for this global network that
   continues to grow.  In order to make RFCs easily viewable to the
   largest number of people possible, across a wide array of devices,
   and to respect the diversity of authors and reference materials, it
   is time to change from the tightly prescribed format of the RFC
   Series.

   All changes to the format of the RFC Series must consider the
   requirements of a wide set of communities, over an extended length of



Flanagan                Expires February 22, 2015               [Page 3]


Internet-Draft            RFC Format Framework               August 2014


   time.  Existing authors and implementors, lawyers that argue
   Intellectual Property Rights (IPR), and policy-makers that need to
   know what to list in potential RFPs for their organizations, all have
   preferences and requirements for their specific needs.  The immediate
   needs of today's communities must balance with the needs for long-
   term archival storage.

3.  Terminology

   RFC 2119 keywords are not used in this document.

   Terminology as described in RFC 6949:

      ASCII: Coded Character Set - 7-bit American Standard Code for
      Information Interchange, ANSI X3.4-1986

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

      Metadata: information associated with a document so as to provide,
      for example, definitions of its structure, or of elements within
      the document such as its topic or author

      Publication format: display and distribution format as it may be
      read or printed after the publication process has completed

      Reflowable text: text that automatically wraps to the next line in
      a document as the user moves the margins of the text, either by
      resizing the window or changing the font size

      Revisable format: the format that will provide the information for
      conversion into a Publication format; it is used or created by the
      RFC Editor (see Section 2.3 for an explanation of current
      practice)

      Submission format: the format submitted to the RFC Editor for
      editorial revision and publication

4.  Overview of the Decision Making Process

   Requirements, use cases, concerns, and suggestions were collected
   from the communities of interest at every stage of the RFC format
   update project.  Input was received through the rfc-interest mailing
   list, as well as in several face-to-face sessions at IETF meetings.
   Updates regarding the status of the project were offered to the IETF
   community during the IETF Technical Plenary as well as Format BoFs or
   IAB sessions at IETF 84, IETF 85, IETF 88, IETF 89, and IETF 90
   [IETF84] [IETF85] [IETF88] [IETF89] [IETF90].



Flanagan                Expires February 22, 2015               [Page 4]


Internet-Draft            RFC Format Framework               August 2014


   The first document published, RFC 6949, provided the first solid
   documentation on what the requirements were for the Series and in
   effect was the output from the first year of discussion on the topic
   of RFC format.  That RFC was published as an IAB stream document,
   thus following the process described in RFC 4845, "Process for
   Publication of IAB RFCs" [RFC4845].

   After the high-level requirements were published, an RFC Format
   Design Team was brought together to start working out the necessary
   details to develop the code needed to create new and changed formats.
   While the bi-weekly calls for this team were limited to Design Team
   members, review of the drafts produced by this team were done
   publicly through requests for feedback on the rfc-interest mailing
   list.  Several of the drafts produced by the Design Team, including
   the XML v2 and v3 drafts and the SVG profile drafts, were sent
   through an early GenART review before starting the process to be
   accepted as an IAB stream draft [GEN-ART].

   While the IETF community provided the majority of input on the
   process, additional outreach opportunities were sought to gain input
   from an even broader audience.  Informal discussions were held with
   participants at several International Association of Scientific,
   Technical, and Medical Publisher events, and presentations made at
   technical conferences such as the TERENA Networking Conference 2014
   and NORDUnet 2014 [TNC2014] [NORDUnet link TBD].

   In order to respond to concerns regarding responses to subpoenas and
   to understand the requirements for lawyers, advice was requested from
   the IETF Trust legal team regarding what format or formats would be
   considered reasonable when responding to a subpoena request for an
   RFC.

   Given that several other standards development organizations (SDOs)
   do not offer plain-text documents, and in fact may offer more than
   one format for their standards, informal input was sought from them
   regarding their experience with supporting one or more non-plain-text
   formats for their standards.

   Finally, the entire process was reviewed regularly with the RFC
   Series Oversight Committee and regular updates provided to the IAB
   and IESG [RSOC].

   Where consensus was not reached during the process, the RSE made any
   necessary final decisions, as per the guidance in RFC 6635, "RFC
   Editor Model (Version 2)" [RFC6635].






Flanagan                Expires February 22, 2015               [Page 5]


Internet-Draft            RFC Format Framework               August 2014


5.  Key Changes

   At the highest level, the changes being made to the RFC Format
   involve breaking away from a pure-ASCII mode and moving to canonical
   format that includes all the information required for rendering a
   document into a wide variety of publication formats.  The RFC Editor
   will become responsible for more than just the canonical plain-text
   file and the PDF-from-text format created at time of publication;
   they will be creating several different formats in order to meet the
   diverse requirements of the community.

   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.  PDF/A-3 will the the
   publication format offered in response to subpoenas for RFCs
   published through this new process, and will be developed with an eye
   towards long-term archival storage.  HTML will be the focus of
   providing the most flexible set of features for an RFC, including
   JavaScript to provide pointers to errata and other metadata.  Plain-
   text will continue to be offered in order to support existing tool
   chains where practicable and the individuals who prefer to read RFCs
   in this format.

   A short summary of changes for each document format is listed below.
   For more detail, please see the sections later in this document and
   review the drafts.

   XML:

   o  this is the canonical version that contains all information
      necessary to render a variety of formats; any question about what
      was intended in the publication will be answered from this format

   o  the canonical XML vocabulary will be the v3 vocabulary; authors
      may submit drafts in v2 vocabulary, but the final publication will
      convert that to v3

   o  any SVG information will be included inline in the final XML file

   o  automatically generated identifiers for sections, paragraphs,
      figures, and tables in the final XML file

   HTML:

   o  no longer derived from the plain-text document

   o  semantic HTML + override-able CSS




Flanagan                Expires February 22, 2015               [Page 6]


Internet-Draft            RFC Format Framework               August 2014


   o  line art, if available, will be included

   o  text will be reflowable

   o  JavaScript will be supported only as a publication option to
      provide up-to-date links to errata and obsoleted or obsoleting
      RFCs; documents must be readable when JavaScript is disabled

   PDF:

   o  no longer derived from the plain-text document

   o  will look more like the HTML publication format than the plain-
      text publication format

   o  will include a rich set of tags and metadata within the document

   o  will conform to the PDF/A-3 standard

   o  line art, if available, will be included

   o  will contain the source XML

   Plain text:

   o  no longer the canonical version

   o  non-ASCII characters will be allowed in .txt files

   o  A Byte Order Mark (BOM) will be added at the start of each file

   o  widow and orphan control will not have priority

   o  authors may choose to have pointers to line art in other
      publication formats in place of ASCII art in the .txt file

   o  both a paginated and unpaginated plain-text file will be created

   o  page headers and footers will not be used

6.  Document Summary

6.1.  Canonical Format Documents








Flanagan                Expires February 22, 2015               [Page 7]


Internet-Draft            RFC Format Framework               August 2014


6.1.1.  XML

   [draft-reschke-xml2rfc] - Describes the xml2rfc v2 vocabulary.  While
   in wide use today, this vocabulary had not been formally documented.
   In order to understand what needed to change in the vocabulary to
   allow for a more simple experience and additional features for
   authors, the current vocabulary needed to be fully described.  This
   document, when published, will be obsoleted by the RFC published from
   draft-hoffman-xml2rfc.

   [draft-hoffman-xml2rfc] - Describes the xml2rfc v3 vocabulary.  The
   design goals in this vocabulary were to make the vocabulary more
   intuitive for authors, and to expand the features to support the
   changes being made in the publication process.  This draft, when
   published, will obsolete the RFC published from draft-reschke-
   xml2rfc.

6.2.  Publication Format Documents

6.2.1.  HTML

   [draft-hildebrand-html-rfc] - Describes the semantic HTML that will
   be produced by the RFC Editor from the xml2rfc v3 files.

6.2.2.  PDF

   [draft-hansen-rfc-use-of-pdf] - Describes the tags and profiles that
   will be used to create the new PDF format, including both the
   internal structure and the visible layout of the file.  A review of
   the different versions of PDF is offered, with a recommendation of
   what PDF standard should apply to RFCs.

6.2.3.  Plain Text

   [draft-flanagan-plaintext] - Describes the details of the plain text
   format, focusing in particular on what is changing from the existing
   plain-text output.

6.2.4.  Potential Future Publication Formats

6.2.4.1.  EPUB

   This format is intended for use by ebook readers and will be
   available for RFCs after the requirements have been defined.  No
   draft is currently available.






Flanagan                Expires February 22, 2015               [Page 8]


Internet-Draft            RFC Format Framework               August 2014


6.3.  Figures and Artwork

6.3.1.  SVG

   [draft-brownlee-svg-rfc] - describes the profile for SVG line art.
   SVG is an XML-based vocabulary for creating line drawings; SVG
   information will be embedded within the canonical XML at time of
   publication.

6.4.  Content and Page Layout

6.4.1.  Non-ASCII Characters

   [draft-flanagan-nonascii] - There are security and readability
   implications to moving outside the ASCII range of characters.  This
   draft focuses on exactly where and how non-ASCII characters may be
   used in an RFC, with an eye towards keeping the documents as secure
   and readable as possible given the information that needs to be
   expressed.

6.4.2.  Style Guide

   [draft-iab-styleguide] - The RFC Style Guide was revised to remove as
   much page formatting information as possible, focusing instead on
   grammar, structure, and content of RFCs.  Some of the changes
   recommended, however, informed the XML v3 vocabulary.

6.4.3.  CSS Requirements

   Requirements under development; a draft will be posted and described
   here in a later revision of this framework.

7.  Transition Plan

7.1.  Testing Phase

   During document review and approved for submission phase, authors and
   stream-approving body will select drafts to run through the new
   process, noting that final publication will continue to be in plain
   text only.  In order to limit the amount of time the RFC Production
   Center (RPC) spends on testing and QA, note that their priority is to
   edit and publish documents, community assistance will be necessary to
   help move this stage along.

   Purpose of testing phase: to work with the community to identify and
   fix bugs in the process and the code, before producing canonical,
   immutable XML, and to collect additional feedback on the usability of
   the new publication formats.



Flanagan                Expires February 22, 2015               [Page 9]


Internet-Draft            RFC Format Framework               August 2014


   Criteria to indicate success: RPC and Tools Development team to
   review bugs and decide when all show-stoppers have been dealt with.

7.2.  Transition Phase

   Documents submitted with an XML file will go through the new process
   to produce a canonical XML document and the available publication
   formats.  Documents submitted as plain text will be published as
   plain text only; they will not be converted to XML by the RPC.

   Purpose of transition phase: to introduce the new publication process
   to the community at large, and to identify and fix any additional
   bugs in the code and the workflow.

   Known risks: More work on the part of the RPC to support both old and
   new publication processes for some unknown period of time.  There is
   potential for confusion as consumers of RFCs find some documents
   published at this time with a full set of outputs, while other
   documents only have plain text.  There may be a delay in publication
   as new bugs are found that must be fixed before the files can be
   converted into the canonical format and associated publication
   formats.

   Criteria to indicate success: All major and critical bugs are
   resolved.  Rough consensus from the community regarding the utility
   of the new formats.

7.3.  Completion

   All drafts submitted for publication, including text, will be
   converted to XML and published as a Canonical XML file with available
   publication formats.

   Known risks: Higher work load for the RPC as, in addition to the
   grammar and style editing, they also create and/or encourage best
   practice with the XML structure.

   Criteria to indicate success: Costs and resources stabilize for the
   new process.

8.  IANA Considerations

   This document has no actions for IANA.








Flanagan                Expires February 22, 2015              [Page 10]


Internet-Draft            RFC Format Framework               August 2014


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

10.  Acknowledgements

   With many thanks to the RFC Format Design Team for their efforts in
   making this transition successful: Nevil Brownlee (ISE), Tony Hansen,
   Joe Hildebrand, Paul Hoffman, Ted Lemon, Julian Reschke, Adam Roach,
   Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler

11.  References

11.1.  Normative References

   [RFC6949]  Flanagan, H. and N. Brownlee, "RFC Series Format
              Requirements and Future Development", RFC 6949, May 2013.

   [draft-reschke-xml2rfc]
              Reschke, J., "The 'XML2RFC' version 2 Vocabulary", draft-
              reschke-xml2rfc-10 , July 2014.

   [draft-hoffman-xml2rfc]
              Hoffman, P., "The 'XML2RFC' version 3 Vocabulary", draft-
              hoffman-xml2rfc-09 , July 2014.

   [draft-brownlee-svg-rfc]
              Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", draft-
              brownlee-svg-rfc-07 , July 2014.

   [draft-hildebrand-html-rfc]
              Hildebrand, J. and H. Flanagan, ed, "HyperText Markup
              Language Request For Comments Format", draft-hildebrand-
              html-rfc-03 , June 2014.

   [draft-hansen-rfc-use-of-pdf]
              Hansen, T., Masinter, L., and M. Hardy, "PDF for an RFC
              Series Output Document Format", draft-hansen-rfc-use-of-
              pdf-02 , July 2014.

   [draft-flanagan-plaintext]
              Flanagan, H., "Requirements for Plain Text RFCs", draft-
              flanagan-plaintext-01 , July 2014.



Flanagan                Expires February 22, 2015              [Page 11]


Internet-Draft            RFC Format Framework               August 2014


   [draft-flanagan-nonascii]
              Flanagan, H., "The Use of Non-ASCII Characters in RFCs",
              draft-flanagan-nonascii-03 , July 2014.

11.2.  Informative References

   [RFC4845]  Daigle, L. and Internet Architecture Board, "Process for
              Publication of IAB RFCs", RFC 4845, July 2007.

   [RFC6635]  Kolkman, O., Halpern, J., and IAB, "RFC Editor Model
              (Version 2)", RFC 6635, June 2012.

   [draft-iab-styleguide]
              Flanagan, H. and S. Ginoza, "The RFC Style Guide", draft-
              iab-styleguide-02 , April 2014.

   [GEN-ART]  IETF, "General Area Review Team (Gen-ART)", n.d.,
              <http://www.ietf.org/iesg/directorate/gen-art.html>.

   [IETF84]   Flanagan, H., "IETF 84 Proceedings: RFC Format (rfcform)",
              n.d., <http://www.ietf.org/proceedings/84/rfcform.html>.

   [IETF85]   Flanagan, H., "IETF 85 Proceedings: RFC Format (rfcform)",
              n.d., <http://www.ietf.org/proceedings/85/rfcform.html>.

   [IETF88]   Flanagan, H., "IETF 88 Proceedings: RFC Format (rfcform)",
              n.d., <http://www.ietf.org/proceedings/88/rfcform.html>.

   [IETF89]   Flanagan, H., "IETF 89 Proceedings: RFC Format (rfcform)",
              n.d., <http://www.ietf.org/proceedings/89/rfcform.html>.

   [IETF90]   Flanagan, H., "IETF 90 Proceedings: RFC Format (rfcform)",
              n.d., <http://www.ietf.org/proceedings/90/rfcform.html>.

   [ISTATS]   "Internet Live Stats", n.d.,
              <http://www.internetlivestats.com/internet-users/>.

   [RFC-INTEREST]
              RFC Editor, "rfc-interest -- A list for discussion of the
              RFC series and RFC Editor functions.", n.d.,
              <https://www.rfc-editor.org/mailman/listinfo/rfc-
              interest>.

   [RSOC]     IAB, "RFC Editor Program: The RSOC", n.d.,
              <http://www.iab.org/activities/programs/
              rfc-editor-program/>.





Flanagan                Expires February 22, 2015              [Page 12]


Internet-Draft            RFC Format Framework               August 2014


   [TNC2014]  Flanagan, H., "IETF Update - 'What's Hot?' - RFC Update",
              n.d., <https://tnc2014.terena.org/core/presentation/84>.

   [XML-ANNOUNCE]
              "Subject: [rfc-i] Direction of the RFC Format Development
              effort", n.d., <http://www.rfc-editor.org/pipermail/
              rfc-interest/2013-May/005584.html>.

Author's Address

   Heather Flanagan
   RFC Editor

   Email: rse@rfc-editor.org





































Flanagan                Expires February 22, 2015              [Page 13]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/