idnits 2.17.1 draft-iab-rfc-plaintext-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 (January 12, 2016) is 3019 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-04) exists of draft-iab-xml2rfc-01 ** Obsolete normative reference: RFC 5741 (Obsoleted by RFC 7841) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Architecture Board H. Flanagan 3 Internet-Draft RFC Editor 4 Intended status: Informational January 12, 2016 5 Expires: July 15, 2016 7 Requirements for Plain-Text RFCs 8 draft-iab-rfc-plaintext-00 10 Abstract 12 In 2013, after a great deal of community discussion, the decision was 13 made to shift from the plain-text, ASCII-only canonical format for 14 RFCs to XML as the canonical format with more human-readable formats 15 rendered from that XML. The high-level requirements that informed 16 this change were defined in RFC6949, "RFC Series Format Requirements 17 and Future Development." Plain text remains an important format for 18 many in the IETF community, and will still be one of the publication 19 formats rendered from the XML. This draft documents the rendering 20 requirements for the plain-text RFC publication format. These 21 requirements do not apply to plain-text RFCs published before the 22 format transition. 24 Editorial Note (To be removed by the RFC Editor) 26 Discussion of this draft takes place on the rfc-interest mailing list 27 (rfc-interest@rfc-editor.org), which has its home page at 28 https://www.rfc-editor.org/mailman/listinfo/rfc-interest. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on July 15, 2016. 47 Copyright Notice 49 Copyright (c) 2016 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Character Encoding . . . . . . . . . . . . . . . . . . . . . 4 66 3. Figures and Artwork . . . . . . . . . . . . . . . . . . . . . 4 67 4. General Page Format Layout . . . . . . . . . . . . . . . . . 5 68 4.1. Headers and Footers . . . . . . . . . . . . . . . . . . . 5 69 4.2. Table of Contents . . . . . . . . . . . . . . . . . . . . 5 70 4.3. Line Width . . . . . . . . . . . . . . . . . . . . . . . 5 71 4.4. Line Spacing . . . . . . . . . . . . . . . . . . . . . . 5 72 4.5. Hyphenation . . . . . . . . . . . . . . . . . . . . . . . 5 73 5. Elements from the xml2rfc v3 vocabulary . . . . . . . . . . . 6 74 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 75 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 76 8. Security Considerations . . . . . . . . . . . . . . . . . . . 6 77 9. Change Log for the Draft . . . . . . . . . . . . . . . . . . 6 78 9.1. draft-flanagan-plaintext-09 to draft-iab-rfc-plaintext-00 6 79 9.2. -08 to -09 . . . . . . . . . . . . . . . . . . . . . . . 6 80 9.3. -07 to -08 . . . . . . . . . . . . . . . . . . . . . . . 6 81 9.4. -06 to -07 . . . . . . . . . . . . . . . . . . . . . . . 7 82 9.5. -05 to -06 . . . . . . . . . . . . . . . . . . . . . . . 7 83 9.6. -04 to -05 . . . . . . . . . . . . . . . . . . . . . . . 7 84 9.7. -03 to -04 . . . . . . . . . . . . . . . . . . . . . . . 7 85 9.8. -02 to -03 . . . . . . . . . . . . . . . . . . . . . . . 7 86 9.9. -01 to -02 . . . . . . . . . . . . . . . . . . . . . . . 7 87 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 88 10.1. Normative References . . . . . . . . . . . . . . . . . . 8 89 10.2. Informative References . . . . . . . . . . . . . . . . . 8 90 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 92 1. Introduction 94 In 2013, after a great deal of community discussion, the decision was 95 made to shift from the plain-text, ASCII-only canonical format for 96 RFCs to XML as the canonical format [XML-ANNOUNCE]. The high-level 97 requirements that informed this change were defined in [RFC6949], 98 "RFC Series Format Requirements and Future Development." Plain text 99 remains an important format for many in the IETF community, and will 100 still be one of the publication formats rendered from the XML. This 101 draft documents the rendering requirements for the plain-text RFC 102 publication format. These requirements do not apply to plain-text 103 RFCs published before the format transition. 105 The Unicode Consortium defines 'plain text' as "Computer-encoded text 106 that consists only of a sequence of code points from a given 107 standard, with no other formatting or structural information. Plain 108 text interchange is commonly used between computer systems that do 109 not share higher-level protocols." [UNICODE-GLOSSARY] In other 110 words, plain-text files cannot include embedded character formatting 111 or style information. The actual character encoding, however, is not 112 limited to any particular sequence of code points. 114 A plain-text output for RFCs will continue to be required for the 115 foreseeable future. The details of what that means for RFCs in terms 116 of which character encoding may be used, what the page layout will 117 look like, how to handle figures and artwork, and how pagination will 118 be handled, are documented in this memo. For more details on general 119 style, see "The RFC Style Guide." [RFC7322] 121 The following assumptions drive the changes in the plain-text output 122 for RFCs: 124 o The existing tools used by the RFC Editor and many members of the 125 author community to create the text file are complicated to change 126 and support; manual manipulation is often required for the final 127 output. In particular, handling page breaks and associated widows 128 and orphans for paginated output is tricky [WIDOWS]. 130 o Additional publication formats--for example: PDF, HTML--will be 131 available that will offer features such as markup, pretty 132 printing, etc. 134 o There is an extensive tool chain in existence among the community 135 to work with plain-text documents. Similar functionality may be 136 possible with other publication formats, but the workflow that 137 uses the existing tool chain should be supported as much as is 138 considered practical. 140 Where practical, the original guidance for the structure of a plain- 141 text RFC has been kept, such as with line lengths, lines per page, 142 etc. [INS2AUTH] 144 Note that this document provides guidance for plain-text RFCs; 145 Internet-Drafts are out of scope. 147 The details described in this document are expected to change based 148 on experience gained in implementing the RFC production center's 149 toolset. Revised documents will be published capturing those changes 150 as the toolset is completed. Other implementers must not expect 151 those changes to remain backwards-compatible with the details 152 described this document. 154 2. Character Encoding 156 Plain-text files for RFCs will use the UTF-8 [RFC3629] character 157 encoding. That said, the use of non-ASCII characters will be only 158 allowed in a limited and controlled fashion. 160 Many elements within the xml2rfc v3 vocabulary have an attribute for 161 the ASCII equivalent to a non-ASCII character string. The ASCII 162 equivalent will be rendered within the plain-text as per the guidance 163 in "The Use of Non-ASCII Characters in RFCs" [I-D.flanagan-nonascii]. 164 Please view the PDF version of that draft. 166 The plain-text file will include a byte order mark (BOM) to provide 167 text reader software with in-band information about the character 168 encoding scheme used. 170 3. Figures and Artwork 172 Artwork is defined as anything marked by the XML >artwork< element 173 (see Section 2.5 of "The 'XML2RFC' version 3 Vocabulary" 174 [I-D.iab-xml2rfc]. Only the 'type=ascii-art' will be rendered within 175 the plain-text format. This marks figures drawn with ASCII 176 characters. 178 If the canonical format includes figures or artwork other than ASCII- 179 art, then the plain-text output must include a pointer to the 180 relevant figure in the HTML version of the RFC to allow readers to 181 see the relevant artwork. 183 Authors who wish to include ASCII-art for the plain-text file and SVG 184 art for the other outputs may do so, but they should be aware of the 185 potential for confusion to individuals reading the RFC with two 186 unique diagrams describing the same content. If there is conflicting 187 information between the publication formats, please review the XML 188 and PDF files to resolve the conflict. 190 4. General Page Format Layout 192 One plain-text output will be created during the publication process 193 with basic pagination that includes a form feed instruction every 58 194 lines at most, including blank lines. Instructions or a script will 195 be made available by and for the community to strip out pagination as 196 per individual preference. 198 4.1. Headers and Footers 200 The front matter on the front page (such as the RFC number and 201 category), and the back matter on the last page (the author's full 202 names and contact information) will continue with the structure 203 described in RFC 5741 [RFC5741], "RFC Streams, Headers, and 204 Boilerplates". Running headers and footers will no longer be added. 206 4.2. Table of Contents 208 In order to retain similar content wherever possible between the 209 various publication formats, the Table of Contents will list section 210 and subsection numbers and titles, but will not include page numbers. 212 4.3. Line Width 214 Each line must be limited to 72 characters followed by the character 215 sequence that denotes an end-of-line (EOL). The EOL sequence used by 216 the RFC Editor will be the two-character sequence CR LF (Carriage 217 Return followed by Line Feed). This limit includes any left-side 218 indentation. 220 Note that the EOL used by the RFC Editor may change with different 221 transports and as displayed in different display software. 223 4.4. Line Spacing 225 Use single-spaced text within a paragraph, and one blank line between 226 paragraphs. 228 4.5. Hyphenation 230 Hyphenated words (e.g., "Internet-Draft"), should not be split across 231 successive lines. 233 5. Elements from the xml2rfc v3 vocabulary 235 The plain-text does not attempt to render anything but the most basic 236 document metadata from the XML. The document layout and structure is 237 instead guided directly by the RFC Style Guide and the updates 238 reflected in the web portion of the Style Guide [STYLEWEB]. URIs 239 that occur in targets may be placed into parenthetical expressions or 240 reference entries [I-D.iab-xml2rfc]. 242 Since plain-text cannot include any rich-text-style formatting, such 243 as bold or italic fonts, tags such as and will not be 244 rendered in any way in the plain-text draft. 246 6. Acknowledgements 248 This draft owes a great deal of thanks to the efforts of the RFC 249 Format Design Team: Nevil Brownlee, Tony Hansen, Joe Hildebrand, Paul 250 Hoffman, Ted Lemon, Julian Reschke, Adam Roach, Alice Russo, Robert 251 Sparks, and David Thaler. 253 7. IANA Considerations 255 This memo includes no requests to IANA. 257 8. Security Considerations 259 The requirements of the plaintext format involve no significant 260 security considerations. As part of the larger format project, 261 however, unintended changes to the text as a result of the 262 transformation from the base XML file could in turn corrupt a 263 standard, practice or critical piece of information about a protocol. 265 9. Change Log for the Draft 267 9.1. draft-flanagan-plaintext-09 to draft-iab-rfc-plaintext-00 269 Figures and Artwork, Character Encoding: included additional detail 270 regarding how these items will be flagged within the XML. 272 9.2. -08 to -09 274 Security Considerations: added text 276 9.3. -07 to -08 278 Change log: forgot to update the change log for the -06 to -07 279 changes. 281 9.4. -06 to -07 283 Introduction: updated to state that this document does not require 284 backwards compatibility. 286 9.5. -05 to -06 288 Abstract: Changed "cut over" to "transition" 290 Elements from xml2rfc v3: emphasized that doc structure is guided by 291 the RFC Style Guide 293 9.6. -04 to -05 295 Abstract and Introduction: Revised for better readability; clarified 296 the definition and implications of the term "plain-text" 298 General Page Format Layout: Added explicit EOL detail and added some 299 clarification regarding pagination 301 Elements from the xml2rfc v3 vocabulary: section added 303 9.7. -03 to -04 305 Change Log for the Draft: forgot to complete the change log between 306 the various revisions of the draft 308 9.8. -02 to -03 310 Abstract: expanded 312 Introduction: adjusted language of assumptions 314 Figures and Artwork: adjusted to indicate where to go in case 315 information for the images conflicts between different formats 317 General Page Layout: switched back to producing one basic paginated 318 format, with an expectation of instructions and/or a script to create 319 local, unpaginated copies for individual use. 321 9.9. -01 to -02 323 Introduction: added pointer to original page layout information 325 Character encoding: clarified language around encoding and use of 326 BOMs 327 General Page Format Layout: removed increased line width requirement; 328 added sections on Line Width, Line Spacing, and Hyphenation (pulled 329 from 2223-bis 331 10. References 333 10.1. Normative References 335 [I-D.flanagan-nonascii] 336 Flanagan, H., "The Use of Non-ASCII Characters in RFCs", 337 draft-flanagan-nonascii-06 (work in progress), November 338 2015. 340 [I-D.iab-xml2rfc] 341 Hoffman, P., "The 'XML2RFC' version 3 Vocabulary", draft- 342 iab-xml2rfc-01 (work in progress), January 2016. 344 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 345 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 346 2003, . 348 [RFC5741] Daigle, L., Ed., Kolkman, O., Ed., and IAB, "RFC Streams, 349 Headers, and Boilerplates", RFC 5741, 350 DOI 10.17487/RFC5741, December 2009, 351 . 353 [RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format 354 Requirements and Future Development", RFC 6949, 355 DOI 10.17487/RFC6949, May 2013, 356 . 358 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 359 DOI 10.17487/RFC7322, September 2014, 360 . 362 10.2. Informative References 364 [INS2AUTH] 365 RFC Editor, "Instructions to Request for Comments (RFC) 366 Authors", August 2004, . 369 [STYLEWEB] 370 RFC Editor, "Web Portion of the Style Guide", May 2015, 371 . 373 [UNICODE-GLOSSARY] 374 The Unicode Consortium, "Glossary of Unicode Terms", 2014, 375 . 377 [WIDOWS] Wikipedia, "Widows and orphans", October 2014, 378 . 380 [XML-ANNOUNCE] 381 Flanagan, H., "Subject: Direction of the RFC Format 382 Development effort", May 2013, . 385 Author's Address 387 Heather Flanagan 388 RFC Editor 390 Email: rse@rfc-editor.org 391 URI: http://orcid.org/0000-0002-2647-2220