idnits 2.17.1 draft-flanagan-rfc-framework-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 21, 2014) is 3534 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 6635 (Obsoleted by RFC 8728) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group H. Flanagan 3 Internet-Draft RFC Editor 4 Intended status: Informational August 21, 2014 5 Expires: February 22, 2015 7 RFC Format Framework 8 draft-flanagan-rfc-framework-00 10 Abstract 12 The canonical format for the RFC Series has been plain-text, ASCII- 13 encoded for several decades. After extensive community discussion 14 and debate, the RFC Editor will be transitioning to XML as the 15 canonical format, with different publication formats rendered from 16 that base document. These changes are intended to increase the 17 usability of the RFC Series by offering documents that match the 18 needs of a wider variety of stakeholders. With these changes, 19 however, comes an increase in complexity for authors, consumers, and 20 the publisher of RFCs. This document serves as the framework that 21 describes the problems being solved and summarizes the many documents 22 that capture the specific requirements for each aspect of the change 23 in format. 25 Discussion of this draft takes place on the rfc-interest mailing list 26 (rfc-interest@rfc-editor.org), which has its home page at 27 https://www.rfc-editor.org/mailman/listinfo/rfc-interest. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on February 22, 2015. 46 Copyright Notice 48 Copyright (c) 2014 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 3 65 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 4. Overview of the Decision Making Process . . . . . . . . . . . 4 67 5. Key Changes . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 6. Document Summary . . . . . . . . . . . . . . . . . . . . . . 7 69 6.1. Canonical Format Documents . . . . . . . . . . . . . . . 7 70 6.1.1. XML . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 6.2. Publication Format Documents . . . . . . . . . . . . . . 8 72 6.2.1. HTML . . . . . . . . . . . . . . . . . . . . . . . . 8 73 6.2.2. PDF . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 6.2.3. Plain Text . . . . . . . . . . . . . . . . . . . . . 8 75 6.2.4. Potential Future Publication Formats . . . . . . . . 8 76 6.3. Figures and Artwork . . . . . . . . . . . . . . . . . . . 9 77 6.3.1. SVG . . . . . . . . . . . . . . . . . . . . . . . . . 9 78 6.4. Content and Page Layout . . . . . . . . . . . . . . . . . 9 79 6.4.1. Non-ASCII Characters . . . . . . . . . . . . . . . . 9 80 6.4.2. Style Guide . . . . . . . . . . . . . . . . . . . . . 9 81 6.4.3. CSS Requirements . . . . . . . . . . . . . . . . . . 9 82 7. Transition Plan . . . . . . . . . . . . . . . . . . . . . . . 9 83 7.1. Testing Phase . . . . . . . . . . . . . . . . . . . . . . 9 84 7.2. Transition Phase . . . . . . . . . . . . . . . . . . . . 10 85 7.3. Completion . . . . . . . . . . . . . . . . . . . . . . . 10 86 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 87 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 88 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 89 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 90 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 91 11.2. Informative References . . . . . . . . . . . . . . . . . 12 92 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 94 1. Introduction 96 In [RFC6949], "RFC Series Format Requirements and Future 97 Development," the need for additional features within RFCs such as 98 non-ASCII characters to respect author names, more advanced artwork 99 than ASCII art, and documents that could display properly on a wide 100 variety of devices was discussed. Based on the discussions with the 101 IETF community as well as other communities of interest, the decision 102 was made by the RFC Series Editor to explore a change to the format 103 of the Series [XML-ANNOUNCE]. This document serves as the framework 104 that describes the problems being solved and summarizes the documents 105 created to-date that capture the specific requirements for each 106 aspect of the change in format. 108 Key changes to the publication of RFCs are highlighted, and a 109 description of the transition plan that will take the Series from a 110 plain-text, ASCII-only format to the new formats are described 111 [RFC-INTEREST]. 113 This document is concerned with the production of RFCs, focusing on 114 the published formats. It does not address any changes to the 115 processes each stream uses to develop and review their submissions 116 (specifically, how Internet-Drafts will be developed). While I-Ds 117 have a similar set of issues and concerns, directly addressing those 118 issues for I-Ds will be discussed within each document stream. 120 2. Problem Statement 122 When the first RFCs were published 45 years ago, the tools to create 123 and read RFCs were limited. Distribution was in effect restricted to 124 individuals who had access to the network that became the Internet. 126 Today, there are nearly three billion people connected to the 127 Internet, and individuals from 45 countries or more regularly 128 attending IETF meetings over the last 5 years [ISTATS] [IETF numbers 129 are unpublished figures from the Secretariat; one could dig them out 130 from the plenary proceedings--how to reference?]. The Internet is 131 now global, and while the world has changed from when the first RFCs 132 were published, the Series remains critical to defining protocols, 133 standards, best practices, and more for this global network that 134 continues to grow. In order to make RFCs easily viewable to the 135 largest number of people possible, across a wide array of devices, 136 and to respect the diversity of authors and reference materials, it 137 is time to change from the tightly prescribed format of the RFC 138 Series. 140 All changes to the format of the RFC Series must consider the 141 requirements of a wide set of communities, over an extended length of 142 time. Existing authors and implementors, lawyers that argue 143 Intellectual Property Rights (IPR), and policy-makers that need to 144 know what to list in potential RFPs for their organizations, all have 145 preferences and requirements for their specific needs. The immediate 146 needs of today's communities must balance with the needs for long- 147 term archival storage. 149 3. Terminology 151 RFC 2119 keywords are not used in this document. 153 Terminology as described in RFC 6949: 155 ASCII: Coded Character Set - 7-bit American Standard Code for 156 Information Interchange, ANSI X3.4-1986 158 Canonical format: the authorized, recognized, accepted, and 159 archived version of the document 161 Metadata: information associated with a document so as to provide, 162 for example, definitions of its structure, or of elements within 163 the document such as its topic or author 165 Publication format: display and distribution format as it may be 166 read or printed after the publication process has completed 168 Reflowable text: text that automatically wraps to the next line in 169 a document as the user moves the margins of the text, either by 170 resizing the window or changing the font size 172 Revisable format: the format that will provide the information for 173 conversion into a Publication format; it is used or created by the 174 RFC Editor (see Section 2.3 for an explanation of current 175 practice) 177 Submission format: the format submitted to the RFC Editor for 178 editorial revision and publication 180 4. Overview of the Decision Making Process 182 Requirements, use cases, concerns, and suggestions were collected 183 from the communities of interest at every stage of the RFC format 184 update project. Input was received through the rfc-interest mailing 185 list, as well as in several face-to-face sessions at IETF meetings. 186 Updates regarding the status of the project were offered to the IETF 187 community during the IETF Technical Plenary as well as Format BoFs or 188 IAB sessions at IETF 84, IETF 85, IETF 88, IETF 89, and IETF 90 189 [IETF84] [IETF85] [IETF88] [IETF89] [IETF90]. 191 The first document published, RFC 6949, provided the first solid 192 documentation on what the requirements were for the Series and in 193 effect was the output from the first year of discussion on the topic 194 of RFC format. That RFC was published as an IAB stream document, 195 thus following the process described in RFC 4845, "Process for 196 Publication of IAB RFCs" [RFC4845]. 198 After the high-level requirements were published, an RFC Format 199 Design Team was brought together to start working out the necessary 200 details to develop the code needed to create new and changed formats. 201 While the bi-weekly calls for this team were limited to Design Team 202 members, review of the drafts produced by this team were done 203 publicly through requests for feedback on the rfc-interest mailing 204 list. Several of the drafts produced by the Design Team, including 205 the XML v2 and v3 drafts and the SVG profile drafts, were sent 206 through an early GenART review before starting the process to be 207 accepted as an IAB stream draft [GEN-ART]. 209 While the IETF community provided the majority of input on the 210 process, additional outreach opportunities were sought to gain input 211 from an even broader audience. Informal discussions were held with 212 participants at several International Association of Scientific, 213 Technical, and Medical Publisher events, and presentations made at 214 technical conferences such as the TERENA Networking Conference 2014 215 and NORDUnet 2014 [TNC2014] [NORDUnet link TBD]. 217 In order to respond to concerns regarding responses to subpoenas and 218 to understand the requirements for lawyers, advice was requested from 219 the IETF Trust legal team regarding what format or formats would be 220 considered reasonable when responding to a subpoena request for an 221 RFC. 223 Given that several other standards development organizations (SDOs) 224 do not offer plain-text documents, and in fact may offer more than 225 one format for their standards, informal input was sought from them 226 regarding their experience with supporting one or more non-plain-text 227 formats for their standards. 229 Finally, the entire process was reviewed regularly with the RFC 230 Series Oversight Committee and regular updates provided to the IAB 231 and IESG [RSOC]. 233 Where consensus was not reached during the process, the RSE made any 234 necessary final decisions, as per the guidance in RFC 6635, "RFC 235 Editor Model (Version 2)" [RFC6635]. 237 5. Key Changes 239 At the highest level, the changes being made to the RFC Format 240 involve breaking away from a pure-ASCII mode and moving to canonical 241 format that includes all the information required for rendering a 242 document into a wide variety of publication formats. The RFC Editor 243 will become responsible for more than just the canonical plain-text 244 file and the PDF-from-text format created at time of publication; 245 they will be creating several different formats in order to meet the 246 diverse requirements of the community. 248 The final XML file produced by the RFC Editor will be considered the 249 canonical format for RFCs; it is the lowest common denominator that 250 holds all the information intended for an RFC. PDF/A-3 will the the 251 publication format offered in response to subpoenas for RFCs 252 published through this new process, and will be developed with an eye 253 towards long-term archival storage. HTML will be the focus of 254 providing the most flexible set of features for an RFC, including 255 JavaScript to provide pointers to errata and other metadata. Plain- 256 text will continue to be offered in order to support existing tool 257 chains where practicable and the individuals who prefer to read RFCs 258 in this format. 260 A short summary of changes for each document format is listed below. 261 For more detail, please see the sections later in this document and 262 review the drafts. 264 XML: 266 o this is the canonical version that contains all information 267 necessary to render a variety of formats; any question about what 268 was intended in the publication will be answered from this format 270 o the canonical XML vocabulary will be the v3 vocabulary; authors 271 may submit drafts in v2 vocabulary, but the final publication will 272 convert that to v3 274 o any SVG information will be included inline in the final XML file 276 o automatically generated identifiers for sections, paragraphs, 277 figures, and tables in the final XML file 279 HTML: 281 o no longer derived from the plain-text document 283 o semantic HTML + override-able CSS 284 o line art, if available, will be included 286 o text will be reflowable 288 o JavaScript will be supported only as a publication option to 289 provide up-to-date links to errata and obsoleted or obsoleting 290 RFCs; documents must be readable when JavaScript is disabled 292 PDF: 294 o no longer derived from the plain-text document 296 o will look more like the HTML publication format than the plain- 297 text publication format 299 o will include a rich set of tags and metadata within the document 301 o will conform to the PDF/A-3 standard 303 o line art, if available, will be included 305 o will contain the source XML 307 Plain text: 309 o no longer the canonical version 311 o non-ASCII characters will be allowed in .txt files 313 o A Byte Order Mark (BOM) will be added at the start of each file 315 o widow and orphan control will not have priority 317 o authors may choose to have pointers to line art in other 318 publication formats in place of ASCII art in the .txt file 320 o both a paginated and unpaginated plain-text file will be created 322 o page headers and footers will not be used 324 6. Document Summary 326 6.1. Canonical Format Documents 327 6.1.1. XML 329 [draft-reschke-xml2rfc] - Describes the xml2rfc v2 vocabulary. While 330 in wide use today, this vocabulary had not been formally documented. 331 In order to understand what needed to change in the vocabulary to 332 allow for a more simple experience and additional features for 333 authors, the current vocabulary needed to be fully described. This 334 document, when published, will be obsoleted by the RFC published from 335 draft-hoffman-xml2rfc. 337 [draft-hoffman-xml2rfc] - Describes the xml2rfc v3 vocabulary. The 338 design goals in this vocabulary were to make the vocabulary more 339 intuitive for authors, and to expand the features to support the 340 changes being made in the publication process. This draft, when 341 published, will obsolete the RFC published from draft-reschke- 342 xml2rfc. 344 6.2. Publication Format Documents 346 6.2.1. HTML 348 [draft-hildebrand-html-rfc] - Describes the semantic HTML that will 349 be produced by the RFC Editor from the xml2rfc v3 files. 351 6.2.2. PDF 353 [draft-hansen-rfc-use-of-pdf] - Describes the tags and profiles that 354 will be used to create the new PDF format, including both the 355 internal structure and the visible layout of the file. A review of 356 the different versions of PDF is offered, with a recommendation of 357 what PDF standard should apply to RFCs. 359 6.2.3. Plain Text 361 [draft-flanagan-plaintext] - Describes the details of the plain text 362 format, focusing in particular on what is changing from the existing 363 plain-text output. 365 6.2.4. Potential Future Publication Formats 367 6.2.4.1. EPUB 369 This format is intended for use by ebook readers and will be 370 available for RFCs after the requirements have been defined. No 371 draft is currently available. 373 6.3. Figures and Artwork 375 6.3.1. SVG 377 [draft-brownlee-svg-rfc] - describes the profile for SVG line art. 378 SVG is an XML-based vocabulary for creating line drawings; SVG 379 information will be embedded within the canonical XML at time of 380 publication. 382 6.4. Content and Page Layout 384 6.4.1. Non-ASCII Characters 386 [draft-flanagan-nonascii] - There are security and readability 387 implications to moving outside the ASCII range of characters. This 388 draft focuses on exactly where and how non-ASCII characters may be 389 used in an RFC, with an eye towards keeping the documents as secure 390 and readable as possible given the information that needs to be 391 expressed. 393 6.4.2. Style Guide 395 [draft-iab-styleguide] - The RFC Style Guide was revised to remove as 396 much page formatting information as possible, focusing instead on 397 grammar, structure, and content of RFCs. Some of the changes 398 recommended, however, informed the XML v3 vocabulary. 400 6.4.3. CSS Requirements 402 Requirements under development; a draft will be posted and described 403 here in a later revision of this framework. 405 7. Transition Plan 407 7.1. Testing Phase 409 During document review and approved for submission phase, authors and 410 stream-approving body will select drafts to run through the new 411 process, noting that final publication will continue to be in plain 412 text only. In order to limit the amount of time the RFC Production 413 Center (RPC) spends on testing and QA, note that their priority is to 414 edit and publish documents, community assistance will be necessary to 415 help move this stage along. 417 Purpose of testing phase: to work with the community to identify and 418 fix bugs in the process and the code, before producing canonical, 419 immutable XML, and to collect additional feedback on the usability of 420 the new publication formats. 422 Criteria to indicate success: RPC and Tools Development team to 423 review bugs and decide when all show-stoppers have been dealt with. 425 7.2. Transition Phase 427 Documents submitted with an XML file will go through the new process 428 to produce a canonical XML document and the available publication 429 formats. Documents submitted as plain text will be published as 430 plain text only; they will not be converted to XML by the RPC. 432 Purpose of transition phase: to introduce the new publication process 433 to the community at large, and to identify and fix any additional 434 bugs in the code and the workflow. 436 Known risks: More work on the part of the RPC to support both old and 437 new publication processes for some unknown period of time. There is 438 potential for confusion as consumers of RFCs find some documents 439 published at this time with a full set of outputs, while other 440 documents only have plain text. There may be a delay in publication 441 as new bugs are found that must be fixed before the files can be 442 converted into the canonical format and associated publication 443 formats. 445 Criteria to indicate success: All major and critical bugs are 446 resolved. Rough consensus from the community regarding the utility 447 of the new formats. 449 7.3. Completion 451 All drafts submitted for publication, including text, will be 452 converted to XML and published as a Canonical XML file with available 453 publication formats. 455 Known risks: Higher work load for the RPC as, in addition to the 456 grammar and style editing, they also create and/or encourage best 457 practice with the XML structure. 459 Criteria to indicate success: Costs and resources stabilize for the 460 new process. 462 8. IANA Considerations 464 This document has no actions for IANA. 466 9. Security Considerations 468 Changing the format for RFCs involves modifying a great number of 469 components to publication. Understanding those changes and the 470 implications for the entire tool chain is critical so as to avoid 471 unintended bugs that would allow unintended changes to text. 472 Unintended changes to text could in turn corrupt a standard, practice 473 or critical piece of information about a protocol. 475 10. Acknowledgements 477 With many thanks to the RFC Format Design Team for their efforts in 478 making this transition successful: Nevil Brownlee (ISE), Tony Hansen, 479 Joe Hildebrand, Paul Hoffman, Ted Lemon, Julian Reschke, Adam Roach, 480 Alice Russo, Robert Sparks (Tools Team liaison), and Dave Thaler 482 11. References 484 11.1. Normative References 486 [RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format 487 Requirements and Future Development", RFC 6949, May 2013. 489 [draft-reschke-xml2rfc] 490 Reschke, J., "The 'XML2RFC' version 2 Vocabulary", draft- 491 reschke-xml2rfc-10 , July 2014. 493 [draft-hoffman-xml2rfc] 494 Hoffman, P., "The 'XML2RFC' version 3 Vocabulary", draft- 495 hoffman-xml2rfc-09 , July 2014. 497 [draft-brownlee-svg-rfc] 498 Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", draft- 499 brownlee-svg-rfc-07 , July 2014. 501 [draft-hildebrand-html-rfc] 502 Hildebrand, J. and H. Flanagan, ed, "HyperText Markup 503 Language Request For Comments Format", draft-hildebrand- 504 html-rfc-03 , June 2014. 506 [draft-hansen-rfc-use-of-pdf] 507 Hansen, T., Masinter, L., and M. Hardy, "PDF for an RFC 508 Series Output Document Format", draft-hansen-rfc-use-of- 509 pdf-02 , July 2014. 511 [draft-flanagan-plaintext] 512 Flanagan, H., "Requirements for Plain Text RFCs", draft- 513 flanagan-plaintext-01 , July 2014. 515 [draft-flanagan-nonascii] 516 Flanagan, H., "The Use of Non-ASCII Characters in RFCs", 517 draft-flanagan-nonascii-03 , July 2014. 519 11.2. Informative References 521 [RFC4845] Daigle, L. and Internet Architecture Board, "Process for 522 Publication of IAB RFCs", RFC 4845, July 2007. 524 [RFC6635] Kolkman, O., Halpern, J., and IAB, "RFC Editor Model 525 (Version 2)", RFC 6635, June 2012. 527 [draft-iab-styleguide] 528 Flanagan, H. and S. Ginoza, "The RFC Style Guide", draft- 529 iab-styleguide-02 , April 2014. 531 [GEN-ART] IETF, "General Area Review Team (Gen-ART)", n.d., 532 . 534 [IETF84] Flanagan, H., "IETF 84 Proceedings: RFC Format (rfcform)", 535 n.d., . 537 [IETF85] Flanagan, H., "IETF 85 Proceedings: RFC Format (rfcform)", 538 n.d., . 540 [IETF88] Flanagan, H., "IETF 88 Proceedings: RFC Format (rfcform)", 541 n.d., . 543 [IETF89] Flanagan, H., "IETF 89 Proceedings: RFC Format (rfcform)", 544 n.d., . 546 [IETF90] Flanagan, H., "IETF 90 Proceedings: RFC Format (rfcform)", 547 n.d., . 549 [ISTATS] "Internet Live Stats", n.d., 550 . 552 [RFC-INTEREST] 553 RFC Editor, "rfc-interest -- A list for discussion of the 554 RFC series and RFC Editor functions.", n.d., 555 . 558 [RSOC] IAB, "RFC Editor Program: The RSOC", n.d., 559 . 562 [TNC2014] Flanagan, H., "IETF Update - 'What's Hot?' - RFC Update", 563 n.d., . 565 [XML-ANNOUNCE] 566 "Subject: [rfc-i] Direction of the RFC Format Development 567 effort", n.d., . 570 Author's Address 572 Heather Flanagan 573 RFC Editor 575 Email: rse@rfc-editor.org