Internet DRAFT - draft-hoffman-rfcformat-canon-others

draft-hoffman-rfcformat-canon-others






Network Working Group                                         P. Hoffman
Internet-Draft                                            VPN Consortium
Intended status: Standards Track                           July 12, 2012
Expires: January 13, 2013


           Proposal for Canonical and Other Formats for RFCs
                draft-hoffman-rfcformat-canon-others-03

Abstract

   This document proposes a new, XML-based canonical format for RFCs
   that explicitly allows external art as a normative part of the RFC.
   If the RFC Editor chooses this format, they will also publish non-
   canonical versions of RFCs in order to accomodate the largest target
   audience of readers.  Having a simple, stable canonical format and a
   varying number of non-canonical formats that can change over time
   allows the RFC Editor to add useful formats, particularly in HTML,
   that can keep up with the needs of all RFC readers.

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 January 13, 2013.

Copyright Notice

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



Hoffman                 Expires January 13, 2013                [Page 1]

Internet-Draft         RFCs: Canonical and Others              July 2012


   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.


1.  Introduction

   A clear result of the decades-long discussion about the format of
   published RFCs is that different RFC readers have different needs and
   desires.  No single format will be sufficient, or even useful, to all
   people who read RFCs.  Another clear result is that the format
   described in [RFC2223] and its follow-ons is no longer the best
   format for publishing protocols, process descriptions, research
   findings, and the many other types of documents that are part of the
   modern RFC series.

   This document proposes to deal with these issues in a way that meets
   the needs and desires of the widespread RFC-reading community.  For
   every RFC, the RFC Editor will publish both a canonical version of
   the RFC that is in XML format and multiple additional forms of the
   RFC, most notably at least in one or more HTML formats.  The XML
   format used will likely be an updated version of that from [RFC2629],
   most notably to include in-line graphic art.

   It is noted that XML files are not easily readable.  However, it is
   also noted that the canonical version of an RFC doesn't need to be
   easily readable: only the non-canonical formats derived from the
   canonical version need to be readable.

   Today, all RFCs are easily retrievable by all readers.  In the
   future, all of the versions of an RFC and its art must be easily
   accessible as well.  To make this easier, the RFC Editor will
   establish a permanent URL template for each RFC that leads to a page
   that lists all of the versions and art; a copy of that URL will be
   included near the beginning of the RFC in the boilerplate so that new
   RFC readers can find it.  Further, it will be easy for advanced RFC
   users to mirror the entire collection of RFC material.

   A major motivation behind the "one canonical, many non-canonical"
   proposal is to allow the RFC Editor to easily change the non-
   canonical formats in the future without having to change the
   canonical format.  For example, the recent discussion of RFC formats
   has shown that many people strongly desire good HTML versions of
   RFCs, but there is not agreement of exactly what format the HTML
   should take.  Further, it is completely clear that the HTML standard
   will evolve in the coming years and decades, and some of the new
   features that will be added will be quite useful in RFCs.  Allowing
   the RFC Editor to add additional HTML formats to the RFC collection,



Hoffman                 Expires January 13, 2013                [Page 2]

Internet-Draft         RFCs: Canonical and Others              July 2012


   even for RFCs that have been published in the past, gives the
   greatest value to RFC readers without forcing any changes on the
   canonical RFC format.

   Similarly, it is clear that HTML is not the only useful format for
   RFCs.  Some people really like plain text; others want PDFs or other
   printer-ready paginated formats; still others want different formats
   that can be converted to different reading devices.  Some people want
   detailed metadata for RFCs so that they can better mine them for
   relevant information; such metadata can be contained in either XML or
   HTML formats.  All of these people can be accommodated by the RFC
   Editor publishing multiple non-canonical versions of RFCs.  The
   canonical version of the RFC and all the non-canonical versions of
   the RFC should have predictable URLs so that tools can easily find
   (for example) an RFC in the reader's preferred HTML style just by
   knowing the RFC number.

   The method that the RFC Editor uses to create the non-canonical
   formats for RFCs is left up to the RFC Editor.  For example, they
   might generate it directly from the input files, through an
   intermediate format, or something else.


2.  Canonical RFC Format and Content

   Canonical RFCs are in XML format.  The most salient rules for the
   format and content of those files are:

   o  The format for the XML will be specified by the RFC Editor.  It is
      likely that the XML format will be an improvement to that which is
      now referred to as "xml2rfc" ([RFC2629] and its informal
      successors).

   o  The XML format will allow for art to be contained in the file.
      This art might be instead of text art in a document (such as for a
      diagram that is too complex to render well in text), or might be
      better variants for text art.  The RFC Editor will determine which
      graphic formats are allowed, and it is likely that at least one
      vector format and one pixel-based format will be permitted.

   o  The XML format will contain all of the metadata needed to produce
      any of the non-canonical formats for an RFC.

   o  The text encoding for the document is UTF-8.

   o  The RFC Editor can decide where it is and is not appropriate to
      use non-ASCII characters from the Unicode repertoire in the RFC.
      For example, the RFC Editor might make rules about using non-ASCII



