draft-iab-rfc-framework-04.txt   draft-iab-rfc-framework-05.txt 
Internet Architecture Board H. Flanagan Internet Architecture Board H. Flanagan
Internet-Draft RFC Editor Internet-Draft RFC Editor
Intended status: Informational February 5, 2016 Intended status: Informational June 21, 2016
Expires: August 8, 2016 Expires: December 23, 2016
RFC Format Framework RFC Format Framework
draft-iab-rfc-framework-04 draft-iab-rfc-framework-05
Abstract Abstract
The canonical format for the RFC Series has been plain-text, ASCII- The canonical format for the RFC Series has been plain-text, ASCII-
encoded for several decades. After extensive community discussion encoded for several decades. After extensive community discussion
and debate, the RFC Editor will be transitioning to XML as the and debate, the RFC Editor will be transitioning to XML as the
canonical format using the XML2RFC version 3 vocabulary. Different canonical format using the XML2RFC version 3 vocabulary. Different
publication formats will be rendered from that base document. These publication formats will be rendered from that base document. These
changes are intended to increase the usability of the RFC Series by changes are intended to increase the usability of the RFC Series by
offering documents that match the needs of a wider variety of offering documents that match the needs of a wider variety of
skipping to change at page 1, line 47 skipping to change at page 1, line 47
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 8, 2016. This Internet-Draft will expire on December 23, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 49 skipping to change at page 2, line 49
9.2. Style Guide . . . . . . . . . . . . . . . . . . . . . . . 10 9.2. Style Guide . . . . . . . . . . . . . . . . . . . . . . . 10
9.3. CSS Requirements . . . . . . . . . . . . . . . . . . . . 10 9.3. CSS Requirements . . . . . . . . . . . . . . . . . . . . 10
10. Transition Plan . . . . . . . . . . . . . . . . . . . . . . . 10 10. Transition Plan . . . . . . . . . . . . . . . . . . . . . . . 10
10.1. Statement of Work and RFP for Tool Development . . . . . 10 10.1. Statement of Work and RFP for Tool Development . . . . . 10
10.2. Testing and Transition . . . . . . . . . . . . . . . . . 10 10.2. Testing and Transition . . . . . . . . . . . . . . . . . 10
10.3. Completion . . . . . . . . . . . . . . . . . . . . . . . 12 10.3. Completion . . . . . . . . . . . . . . . . . . . . . . . 12
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
12. Security Considerations . . . . . . . . . . . . . . . . . . . 12 12. Security Considerations . . . . . . . . . . . . . . . . . . . 12
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12
14. Appendix - Change log . . . . . . . . . . . . . . . . . . . . 12 14. Appendix - Change log . . . . . . . . . . . . . . . . . . . . 12
14.1. draft-iab-rfc-framework-03 to -04 . . . . . . . . . . . 12 14.1. draft-iab-rfc-framework-04 to -05 . . . . . . . . . . . 13
14.2. draft-iab-rfc-framework-02 to -03 . . . . . . . . . . . 13 14.2. draft-iab-rfc-framework-03 to -04 . . . . . . . . . . . 13
14.3. draft-iab-rfc-framework-01 to -02 . . . . . . . . . . . 13 14.3. draft-iab-rfc-framework-02 to -03 . . . . . . . . . . . 13
14.4. draft-iab-rfc-framework-00 to -01 . . . . . . . . . . . 13 14.4. draft-iab-rfc-framework-01 to -02 . . . . . . . . . . . 13
14.5. draft-iab-rfc-framework-00 to -01 . . . . . . . . . . . 13
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
15.1. Normative References . . . . . . . . . . . . . . . . . . 13 15.1. Normative References . . . . . . . . . . . . . . . . . . 13
15.2. Informative References . . . . . . . . . . . . . . . . . 14 15.2. Informative References . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
[RFC6949], "RFC Series Format Requirements and Future Development," "RFC Series Format Requirements and Future Development" discussed the
discussed the need for additional features within RFCs such as non- need for additional features within RFCs such as non-ASCII characters
ASCII characters to respect author names, more advanced artwork than to respect author names, more advanced artwork than ASCII art, and
ASCII art, and documents that could display properly on a wide documents that could display properly on a wide variety of devices
variety of devices. Based on the discussions with the IETF community [RFC6949]. Based on the discussions with the IETF community as well
as well as other communities of interest, the RFC Series Editor as other communities of interest, the RFC Series Editor decided to
decided to explore a change to the format of the Series explore a change to the format of the Series [XML-ANNOUNCE]. This
[XML-ANNOUNCE]. This document serves as the framework that describes document serves as the framework that describes the problems being
the problems being solved and summarizes the documents created to- solved and summarizes the documents created to-date that capture the
date that capture the specific requirements for each aspect of the specific requirements for each aspect of the change in format.
change in format.
Key changes to the publication of RFCs are highlighted, and a Key changes to the publication of RFCs are highlighted, and a
transition plan that will take the Series from a plain-text, ASCII- transition plan that will take the Series from a plain-text, ASCII-
only format to the new formats is described on the rfc-interest only format to the new formats is described on the rfc-interest
mailing list [RFC-INTEREST]. mailing list [RFC-INTEREST].
This document is concerned with the production of RFCs, focusing on This document is concerned with the production of RFCs, focusing on
the published formats. It does not address any changes to the the published formats. It does not address any changes to the
processes each stream uses to develop and review their submissions processes each stream uses to develop and review their submissions
(specifically, how Internet-Drafts will be developed). While I-Ds (specifically, how Internet-Drafts will be developed). While I-Ds
have a similar set of issues and concerns, directly addressing those have a similar set of issues and concerns, directly addressing those
issues for I-Ds will be discussed within each document stream. issues for I-Ds will be discussed within each document stream.
The details described in this document are expected to change based The details described in this document are expected to change based
on experience gained in implementing the RFC production center's on experience gained in implementing the RFC Production Center's
toolset. Revised documents will be published capturing those changes toolset. Revised documents will be published capturing those changes
as the toolset is completed. Other implementers must not expect as the toolset is completed. Other implementers must not expect
those changes to remain backwards-compatible with the details those changes to remain backwards-compatible with the details
described this document. described this document.
2. Problem Statement 2. Problem Statement
There are nearly three billion people connected to the Internet, and There are nearly three billion people connected to the Internet, and
individuals from 45 countries or more regularly attending IETF individuals from 45 countries or more regularly attending IETF
meetings over the last 5 years [ISTATS]. The Internet is now global, meetings over the last five years [ISTATS]. The Internet is now
and while the world has changed from when the first RFCs were global, and while the world has changed from when the first RFCs were
published, the Series remains critical to defining protocols, published, the Series remains critical to defining protocols,
standards, best practices, and more for this global network that standards, best practices, and more for this global network that
continues to grow. In order to make RFCs easily viewable to the continues to grow. In order to make RFCs easily viewable to the
largest number of people possible, across a wide array of devices, largest number of people possible, across a wide array of devices,
and to respect the diversity of authors and reference materials, it and to respect the diversity of authors and reference materials while
is time to update the tightly prescribed format of the RFC Series. still recognizing the archival aspects of the Series, it is time to
update the tightly prescribed format of the RFC Series.
All changes to the format of the RFC Series must consider the All changes to the format of the RFC Series must consider the
requirements of a wide set of communities, over an extended length of requirements of a wide set of communities, over an extended length of
time. For example, existing authors and implementers, lawyers that time. For example, existing authors and implementers, lawyers that
argue Intellectual Property Rights (IPR), educators, managers, and argue Intellectual Property Rights (IPR), educators, managers, and
policy-makers that need to know what to list in potential RFPs for policy-makers that need to know what to list in potential RFPs for
their organizations, all have preferences and requirements for their their organizations, all have preferences and requirements for their
specific needs. The immediate needs of today's communities must be specific needs. The immediate needs of today's communities must be
balanced with the needs for long-term archival storage. balanced with the needs for long-term archival storage.
skipping to change at page 5, line 25 skipping to change at page 5, line 26
of IAB RFCs" [RFC4845]. of IAB RFCs" [RFC4845].
After the high-level requirements were published, the RFC Series After the high-level requirements were published, the RFC Series
Editor (RSE) brought together an RFC Format Design Team to start Editor (RSE) brought together an RFC Format Design Team to start
working out the necessary details to develop the code needed to working out the necessary details to develop the code needed to
create new and changed formats. The design team discussed moving create new and changed formats. The design team discussed moving
away from the existing xml2rfc vocabulary, but with such a strong away from the existing xml2rfc vocabulary, but with such a strong
existing support base within the community and no clear value with existing support base within the community and no clear value with
other XML vocabularies or schemas, the decision was made to work with other XML vocabularies or schemas, the decision was made to work with
the XML2RFC version 2 (xml2rfc v2) model and use it as the base for the XML2RFC version 2 (xml2rfc v2) model and use it as the base for
the new format world [I-D.iab-xml2rfcv2]. Part of this discussion the new format world [RFC7749]. Part of this discussion included a
included a decision to stop using an XML document type definition decision to stop using an XML document type definition (DTD) in favor
(DTD) in favor of a Regular Language for XML Next General (Relax NG) of a Regular Language for XML Next General (Relax NG) model using a
model using a defined vocabulary. While the bi-weekly calls for this defined vocabulary. While the bi-weekly calls for this team were
team were limited to Design Team members, review of the decisions as limited to Design Team members, review of the decisions as documented
documented in the drafts produced by this team were done publicly in the drafts produced by this team were done publicly through
through requests for feedback on the rfc-interest mailing list. requests for feedback on the rfc-interest mailing list. Several of
Several of the drafts produced by the Design Team, including the the drafts produced by the Design Team, including the xml2rfc v2 and
xml2rfc v2 and v3 drafts and the SVG profile drafts, were sent v3 drafts and the SVG profile drafts, were sent through an early
through an early GenART review before starting the process to be GenART review before starting the process to be accepted as an IAB
accepted as an IAB stream draft [GEN-ART] [I-D.iab-xml2rfc]. stream draft [GEN-ART] [I-D.iab-xml2rfc].
While the IETF community provided the majority of input on the While the IETF community provided the majority of input on the
process, additional outreach opportunities were sought to gain input process, additional outreach opportunities were sought to gain input
from an even broader audience. Informal discussions were held with from an even broader audience. Informal discussions were held with
participants at several International Association of Scientific, participants at several International Association of Scientific,
Technical, and Medical Publisher events, and presentations made at Technical, and Medical Publisher events, and presentations made at
technical conferences such as the TERENA Networking Conference 2014 technical conferences such as the TERENA Networking Conference 2014
and NORDUnet 2014 [TNC2014] [NDN2014]. and NORDUnet 2014 [TNC2014] [NDN2014].
In order to respond to concerns regarding responses to subpoenas and In order to respond to concerns regarding responses to subpoenas and
skipping to change at page 7, line 36 skipping to change at page 7, line 36
includes all uses of xinclude, src attributes (such as in includes all uses of xinclude, src attributes (such as in
<artwork> or <sourcecode> elements), include-like processing <artwork> or <sourcecode> elements), include-like processing
instructions, and externally defined entities. instructions, and externally defined entities.
o The final XML will not contain comments or processing o The final XML will not contain comments or processing
instructions. instructions.
o The final XML will not contain src attributes for <artwork> or o The final XML will not contain src attributes for <artwork> or
<sourcecode> elements. <sourcecode> elements.
[I-D.iab-xml2rfcv2] Describes the xml2rfc v2 vocabulary. While in [RFC7749] Describes the xml2rfc v2 vocabulary. While in wide use
wide use today, this vocabulary had not been formally documented. In today, this vocabulary had not been formally documented. In order to
order to understand what needed to change in the vocabulary to allow understand what needed to change in the vocabulary to allow for a
for a more simple experience and additional features for authors, the more simple experience and additional features for authors, the
current vocabulary needed to be fully described. This document, when current vocabulary needed to be fully described. This document, when
published, will be obsoleted by the RFC published from draft-iab- published, will be obsoleted by the RFC published from draft-iab-
xml2rfc. xml2rfc.
[I-D.iab-xml2rfc] Describes the xml2rfc v3 vocabulary. The design [I-D.iab-xml2rfc] Describes the xml2rfc v3 vocabulary. The design
goals in this vocabulary were to make the vocabulary more intuitive goals in this vocabulary were to make the vocabulary more intuitive
for authors, and to expand the features to support the changes being for authors, and to expand the features to support the changes being
made in the publication process. This draft, when published, will made in the publication process. This draft, when published, will
obsolete the RFC published from draft-iab-xml2rfcv2. obsolete the RFC 7749.
7. Publication Format Documents 7. Publication Format Documents
7.1. HTML 7.1. HTML
[I-D.iab-html-rfc] - Describes the semantic HTML that will be [I-D.iab-html-rfc] - Describes the semantic HTML that will be
produced by the RFC Editor from the xml2rfc v3 files. produced by the RFC Editor from the xml2rfc v3 files.
Key points regarding the HTML output: Key points regarding the HTML output:
skipping to change at page 11, line 11 skipping to change at page 11, line 11
approving bodies will select drafts to run through the proposed new approving bodies will select drafts to run through the proposed new
publication process. While the final RFCs published during this time publication process. While the final RFCs published during this time
will continue as plain-text and immutable once published, the will continue as plain-text and immutable once published, the
feedback process is necessary to bootstrap initial testing. These feedback process is necessary to bootstrap initial testing. These
early tests will target finding issues with the proposed xml2rfc v3 early tests will target finding issues with the proposed xml2rfc v3
vocabulary that result in poorly formed publication formats as well vocabulary that result in poorly formed publication formats as well
as issues that prevent proper review of submitted drafts. as issues that prevent proper review of submitted drafts.
Feedback will result in regular iteration of the basic code and XML Feedback will result in regular iteration of the basic code and XML
vocabulary. In order to limit the amount of time the RFC Production vocabulary. In order to limit the amount of time the RFC Production
Center (RPC) spends on testing and QA, note that their priority is to Center (RPC) spends on testing and QA, their priority will be to edit
edit and publish documents, community assistance will be necessary to and publish documents; therefore, community assistance will be
help move this stage along. A mailing list and experimental source necessary to help move this stage along. A mailing list and
directory on the RFC Editor website will be created for community experimental source directory on the RFC Editor website will be
members willing to assist in the detailed review of the XML and created for community members willing to assist in the detailed
publication formats. Editorial checks of the publication formats by review of the XML and publication formats. Editorial checks of the
the community are out of scope; the focus will be the QA of each publication formats by the community are out of scope; the focus will
available output, checking for inconsistencies across formats. be the QA of each available output, checking for inconsistencies
across formats.
The purpose of testing phase is to work with the community to The purpose of testing phase is to work with the community to
identify and fix bugs in the process and the code, before producing identify and fix bugs in the process and the code, before producing
canonical, immutable XML, and to collect additional feedback on the canonical, immutable XML, and to collect additional feedback on the
usability of the new publication formats. usability of the new publication formats.
Any modifications to the draft review process, up to and including
AUTH48, will happen with the community and the stream approving
bodies as we learn more about the features and outputs of the new
publication tools. Defining those processes is out of scope for this
document.
Success will be measured by the closure of all bugs which had been Success will be measured by the closure of all bugs which had been
identified by the RPC and the Tools Development team as fatal and identified by the RPC and the Tools Development team as fatal and
consensus on the readiness of the XML vocabulary and final XML files consensus on the readiness of the XML vocabulary and final XML files
for publication. The actual rendering engine can go through further for publication. The actual rendering engine can go through further
review and iteration, as the publication formats may be republished review and iteration, as the publication formats may be republished
as needed. as needed.
Authors are not required to submit their approved drafts in an XML Authors are not required to submit their approved drafts in an XML
format, though they are strongly encouraged to do so; plain-text will format, though they are strongly encouraged to do so; plain-text will
also remain an option for the foreseeable future. However, documents also remain an option for the foreseeable future. However, documents
skipping to change at page 12, line 43 skipping to change at page 13, line 5
With many thanks to the RFC Format Design Team for their efforts in With many thanks to the RFC Format Design Team for their efforts in
making this transition successful: Nevil Brownlee (ISE), Tony Hansen, making this transition successful: Nevil Brownlee (ISE), Tony Hansen,
Joe Hildebrand, Paul Hoffman, Ted Lemon, Julian Reschke, Adam Roach, Joe Hildebrand, Paul Hoffman, Ted Lemon, Julian Reschke, Adam Roach,
Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler. Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler.
14. Appendix - Change log 14. Appendix - Change log
To be removed by RFC Editor To be removed by RFC Editor
14.1. draft-iab-rfc-framework-03 to -04 14.1. draft-iab-rfc-framework-04 to -05
Introduction: minor clarifications
Updated references
14.2. draft-iab-rfc-framework-03 to -04
Introduction: editorial changes Introduction: editorial changes
Clarified that submitted plain text will be converted to XML by the Clarified that submitted plain text will be converted to XML by the
RPC; the XML will be used to render all output formats. RPC; the XML will be used to render all output formats.
14.2. draft-iab-rfc-framework-02 to -03 14.3. draft-iab-rfc-framework-02 to -03
HTML output: clarified expectations around use of JavaScript. HTML output: clarified expectations around use of JavaScript.
14.3. draft-iab-rfc-framework-01 to -02 14.4. draft-iab-rfc-framework-01 to -02
Introduction: Removed some unnecessary history. Introduction: Removed some unnecessary history.
14.4. draft-iab-rfc-framework-00 to -01 14.5. draft-iab-rfc-framework-00 to -01
Decision Making Process: noted taht other XML schemas and Decision Making Process: noted taht other XML schemas and
vocabularies were considered by the design team vocabularies were considered by the design team
XML for RFCs: "boilerplate at time of publication" XML for RFCs: "boilerplate at time of publication"
HTML: clarified that JavaScript should not impact readability of the HTML: clarified that JavaScript should not impact readability of the
document as it looked at time of publication document as it looked at time of publication
15. References 15. References
15.1. Normative References 15.1. Normative References
[RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format [RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format
Requirements and Future Development", RFC 6949, Requirements and Future Development", RFC 6949,
DOI 10.17487/RFC6949, May 2013, DOI 10.17487/RFC6949, May 2013,
<http://www.rfc-editor.org/info/rfc6949>. <http://www.rfc-editor.org/info/rfc6949>.
[RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary",
RFC 7749, DOI 10.17487/RFC7749, February 2016,
<http://www.rfc-editor.org/info/rfc7749>.
[I-D.iab-xml2rfc] [I-D.iab-xml2rfc]
Hoffman, P., "The "xml2rfc" version 3 Vocabulary", draft- Hoffman, P., "The "xml2rfc" version 3 Vocabulary", draft-
iab-xml2rfc-02 (work in progress), January 2016. iab-xml2rfc-03 (work in progress), February 2016.
[I-D.iab-xml2rfcv2]
Reschke, J., "The 'XML2RFC' version 2 Vocabulary", draft-
iab-xml2rfcv2-02 (work in progress), September 2015.
[I-D.iab-svg-rfc] [I-D.iab-svg-rfc]
Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", draft- Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", draft-
iab-svg-rfc-01 (work in progress), January 2016. iab-svg-rfc-02 (work in progress), February 2016.
[I-D.iab-html-rfc] [I-D.iab-html-rfc]
Hildebrand, J. and P. Hoffman, "HyperText Markup Language Hildebrand, J. and P. Hoffman, "HyperText Markup Language
Request For Comments Format", draft-iab-html-rfc-01 (work Request For Comments Format", draft-iab-html-rfc-02 (work
in progress), January 2016. in progress), February 2016.
[I-D.iab-rfc-use-of-pdf] [I-D.iab-rfc-use-of-pdf]
Hansen, T., Masinter, L., and M. Hardy, "PDF for an RFC Hansen, T., Masinter, L., and M. Hardy, "PDF for an RFC
Series Output Document Format", draft-iab-rfc-use-of- Series Output Document Format", draft-iab-rfc-use-of-
pdf-01 (work in progress), January 2016. pdf-02 (work in progress), May 2016.
[I-D.iab-rfc-plaintext] [I-D.iab-rfc-plaintext]
Flanagan, H., "Requirements for Plain-Text RFCs", draft- Flanagan, H., "Requirements for Plain-Text RFCs", draft-
iab-rfc-plaintext-01 (work in progress), January 2016. iab-rfc-plaintext-03 (work in progress), May 2016.
[I-D.iab-rfc-nonascii] [I-D.iab-rfc-nonascii]
Flanagan, H., "The Use of Non-ASCII Characters in RFCs", Flanagan, H., "The Use of Non-ASCII Characters in RFCs",
draft-iab-rfc-nonascii-00 (work in progress), January draft-iab-rfc-nonascii-02 (work in progress), April 2016.
2016.
[I-D.iab-rfc-css] [I-D.iab-rfc-css]
Flanagan, H., "CSS Requirements for RFCs", draft-iab-rfc- Flanagan, H., "CSS Requirements for RFCs", draft-iab-rfc-
css-00 (work in progress), January 2016. css-00 (work in progress), January 2016.
15.2. Informative References 15.2. Informative References
[RFC4845] Daigle, L., Ed. and Internet Architecture Board, "Process [RFC4845] Daigle, L., Ed. and Internet Architecture Board, "Process
for Publication of IAB RFCs", RFC 4845, for Publication of IAB RFCs", RFC 4845,
DOI 10.17487/RFC4845, July 2007, DOI 10.17487/RFC4845, July 2007,
 End of changes. 25 change blocks. 
66 lines changed or deleted 78 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/