idnits 2.17.1 draft-iab-rfcv3-preptool-02.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 (June 30, 2016) is 2856 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hoffman 3 Internet-Draft ICANN 4 Intended status: Informational J. Hildebrand 5 Expires: January 1, 2017 Cisco 6 June 30, 2016 8 RFC v3 Prep Tool Description 9 draft-iab-rfcv3-preptool-02 11 Abstract 13 This document describes some aspects of the "prep tool" that is 14 expected to be created when the new RFC v3 specification is deployed. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on January 1, 2017. 33 Copyright Notice 35 Copyright (c) 2016 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. v3 Prep Tool Usage Scenarios . . . . . . . . . . . . . . . . 4 52 3. Internet-Draft Submission . . . . . . . . . . . . . . . . . . 4 53 4. Canonical RFC Preparation . . . . . . . . . . . . . . . . . . 5 54 5. What the v3 Prep Tool Does . . . . . . . . . . . . . . . . . 5 55 5.1. XML Sanitization . . . . . . . . . . . . . . . . . . . . 5 56 5.1.1. XInclude Processing . . . . . . . . . . . . . . . . . 6 57 5.1.2. DTD Removal . . . . . . . . . . . . . . . . . . . . . 6 58 5.1.3. Processing Instruction Removal . . . . . . . . . . . 6 59 5.1.4. Validity Check . . . . . . . . . . . . . . . . . . . 6 60 5.1.5. Check "anchor" . . . . . . . . . . . . . . . . . . . 6 61 5.2. Defaults . . . . . . . . . . . . . . . . . . . . . . . . 6 62 5.2.1. "version" Insertion . . . . . . . . . . . . . . . . . 6 63 5.2.2. "seriesInfo" Insertion . . . . . . . . . . . . . . . 6 64 5.2.3. Insertion . . . . . . . . . . . . . . . . . . 7 65 5.2.4. "prepTime" Insertion . . . . . . . . . . . . . . . . 7 66 5.2.5.
    Group "start" Insertion . . . . . . . . . . . . 7 67 5.2.6. Attribute Default Value Insertion . . . . . . . . . . 7 68 5.2.7. Section "toc" attribute . . . . . . . . . . . . . . . 7 69 5.2.8. "removeInRFC" Warning Paragraph . . . . . . . . . . . 8 70 5.3. Normalization . . . . . . . . . . . . . . . . . . . . . . 8 71 5.3.1. "month" Attribute . . . . . . . . . . . . . . . . . . 8 72 5.3.2. ASCII Attribute Processing . . . . . . . . . . . . . 8 73 5.3.3. "title" Conversion . . . . . . . . . . . . . . . . . 8 74 5.4. Generation . . . . . . . . . . . . . . . . . . . . . . . 9 75 5.4.1. "expiresDate" Insertion . . . . . . . . . . . . . . . 9 76 5.4.2. Insertion . . . . . . . . . . . . . . . 9 77 5.4.2.1. Compare "submissionType" and 78 "stream" . . . . . . . . . . . . . . . . . . . . 9 79 5.4.2.2. 'Status of this Memo' Insertion . . . . . . . . . 9 80 5.4.2.3. Copyright Insertion . . . . . . . . . . . . . . . 9 81 5.4.3. "target" Insertion . . . . . . . . . . . 9 82 5.4.4. Slugification . . . . . . . . . . . . . . . . 10 83 5.4.5. Sorting . . . . . . . . . . . . . . . . . 10 84 5.4.6. "pn" Numbering . . . . . . . . . . . . . . . . . . . 10 85 5.4.7. Numbering . . . . . . . . . . . . . . . . . . 10 86 5.4.8. processing . . . . . . . . . . . . . . . . . . 11 87 5.4.8.1. "derivedContent" Insertion (With Content) . . . . 11 88 5.4.8.2. "derivedContent" Insertion (Without Content) . . 11 89 5.4.9. Processing . . . . . . . . . . . . . . . . . 11 90 5.5. Inclusion . . . . . . . . . . . . . . . . . . . . . . . . 12 91 5.5.1. Processing . . . . . . . . . . . . . . . . 12 92 5.5.2. Processing . . . . . . . . . . . . . . . 13 93 5.6. RFC Production Mode Cleanup . . . . . . . . . . . . . . . 14 94 5.6.1. Removal . . . . . . . . . . . . . . . . . . . 14 95 5.6.2. Removal . . . . . . . . . . . . . . . . . . . 14 96 5.6.3. Processing . . . . . . . . . . . . . . . . . . 14 97 5.6.4. XML Comment Removal . . . . . . . . . . . . . . . . . 15 98 5.6.5. "xml:base" and "originalSrc" Removal . . . . . . . . 15 99 5.6.6. Compliance Check . . . . . . . . . . . . . . . . . . 15 100 5.7. Finalization . . . . . . . . . . . . . . . . . . . . . . 15 101 5.7.1. "scripts" Insertion . . . . . . . . . . . . . . . . . 15 102 5.7.2. Pretty-Format . . . . . . . . . . . . . . . . . . . . 15 103 6. Additional Uses for the Prep Tool . . . . . . . . . . . . . . 15 104 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 105 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 106 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16 107 10. Informative References . . . . . . . . . . . . . . . . . . . 16 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 110 1. Introduction 112 For the future of the RFC format, the RFC Editor has decided that XML 113 (using the XML2RFCv3 vocabulary [I-D.iab-xml2rfc]) is the canonical 114 format, in the sense that it is the data that is the authorized, 115 recognized, accepted, and archived version of the document. See 116 [RFC6949] for more detail on this. 118 Most people will read other formats, such as HTML, PDF, ASCII text, 119 or other formats of the future, however. In order to ensure each of 120 these formats is as similar as possible to one another as well as the 121 canonical XML, there is a desire that the translation from XML into 122 the other formats will be straightforward syntactic translation. To 123 make that happen, a good amount of data will need to be in the XML 124 format that is not there today. That data will be added by a program 125 called the "prep tool", which will often run as a part of the xml2rfc 126 process. 128 This draft specifies the steps that the prep tool will have to take. 129 As changes to [I-D.iab-xml2rfc] are made, this document will be 130 updated. 132 The details (particularly any vocabularies) described in this 133 document are expected to change based on experience gained in 134 implementing the RFC Production Center's (RPC) toolset. Revised 135 documents will be published capturing those changes as the toolset is 136 completed. Other implementers must not expect those changes to 137 remain backwards-compatible with the details described in this 138 document. 140 2. v3 Prep Tool Usage Scenarios 142 The prep tool will have several settings: 144 o Internet-Draft preparation 146 o Canonical RFC preparation 148 There are only a few differences between the two settings. For 149 example, the boilerplate output will be different, as will the date 150 output on the front page. 152 Note that this only describes what the IETF-sponsored prep tool does. 153 Others might create their own work-alike prep tools for their own 154 formatting needs. However, an output format developer does not need 155 to change the prep tool in order to create their own formatter: they 156 only need to be able to consume prepared text. The IETF-sponsored 157 prep tool runs in two different modes: "I-D" mode when the tool is 158 run during Internet-Draft submission and processing, and "RFC 159 production mode" when the tool is run by the RFC Production Center 160 while producing an RFC. 162 This tool is described as if it is a separate tool so that we can 163 reason about its architectural properties. In actual implementation, 164 it might be a part of a larger suite of functionality. 166 3. Internet-Draft Submission 168 When the IETF draft submission tool accepts v3 XML as an input 169 format, the submission tool runs the submitted file through the prep 170 tool. This is called "I-D mode" in this document. If the tool finds 171 no errors, it keeps two XML files: the submitted file and the prepped 172 file. 174 The prepped file provides a record of what a submitter was attesting 175 to at the time of submission. It represents a self-contained record 176 of what any external references resolved to at the time of 177 submission. 179 The prepped file is used by the IETF formatters to create outputs 180 such as HTML, PDF, and text (or the tools act in a way 181 indistinguishable from this). The message sent out by the draft 182 submission tool includes a link to the original XML as well as the 183 other outputs, including the prepped XML. 185 The prepped XML can be used by tools not yet developed to output new 186 formats that have as similar output as possible to the current IETF 187 formatters. For example, if the IETF creates a .mobi output renderer 188 later, it can run that renderer on all of the prepped XML that has 189 been saved, ensuring that the content of included external references 190 and all of the part numbers and boilerplate will be the same as what 191 was produced by the previous IETF formatters at the time the document 192 was first uploaded. 194 4. Canonical RFC Preparation 196 During AUTH48, the RPC will run the prep tool in canonical RFC 197 production mode and make the results available to the authors so they 198 can see what the final output might look like. When the document has 199 passed AUTH48 review, the RPC runs the prep tool in canonical RFC 200 production mode one last time, locks down the canonicalized XML, runs 201 the formatters for the publication formats, and publishes all of 202 those. 204 This document assumes that the prep tool will be used in the 205 following manner by the RPC; they may use something different, or 206 with different configuration. 208 Similarly to I-D's, the prepped XML can be used later to re-render 209 the output formats, or to generate new formats. 211 5. What the v3 Prep Tool Does 213 The steps listed here are in order of processing. In all cases where 214 the prep tool would "add" an attribute or element, if that attribute 215 or element already exists, the prep tool will check that the 216 attribute or element has valid values. If the value is incorrect, 217 the prep tool will warn with the old and new values, then replace the 218 incorrect value with the new value. 220 Currently, the IETF uses a tool called "idnits" to check text input 221 to the Internet-Drafts publishing process. idnits indicates if it 222 encountered any errors, and also provide text with all of the 223 warnings and errors in a human-readable form. The prep tool should 224 probably check for as many of these errors and warnings as possible 225 when it is processing the XML input. For the moment, tooling might 226 run idnts on the text output from the prepared XML. The list below 227 contains some of those errors and warnings, but the deployed version 228 of the prep tool may contain additional steps to include more or the 229 checks from idnits. 231 5.1. XML Sanitization 233 These steps will ensure that the input document is properly 234 formatted, and that all XML processing has been performed. 236 5.1.1. XInclude Processing 238 Process all elements. Note: d XML may include 239 more s (with relative references resolved against the base 240 URI potentially modified by a previously inserted xml:base 241 attribute). The tool may be configurable with a limit on the depth 242 of recursion. 244 5.1.2. DTD Removal 246 Fully process any Document Type Definitions (DTDs) in the input 247 document, then remove the DTD. At a minimum, this entails processing 248 the entity references and includes for external files. 250 5.1.3. Processing Instruction Removal 252 Remove processing instructions. 254 5.1.4. Validity Check 256 Check the input against the RNG in [I-D.iab-xml2rfc]. If the input 257 is not valid, give an error. 259 5.1.5. Check "anchor" 261 Check all elements for "anchor" attributes. If any "anchor" 262 attribute begins with "s-", "f-", "t-", or "i-", give an error. 264 5.2. Defaults 266 These steps will ensure that all default values have been filled in 267 to the XML, in case the defaults change at a later date. Steps in 268 this section will not overwrite existing values in the input file. 270 5.2.1. "version" Insertion 272 If the element has a "version" attribute with a value other 273 than "3", give an error. If the element has no "version" 274 attribute, add one with the value "3". 276 5.2.2. "seriesInfo" Insertion 278 If the element of the element does not already have a 279 element, add a element with the name 280 attribute based on the mode in which the preptool is running 281 ("Internet-Draft" for Draft mode and "RFC" for RFC production mode) 282 and a value that is the input filename minus any extension for 283 Internet-Drafts, and is a number specified by the RFC Editor for 284 RFCs. 286 5.2.3. Insertion 288 If the element in the element does not contain a 289 element, add it and fill in the "day", "month", and "year" attibutes 290 from the current date. If the element in the element 291 has a element with "day", "month", and "year" attibutes, but 292 the date indicated is more than three days in the past or is in the 293 future, give a warning. If the element in the element 294 has a element with some but not all of the "day", "month", and 295 "year" attibutes, give an error. 297 5.2.4. "prepTime" Insertion 299 If the input document includes a "prepTime" attribute of , exit 300 with an error. 302 Fill in the "prepTime" attribute of with the current datetime. 304 5.2.5.
      Group "start" Insertion 306 Add a "start" attribute to every
        element containing a group that 307 does not already have a start. 309 5.2.6. Attribute Default Value Insertion 311 Fill in any default values for attributes on elements, except 312 "keepWithNext" and "keepWithPrevious" of , and "toc" of
        . 313 Some default values can be found in the Relax NG schema, while others 314 can be found in the prose describing the elements in 315 [I-D.iab-xml2rfc]). 317 5.2.7. Section "toc" attribute 319 For each
        , modify the "toc" attribute to be either "include" 320 or "exclude": 322 o for sections that have an ancestor of , use "exclude" 324 o else for sections that have a descendant that has toc="include", 325 use "include". If the section has toc="exclude" in the input, 326 this is an error. 328 o else for sections that are children of a section with 329 toc="exclude", use "exclude". 331 o else for sections that are deeper than rfc/@tocDepth, use 332 "exclude" 334 o else use "include" 336 5.2.8. "removeInRFC" Warning Paragraph 338 If in I-D mode, if there is a or
        element with a 339 "removeInRFC" attribute that has the value "true", add a paragraph to 340 the top of the element with the text "This note is to be removed 341 before publishing as an RFC." or "This section...", unless a 342 paragraph consisting of that exact text already exists. 344 5.3. Normalization 346 These steps will ensure that ideas that can be expressed in multiple 347 different ways in the input document are only found in one way in the 348 prepared document. 350 5.3.1. "month" Attribute 352 Normalize the values of "month" attributes in all elements in 353 elements in elements to numeric values. 355 5.3.2. ASCII Attribute Processing 357 In every , , , , , 358 , and element, if there is an "ascii" attribute and 359 the value of that attribute is the same as the content of the 360 element, remove the "ascii" element and issue a warning about the 361 removal. 363 In every element, if there is an "asciiFullname", 364 "asciiInitials", or "asciiSurname" attribute, check the content of 365 that element against its matching "fullname", "initials", or 366 "surname" element (respectively). If the two are the same, remove 367 the "ascii*" elelement and issue a warning about the removal. 369 5.3.3. "title" Conversion 371 For every
        , ,
        , , and 372 element that has a (deprecated) "title" attribute, remove the "title" 373 attribute and insert a element with the title from the 374 attribute. 376 5.4. Generation 378 These steps will generate new content, overriding existing similar 379 content in the input document. Some of these steps are important 380 enough that they specify a warning to be generated when the content 381 being overwritten does not match the new content. 383 5.4.1. "expiresDate" Insertion 385 If in I-D mode, fill in "expiresDate" attribute of based on the 386 element of the document's element. 388 5.4.2. Insertion 390 Create a element if it does not exist. If there are 391 any children of the element, produce a warning that 392 says "Existing boilerplate being removed. Other tools, specifically 393 the draft submission tool, will treat this condition as an error" and 394 remove the existing children. 396 5.4.2.1. Compare "submissionType" and "stream" 398 Verify that "submissionType" and "stream" are the 399 same if they are both present. If either is missing, add it. Note 400 that both have a default value of "IETF". 402 5.4.2.2. 'Status of this Memo' Insertion 404 Add the "Status of this Memo" section to the element 405 with current values. The application will use the "submissionType", 406 and "consensus" attributes of the element, the 407 element, and the "status" and "stream" attributes of the 408 element, to determine which [I-D.iab-rfc5741bis] boilerplate to 409 include, as described in Appendix A of [I-D.iab-xml2rfc]. 411 5.4.2.3. Copyright Insertion 413 Add the "Copyright Notice" section to the element. The 414 application will use the "ipr" and "submissionType" attributes of the 415 element and the element to determine which portions and 416 which version of the TLP to use, as described in A.1 of 417 [I-D.iab-xml2rfc]. 419 5.4.3. "target" Insertion 421 For any element that does not already have a "target" 422 attribute, fill the target attribute in if the element has one or 423 more child element(s) and the "name" attribute of the 424 element is "RFC", "Internet-Draft", or "DOI" or other 425 value for which it is clear what the "target" should be. The 426 particular URLs for RFCs, Internet-Drafts, and DOIs for this step 427 will be specified later by the RFC Editor and the IESG. These URLs 428 might also be different before and after the v3 format is adopted. 430 5.4.4. Slugification 432 Add a "slugifiedName" attribute to each element that does not 433 contain one; replace the attribute if it contains a value that begins 434 with "n-". 436 5.4.5. Sorting 438 If the "sortRefs" attribute of the element is true, sort the 439 s and s lexically by the value of the 440 "anchor" attribute, as modified by the "to" attribute of any 441 element. The RFC Editor needs to determine what 442 the rules for lexical sorting are. The authors of this document 443 acknowledge that getting consensus on this will be a difficult task. 445 5.4.6. "pn" Numbering 447 Add "pn" attributes for all parts. Parts are: 449 o
        in : pn='s-1.4.2' 451 o : pn='s-12' or pn='s-12.1' 453 o : pn='s-abstract' 455 o : pn='s-note-2' 457 o
        in : pn='s-boilerplate-1' 459 o : pn='t-3' 461 o
        : pn='f-4' 463 o ,
        , the "derivedContent" is the name of the thing 496 pointed to, such as "Section 2.3", "Figure 12", or "Table 4". * For 497 format='title', if the target is a element, the 498 "derivedContent" attribute is the name of the reference, extracted 499 from the child of the <front> child of the reference. * For 500 format='title', if the target element has a <name> child element, the 501 "derivedContent" attribute is the text content of that <name> element 502 concatenated with the text content of each descendant node of <name> 503 (that is, stripping out all of the XML markup, leaving only the 504 text). * For format='title', if the target element does not contain 505 a <name> child element, the "derivedContent" attribute is the value 506 of the "target" attribute with no other adornment. Issue a warning 507 if the "derivedContent" attribute already exists and has a different 508 value from what was being filled in. 510 5.4.9. <relref> Processing 512 If any <relref> element's "target" attribute refers to anything but a 513 <reference> element, give an error. 515 For each <relref> element, fill in the "derivedLink" attribute. 517 5.5. Inclusion 519 These steps will include external files into the output document. 521 5.5.1. <artwork> Processing 523 1. If an <artwork> element has a "src" attribute where no scheme is 524 specified, copy the "src" attribute value to the "originalSrc" 525 attribute, and replace the "src" value with a URI that uses the 526 "file:" scheme in a path relative to the file being processed. 527 See Section 8 for warnings about this step. This will likely be 528 one of the most common authoring approaches. 530 2. If an <artwork> element has a "src" attribute with a "file:" 531 scheme, and if processing the URL would cause the processor to 532 retrieve a file that is not in the same directory, or a 533 subdirectory, as the file being processed, give an error. If the 534 "src" has any shellmeta strings (such as "`", "$USER", and so on) 535 that would be processed , give an error. Replace the "src" 536 attribute with a URI that uses the "file:" scheme in a path 537 relative to the file being processed. This rule attempts to 538 prevent <artwork src='file:///etc/passwd'> and similar security 539 issues. See Section 8 for warnings about this step. 541 3. If an <artwork> element has a "src" attribute, and the element 542 has content, give an error. 544 4. If an <artwork> element has type='svg' and there is a "src" 545 attribute, the data needs to be moved into the content of the 546 <artwork> element. 548 * If the "src" URI scheme is "data:", fill the content of the 549 <artwork> element with that data and remove the "src" 550 attribute. 552 * If the "src" URI scheme is "file:", "http:", or "https:", fill 553 the content of the <artwork> element with the resolved XML 554 from the URI in the "src" attribute. If there is no 555 "originalSrc" attribute, add an "originalSrc" attribute with 556 the value of the URI and remove the "src" attribute. 558 * If the <artwork> element has an "alt" attribute, and the SVG 559 does not have a <desc> element, add the <desc> element with 560 the contents of the "alt" attribute. 562 5. If an <artwork> element has type='binary-art', the data needs to 563 be in a "src" attribute with a URI scheme of "data:". If the 564 "src" URI scheme is "file:", "http:", or "https:", resolve the 565 URL. Replace the "src" attribute with a "data:" URI, and add an 566 "originalSrc" attribute with the value of the URI. For the 567 "http:" and "https:" URI schemes, the mediatype of the "data:" 568 URI will be the Content-Type of the HTTP response. For the 569 "file:" URI scheme, the mediatype of the "data:" URI needs to be 570 guessed with heuristics (this is possibly a bad idea). This also 571 fails for content that includes binary images but uses a type 572 other than "binary-art". Note: since this feature can't be used 573 for RFCs at the moment, this entire feature might be de- 574 prioritized. 576 6. If an <artwork> element does not have type='svg' or type='binary- 577 art' and there is a "src" attribute, the data needs to be moved 578 into the content of the <artwork> element. Note that this step 579 assumes that all of the preferred types other than "binary-art" 580 are text, which is possibly wrong. 582 * If the "src" URI scheme is "data:", fill the content of the 583 <artwork> element with the correctly-escaped form of that data 584 and remove the "src" attribute. 586 * If the "src" URI scheme is "file:", "http:", or "https:", fill 587 the content of the <artwork> element with the correctly- 588 escaped form of the resolved text from the URI in the "src" 589 attribute. If there is no "originalSrc" attribute, add an 590 "originalSrc" attribute with the value of the URI and remove 591 the "src" attribute. 593 5.5.2. <sourcecode> Processing 595 1. If an <sourcecode> element has a "src" attribute where no scheme 596 is specified, copy the "src" attribute value to the "originalSrc" 597 attribute, and replace the "src" value with a URI that uses the 598 "file:" scheme in a path relative to the file being processed. 599 See Section 8 for warnings about this step. This will likely be 600 one of the most common authoring approaches. 602 2. If an <sourcecode> element has a "src" attribute with a "file:" 603 scheme, and if processing the URL would cause the processor to 604 retrieve a file that is not in the same directory, or a 605 subdirectory, as the file being processed, give an error. If the 606 "src" has any shellmeta strings (such as "`", "$USER", and so on) 607 that would be processed , give an error. Replace the "src" 608 attribute with a URI that uses the "file:" scheme in a path 609 relative to the file being processed. This rule attempts to 610 prevent <sourcecode src='file:///etc/passwd'> and similar 611 security issues. See Section 8 for warnings about this step. 613 3. If an <sourcecode> element has a "src" attribute, and the element 614 has content, give an error. 616 4. If an <sourcecode> elementhas a "src" attribute, the data needs 617 to be moved into the content of the <sourcecode> element. 619 * If the "src" URI scheme is "data:", fill the content of the 620 <sourcecode> element with that data and remove the "src" 621 attribute. 623 * If the "src" URI scheme is "file:", "http:", or "https:", fill 624 the content of the <sourcecode> element with the resolved XML 625 from the URI in the "src" attribute. If there is no 626 "originalSrc" attribute, add an "originalSrc" attribute with 627 the value of the URI and remove the "src" attribute. 629 5.6. RFC Production Mode Cleanup 631 These steps provide extra cleanup of the output document in RFC 632 production mode. 634 5.6.1. <note> Removal 636 If in RFC production mode, if there is a <note> or <section> element 637 with a "removeInRFC" attribute that has the value "true", remove the 638 element. 640 5.6.2. <cref> Removal 642 If in RFC production mode, remove all <cref> elements. 644 5.6.3. <link> Processing 646 1. If in RFC production mode, remove all <link> elements whose "rel" 647 attribute has the value "alternate". 649 2. If in RFC production mode, check if there is a <link> element 650 with the current ISSN for the RFC series (2070-1721); if not, add 651 <link rel="item" href="urn:issn:2070-1721">. 653 3. If in RFC production mode, check if there is a <link> element 654 with a DOI for this RFC; if not, add one of the form <link 655 rel="describedBy" href="https://dx.doi.org/10.17487/rfcdd"> where 656 "dd" is the number of the RFC, such as 657 "https://dx.doi.org/10.17487/rfc2109". The URI is described in 658 [RFC7669]. If there was already a <link> element with a DOI for 659 this RFC, check that the "href" value has the right format. 661 4. If in RFC production mode, check if there is a <link> element 662 with the file name of the Internet-Draft that became this RFC the 663 form <link rel="convertedFrom" 664 href="https://datatracker.ietf.org/doc/draft-tttttttttt/">. If 665 one does not exist, give an error. 667 5.6.4. XML Comment Removal 669 If in RFC production mode, remove XML comments. 671 5.6.5. "xml:base" and "originalSrc" Removal 673 If in RFC production mode, remove all "xml:base" or "originalSrc" 674 attributes from all elements. 676 5.6.6. Compliance Check 678 If in RFC production mode, ensure that the result is in full 679 compliance to v3 schema, without any deprecated elements or 680 attributes, and give an error if any issues are found. 682 5.7. Finalization 684 These steps provide the finishing touches on the output document. 686 5.7.1. "scripts" Insertion 688 Determine all the characters used in the document, and fill in the 689 "scripts" attribute for <rfc>. 691 5.7.2. Pretty-Format 693 Pretty-format the XML output. (Note: there are many tools that do an 694 adequate job.) 696 6. Additional Uses for the Prep Tool 698 There will be a need for Internet-Draft authors who include files 699 from their local disk (such as for <artwork src="mydrawing.svg"/>) to 700 have the contents of those files inlined to their drafts before 701 submitting them to the Internet-Draft processor. (There is a 702 possibility that the Internet-Draft processor will allow XML files 703 and accompanying files to be submitted at the same time, but this 704 seems troublesome from a security, portability, and complexity 705 standpoint.) For these users, having a local copy of the prep tool 706 that has an option to just inline all local files would be terribly 707 useful. That option would be a proper subset of the steps given in 708 Section 5. 710 A feature that might be useful in a local prep tool would be the 711 inverse of the "just inline" option would be "extract all". This 712 would allow a user who has a v3 RFC or Internet-Draft to dump all of 713 the <artwork> and <sourcecode> elements into local files instead of 714 having to find each one in the XML. This option might even do as 715 much validation as possible on the extracted <sourcecode> elements. 716 This feature might also remove some of the features added by the prep 717 tool (such as part numbers and slugifiedName's starting with "n-") in 718 order to make the resulting file easier to edit. 720 7. IANA Considerations 722 None. 724 8. Security Considerations 726 Steps in this document attempt to prevent the <artwork> and 727 <sourcecode> entities from exposing the contents of files outside the 728 directory in which the document being processed resides. For 729 example, values starting with "/", "./", or "../" should generate 730 errors. 732 The security considerations in [RFC3470] apply here. In specific, 733 processing XML external references can expose a prep tool 734 implementation to various threats by causing the implementation to 735 access external resources automatically. It is important to disallow 736 arbitrary access to such external references within XML data from 737 untrusted sources. 739 9. Acknowledgements 741 Many people contributed valuable ideas to this document. Special 742 thanks go to Robert Sparks for his in-depth review and contributions 743 early in the development of this document, and to Julian Reschke for 744 his help getting the document structured more clearly. 746 10. Informative References 748 [I-D.iab-rfc5741bis] 749 Halpern, J., Daigle, L., and O. Kolkman, "On RFC Streams, 750 Headers, and Boilerplates", draft-iab-rfc5741bis-02 (work 751 in progress), February 2016. 753 [I-D.iab-xml2rfc] 754 Hoffman, P., "The "xml2rfc" version 3 Vocabulary", draft- 755 iab-xml2rfc-04 (work in progress), June 2016. 757 [RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for 758 the Use of Extensible Markup Language (XML) within IETF 759 Protocols", BCP 70, RFC 3470, DOI 10.17487/RFC3470, 760 January 2003, <http://www.rfc-editor.org/info/rfc3470>. 762 [RFC6949] Flanagan, H. and N. Brownlee, "RFC Series Format 763 Requirements and Future Development", RFC 6949, 764 DOI 10.17487/RFC6949, May 2013, 765 <http://www.rfc-editor.org/info/rfc6949>. 767 [RFC7669] Levine, J., "Assigning Digital Object Identifiers to 768 RFCs", RFC 7669, DOI 10.17487/RFC7669, October 2015, 769 <http://www.rfc-editor.org/info/rfc7669>. 771 Authors' Addresses 773 Paul Hoffman 774 ICANN 776 Email: paul.hoffman@icann.org 778 Joe Hildebrand 779 Cisco 781 Email: jhildebr@cisco.com