Hoffman                 Expires January 13, 2013                [Page 3]

Internet-Draft         RFCs: Canonical and Others              July 2012


      characters in people's names, reference titles, examples in text,
      and so on.

   o  Text art that internal to the document is limited to 95 columns.
      This is reasonable for printing on laser printers from the past 25
      years, and allows much more expressive art than the current
      maximum of approximately 70 columns.

   Text art encompasses many types of content.  The unifying feature is
   that it is one or more lines of text that must be rendered with a
   monospace font in order to be fully understood in the context of the
   document.  Thus, text art includes graphical representations such as
   packet diagrams, flow diagrams, and flow charts, but it also includes
   other text that needs to have column alignment such as multi-line
   ABNF.

   This proposal does not deal with how mathematical equations might be
   included in the canonical RFC format.  An author can do it as text or
   as art in an external file.  The RFC Editor might allow an equation-
   specific format from external art files.


3.  Additional Formats Provided by the RFC Editor

   The RFC Editor will derive and publish non-canonical documents in
   multiple formats from the RFC.  If the RFC-reading community agrees
   on a single HTML format, that will certainly be published.  If the
   RFC-reading community cannot agree on just one HTML format, the RFC
   Editor might publish non-canonical versions of an RFC in multiple
   HTML formats.  The RFC Editor will oversee the development of the
   tools needed to produce the non-canonical formats.

   Depending on interest from the RFC-reading community, the RFC Editor
   will also publish non-canonical versions in other formats.  For
   example, it is likely that the RFC Editor will publish in at least
   one format of PDF.  Because some tools in widespread use rely on the
   current RFC format, the RFC Editor might also publish a non-canonical
   version in using the rules in RFC 2333 (line lengths, page headers,
   and so on).


4.  Input to the RFC Series

   The RFC Editor will allow submission of RFCs in the same XML format
   as the canonical version of an RFC.  This allows an author to use
   differencing tools to track all changes that are made to the document
   that they submitted to the RFC Editor.




Hoffman                 Expires January 13, 2013                [Page 4]

Internet-Draft         RFCs: Canonical and Others              July 2012


   The RFC Editor will also possibly allow additional formats for
   submission based on agreement with the RFC streams.  If other
   submission formats are allowed, the RFC Editor will convert the
   submission to the canonical format before performing any editing so
   that all editorial changes are easily tracked within the canonical
   format.  This is similar to what they do currently with submissions
   that are not in the format the RFC Editor uses for its internal
   tooling.

   This proposal in this document does not affect the allowed format for
   the publication of Internet-Drafts.  The IETF Chair has indicated
   that such a change might happen after the choices are made for RFC
   format.


5.  Metadata Needed to Create RFCs

   The canonical format for RFCs must contain all of the body text for
   the RFC as well as all of the metadata that is used to mark up the
   RFC.  RFC metadata is useful for many things such as finding RFCs
   with particular types of content and for making it clearer to a
   reader what the RFC author intended.

   The following is a list of the metadata that needs to be part of the
   canonical RFC format.  This list will probably be controversial, but
   the eventual list needs to contain all of the metadata that is
   intended for the final RFC format so that the format can be fully
   specified.  Items marked with an asterisk are especially likely to
   need much more work.

   Status
     Category
     RFC stream
     Obsoletes
     Updates
     Date published
     Draft derived from
     Title and short title
   Per-author
     Name
     Initials
     Company
     Postal
     Email
     URL
     Role (editor, other)
   Front content
     Abstract



Hoffman                 Expires January 13, 2013                [Page 5]

Internet-Draft         RFCs: Canonical and Others              July 2012


     Copyright
     Other legal *
   Headings
     Level
     Number
   Paragraphs
     Indented for quoting or emphasis
   Lists
     Style (bulleted, numbered, unmarked)
     Nesting
     Elements
     Definitions
   Validatable formats
     ABNF
     XML
     JSON
     ASN.1
   Inline art
     Datagram layout
     State diagram
     Flow chart
     Pseudocode
     Table *
     Non-validatable fragments of validatable formats
     Other
   Tables *
   Special sections
     Security Considerations
     IANA Considerations
     Normative References
     Informative References
   Cross-references
     To internal sections
     To reference
     To section in reference
   References *
     RFCs
     Specific versions of IDs
     Non-specific versions of IDs
     Common non-IETF documents (IEEE, ITU, ISO, ANSI, Unicode)
     Corner cases


6.  IANA Considerations

   None





Hoffman                 Expires January 13, 2013                [Page 6]

Internet-Draft         RFCs: Canonical and Others              July 2012


7.  Security Considerations

   None


8.  Informative References

   [RFC2223]  Postel, J. and J. Reynolds, "Instructions to RFC Authors",
              RFC 2223, October 1997.

   [RFC2629]  Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
              June 1999.


Author's Address

   Paul Hoffman
   VPN Consortium

   Email: paul.hoffman@vpnc.org































Hoffman                 Expires January 13, 2013                [Page 7]