idnits 2.17.1 draft-hoffman-rfcformat-canon-others-03.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 (July 12, 2012) is 4307 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Obsolete informational reference (is this intentional?): RFC 2223 (Obsoleted by RFC 7322) -- Obsolete informational reference (is this intentional?): RFC 2629 (Obsoleted by RFC 7749) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hoffman 3 Internet-Draft VPN Consortium 4 Intended status: Standards Track July 12, 2012 5 Expires: January 13, 2013 7 Proposal for Canonical and Other Formats for RFCs 8 draft-hoffman-rfcformat-canon-others-03 10 Abstract 12 This document proposes a new, XML-based canonical format for RFCs 13 that explicitly allows external art as a normative part of the RFC. 14 If the RFC Editor chooses this format, they will also publish non- 15 canonical versions of RFCs in order to accomodate the largest target 16 audience of readers. Having a simple, stable canonical format and a 17 varying number of non-canonical formats that can change over time 18 allows the RFC Editor to add useful formats, particularly in HTML, 19 that can keep up with the needs of all RFC readers. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 13, 2013. 38 Copyright Notice 40 Copyright (c) 2012 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 1. Introduction 55 A clear result of the decades-long discussion about the format of 56 published RFCs is that different RFC readers have different needs and 57 desires. No single format will be sufficient, or even useful, to all 58 people who read RFCs. Another clear result is that the format 59 described in [RFC2223] and its follow-ons is no longer the best 60 format for publishing protocols, process descriptions, research 61 findings, and the many other types of documents that are part of the 62 modern RFC series. 64 This document proposes to deal with these issues in a way that meets 65 the needs and desires of the widespread RFC-reading community. For 66 every RFC, the RFC Editor will publish both a canonical version of 67 the RFC that is in XML format and multiple additional forms of the 68 RFC, most notably at least in one or more HTML formats. The XML 69 format used will likely be an updated version of that from [RFC2629], 70 most notably to include in-line graphic art. 72 It is noted that XML files are not easily readable. However, it is 73 also noted that the canonical version of an RFC doesn't need to be 74 easily readable: only the non-canonical formats derived from the 75 canonical version need to be readable. 77 Today, all RFCs are easily retrievable by all readers. In the 78 future, all of the versions of an RFC and its art must be easily 79 accessible as well. To make this easier, the RFC Editor will 80 establish a permanent URL template for each RFC that leads to a page 81 that lists all of the versions and art; a copy of that URL will be 82 included near the beginning of the RFC in the boilerplate so that new 83 RFC readers can find it. Further, it will be easy for advanced RFC 84 users to mirror the entire collection of RFC material. 86 A major motivation behind the "one canonical, many non-canonical" 87 proposal is to allow the RFC Editor to easily change the non- 88 canonical formats in the future without having to change the 89 canonical format. For example, the recent discussion of RFC formats 90 has shown that many people strongly desire good HTML versions of 91 RFCs, but there is not agreement of exactly what format the HTML 92 should take. Further, it is completely clear that the HTML standard 93 will evolve in the coming years and decades, and some of the new 94 features that will be added will be quite useful in RFCs. Allowing 95 the RFC Editor to add additional HTML formats to the RFC collection, 96 even for RFCs that have been published in the past, gives the 97 greatest value to RFC readers without forcing any changes on the 98 canonical RFC format. 100 Similarly, it is clear that HTML is not the only useful format for 101 RFCs. Some people really like plain text; others want PDFs or other 102 printer-ready paginated formats; still others want different formats 103 that can be converted to different reading devices. Some people want 104 detailed metadata for RFCs so that they can better mine them for 105 relevant information; such metadata can be contained in either XML or 106 HTML formats. All of these people can be accommodated by the RFC 107 Editor publishing multiple non-canonical versions of RFCs. The 108 canonical version of the RFC and all the non-canonical versions of 109 the RFC should have predictable URLs so that tools can easily find 110 (for example) an RFC in the reader's preferred HTML style just by 111 knowing the RFC number. 113 The method that the RFC Editor uses to create the non-canonical 114 formats for RFCs is left up to the RFC Editor. For example, they 115 might generate it directly from the input files, through an 116 intermediate format, or something else. 118 2. Canonical RFC Format and Content 120 Canonical RFCs are in XML format. The most salient rules for the 121 format and content of those files are: 123 o The format for the XML will be specified by the RFC Editor. It is 124 likely that the XML format will be an improvement to that which is 125 now referred to as "xml2rfc" ([RFC2629] and its informal 126 successors). 128 o The XML format will allow for art to be contained in the file. 129 This art might be instead of text art in a document (such as for a 130 diagram that is too complex to render well in text), or might be 131 better variants for text art. The RFC Editor will determine which 132 graphic formats are allowed, and it is likely that at least one 133 vector format and one pixel-based format will be permitted. 135 o The XML format will contain all of the metadata needed to produce 136 any of the non-canonical formats for an RFC. 138 o The text encoding for the document is UTF-8. 140 o The RFC Editor can decide where it is and is not appropriate to 141 use non-ASCII characters from the Unicode repertoire in the RFC. 142 For example, the RFC Editor might make rules about using non-ASCII 143 characters in people's names, reference titles, examples in text, 144 and so on. 146 o Text art that internal to the document is limited to 95 columns. 147 This is reasonable for printing on laser printers from the past 25 148 years, and allows much more expressive art than the current 149 maximum of approximately 70 columns. 151 Text art encompasses many types of content. The unifying feature is 152 that it is one or more lines of text that must be rendered with a 153 monospace font in order to be fully understood in the context of the 154 document. Thus, text art includes graphical representations such as 155 packet diagrams, flow diagrams, and flow charts, but it also includes 156 other text that needs to have column alignment such as multi-line 157 ABNF. 159 This proposal does not deal with how mathematical equations might be 160 included in the canonical RFC format. An author can do it as text or 161 as art in an external file. The RFC Editor might allow an equation- 162 specific format from external art files. 164 3. Additional Formats Provided by the RFC Editor 166 The RFC Editor will derive and publish non-canonical documents in 167 multiple formats from the RFC. If the RFC-reading community agrees 168 on a single HTML format, that will certainly be published. If the 169 RFC-reading community cannot agree on just one HTML format, the RFC 170 Editor might publish non-canonical versions of an RFC in multiple 171 HTML formats. The RFC Editor will oversee the development of the 172 tools needed to produce the non-canonical formats. 174 Depending on interest from the RFC-reading community, the RFC Editor 175 will also publish non-canonical versions in other formats. For 176 example, it is likely that the RFC Editor will publish in at least 177 one format of PDF. Because some tools in widespread use rely on the 178 current RFC format, the RFC Editor might also publish a non-canonical 179 version in using the rules in RFC 2333 (line lengths, page headers, 180 and so on). 182 4. Input to the RFC Series 184 The RFC Editor will allow submission of RFCs in the same XML format 185 as the canonical version of an RFC. This allows an author to use 186 differencing tools to track all changes that are made to the document 187 that they submitted to the RFC Editor. 189 The RFC Editor will also possibly allow additional formats for 190 submission based on agreement with the RFC streams. If other 191 submission formats are allowed, the RFC Editor will convert the 192 submission to the canonical format before performing any editing so 193 that all editorial changes are easily tracked within the canonical 194 format. This is similar to what they do currently with submissions 195 that are not in the format the RFC Editor uses for its internal 196 tooling. 198 This proposal in this document does not affect the allowed format for 199 the publication of Internet-Drafts. The IETF Chair has indicated 200 that such a change might happen after the choices are made for RFC 201 format. 203 5. Metadata Needed to Create RFCs 205 The canonical format for RFCs must contain all of the body text for 206 the RFC as well as all of the metadata that is used to mark up the 207 RFC. RFC metadata is useful for many things such as finding RFCs 208 with particular types of content and for making it clearer to a 209 reader what the RFC author intended. 211 The following is a list of the metadata that needs to be part of the 212 canonical RFC format. This list will probably be controversial, but 213 the eventual list needs to contain all of the metadata that is 214 intended for the final RFC format so that the format can be fully 215 specified. Items marked with an asterisk are especially likely to 216 need much more work. 218 Status 219 Category 220 RFC stream 221 Obsoletes 222 Updates 223 Date published 224 Draft derived from 225 Title and short title 226 Per-author 227 Name 228 Initials 229 Company 230 Postal 231 Email 232 URL 233 Role (editor, other) 234 Front content 235 Abstract 236 Copyright 237 Other legal * 238 Headings 239 Level 240 Number 241 Paragraphs 242 Indented for quoting or emphasis 243 Lists 244 Style (bulleted, numbered, unmarked) 245 Nesting 246 Elements 247 Definitions 248 Validatable formats 249 ABNF 250 XML 251 JSON 252 ASN.1 253 Inline art 254 Datagram layout 255 State diagram 256 Flow chart 257 Pseudocode 258 Table * 259 Non-validatable fragments of validatable formats 260 Other 261 Tables * 262 Special sections 263 Security Considerations 264 IANA Considerations 265 Normative References 266 Informative References 267 Cross-references 268 To internal sections 269 To reference 270 To section in reference 271 References * 272 RFCs 273 Specific versions of IDs 274 Non-specific versions of IDs 275 Common non-IETF documents (IEEE, ITU, ISO, ANSI, Unicode) 276 Corner cases 278 6. IANA Considerations 280 None 282 7. Security Considerations 284 None 286 8. Informative References 288 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 289 RFC 2223, October 1997. 291 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 292 June 1999. 294 Author's Address 296 Paul Hoffman 297 VPN Consortium 299 Email: paul.hoffman@vpnc.org