RSE Wiki Archive

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
RFC Design Team wiki space

===== Introduction =====

During IETF 86, the IAB formally approved the publication of "RFC Format Requirements and Future Development" (RFC 6949).  That RFC outlines the requirements gathered from the communities of interest regarding the Canonical format for the RFC Series.  With those requirements in hand, the next step is to explore how those requirements might be implemented and verify what is possible and reasonable for the Series going forward.

The direction we are exploring is one where the Canonical format - the format that is authoritative for content of an RFC - is XML using the xml2rfc DTD.  From that format, four Publication formats will be rendered: Text, HTML, PDF, and EPUB.  We are focusing on the xml2rfc DTD as something most likely to meet the requirements as defined in a reasonable time frame and budget because xml2rfc is:

  * well-known by many in the authoring community as well as the RFC Editor;
  * has a start on meeting most of the requirements already;
  * is based on a solid mark-up language that is expected to exist for the foreseeable future.

Authors may continue to submit XML or text files when their I-Ds are approved for publication.  

By allowing for multiple Publication formats, readers can choose a format that works best for their circumstances.  The Text and PDF will be extremely basic and support the widest array of tools.  The HTML will allow more features and be readable by modern browsers.

Over the past two years, the [[design:design-team|RFC Format Design Team]], formed during IETF 87, has discussed the more detailed requirements for the XML Canonical format as well as the requirements of the different Publication formats and their associated character encoding.  The results of that discussion, including documentation on items discussed but decided against as requirements, are documented in this wiki.

==== Reading list ====
The RFC Format is a large project that has required several documents to capture the requirements found in each aspect of the work. The documents depend on each other, and are moving through the community review and publication process as a set to help keep those relationships intact. Several documents require understanding a separate document for full comprehension of the material.

Below is the suggested reading order for the drafts that describe the new RFC format requirements. The design team has done a great job in pulling all fo this together, and many members of the community have reviewed these in parts and offered targeted feedback. Please take this time to review the drafts as a compendium, and then review the Statements of Work that describe the programming effort that will depend on these drafts as their requirements.

1. The big picture
  * Flanagan, H., "RFC Format Framework", Work in Progress, [[http://datatracker.ietf.org/doc/draft-flanagan-rfc-framework/|draft-flanagan-rfc-framework-04]], June 2015.

2. The underlying vocabulary
  * Hoffman, P., "The 'XML2RFC' version 3 Vocabulary", Work in Progress, [[https://datatracker.ietf.org/doc/draft-hoffman-xml2rfc/|draft-hoffman-xml2rfc-23]], September 2015.

3. The outputs
  * Hildebrand, J. and P. Hoffman, "HyperText Markup Language Request For Comments Format", Work in Progress, [[https://datatracker.ietf.org/doc/draft-hildebrand-html-rfc/|draft-hildebrand-html-rfc-10]], August 2015.
  * Flanagan, H., "Requirements for Plain Text RFCs", Work in Progress, [[https://datatracker.ietf.org/doc/draft-flanagan-plaintext/|draft-flanagan-plaintext-08]], September 2015.
  * Hansen, T., Masinter, L., and M. Hardy, "PDF for an RFC Series Output Document Format", Work in Progress, [[https://datatracker.ietf.org/doc/draft-hansen-rfc-use-of-pdf/|draft-hansen-rfc-use-of-pdf-08]], October 2015.
  * Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", Work in Progress, [[https://datatracker.ietf.org/doc/draft-brownlee-svg-rfc/|draft-brownlee-svg-rfc-12]], September 2015.

4. Generalized requirements
  * Flanagan, H., "The Use of Non-ASCII Characters in RFCs", Work in Progress, [[https://www.ietf.org/id/draft-flanagan-nonascii-05.pdf|draft-flanagan-nonascii-05]], August 2015. *Please review the PDF version only!*

5. Workflow and tools (note that the examples draft will not become an RFC, but is necessary for the project)
  * Hildebrand, J. and P. Hoffman, "RFC v3 Prep Tool Description", Work in Progress, [[https://datatracker.ietf.org/doc/draft-hoffman-rfcv3-preptool/|draft-hoffman-rfcv3-preptool-06]], September 2015.
  * Hoffman, P. and T. Hansen, "Examples of the 'XML2RFC' Version 2 and 3 Vocabularies", Work in Progress, [[http://datatracker.ietf.org/doc/draft-hoffman-rfcexamples/|draft-hoffman-rfcexamples-03]], May 2015.

6. The Statements of Work
  * http://www.nostrum.com/~rjsparks/rfced/


==== Format Requirements pulled from RFC 6949 ====

      1.  The content of an RFC must not change, regardless of format,
          once published.
          
      2.  The Canonical format must be persistent and reliable across a
          large variety of devices, operating systems, and editing tools
          for the indefinite future.  This means the format must be both
          readable and editable across commonly used devices, operating
          systems, and platforms for the foreseeable future.
          
      3.  While several Publication formats must be allowed, in order to
          continue support for the most basic reading and search tools
          and to provide continuity for the Series, at least one
          Publication format must be plain text.
          
      4.  The boilerplate and overall structure of the RFC must be in
          accordance with current RFC and Style Guide requirements (see
          [RFC5741]).
          
      5.  The documents must be made accessible to people with visual
          disabilities through such means as including alternative text
          for images and limiting the use of color.  See the W3C's
          accessibility documents [WCAG20] and the United Nations
          "Convention on the Rights of Persons with Disabilities"
          [UN2006] for guidance.  Appropriate authoring tools are highly
          desirable but focus on the creation of Internet-Drafts, a
          topic outside the scope of the RFC Editor.
          
      6.  The official language of the RFC Series is English.  ASCII is
          required for all text that must be read to understand or
          implement the technology described in the RFC.  Use of non-
          ASCII characters, expressed in a standard Unicode Encoding
          Form (such as UTF-8), must receive explicit approval from the
          document stream manager and will be allowed after the rules
          for the common use cases are defined in the Style Guide.
          
      7.  The Submission and Publication formats need to permit
          extending the set of metadata tags, for the addition of
          labeled metadata.  A predefined set of metadata tags must be
          created to make use of metadata tags consistent for the life
          of the Series.
          
      8.  Graphics may include ASCII art and a more complex form to be
          defined, such as SVG line art [SVG].  Color and grayscale will
          not be accepted.  RFCs must correctly display in monochromatic
          black-and-white to allow for monochrome displays, black-and-
          white printing, and support for visual disabilities.
          
      9.  The Canonical format must be renderable into self-contained
          Publication formats in order to be easily downloaded and read
          offline.
          
      10. Fixed-width fonts and non-reflowable text are required for
          ASCII-art sections, source code examples, and other places
          where strict alignment is required.
          
      11. At least one Publication format must support readable print to
          standard paper sizes.
          
      12. The Canonical format should be structured to enable easy
          program identification and parsing of code or specifications,
          such as MIB modules and ABNF.
RSE Wiki Archive

User Tools

Site Tools

Page Tools
