idnits 2.17.1 draft-iab-rfcv3-preptool-01.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 (February 10, 2016) is 2995 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-04) exists of draft-iab-xml2rfc-02 -- Obsolete informational reference (is this intentional?): RFC 5741 (Obsoleted by RFC 7841) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). 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: August 13, 2016 Cisco 6 February 10, 2016 8 RFC v3 Prep Tool Description 9 draft-iab-rfcv3-preptool-01 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 August 13, 2016. 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. v3 Prep Tool Usage Scenarios . . . . . . . . . . . . . . . . 2 52 3. Internet-Draft Submission . . . . . . . . . . . . . . . . . . 3 53 4. Canonical RFC Preparation . . . . . . . . . . . . . . . . . . 4 54 5. What the v3 Prep Tool Does . . . . . . . . . . . . . . . . . 4 55 6. Additional Uses for the Prep Tool . . . . . . . . . . . . . . 10 56 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 57 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 58 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 59 10. Informative References . . . . . . . . . . . . . . . . . . . 11 60 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 62 1. Introduction 64 For the future of the RFC format, the RFC Editor has decided that XML 65 (using the XML2RFCv3 vocabulary [I-D.iab-xml2rfc]) is the canonical 66 format, in the sense that it is the data that is blessed by the 67 process as the actual RFC. See [RFC6949] for more detail on this. 69 Most people will read other formats, such as HTML, PDF, ASCII text, 70 or other formats of the future, however. In order to ensure each of 71 these formats is as similar as possible to one another as well as the 72 canonical XML, there is a desire that the translation from XML into 73 the other formats will be straightforward syntactic translation. To 74 make that happen, a good amount of data will need to be in the XML 75 format that is not there today. That data will be added by a program 76 called the "prep tool", which will often run as a part of the xml2rfc 77 process. 79 This draft specifies the steps that the prep tool will have to take. 80 As changes to [I-D.iab-xml2rfc] are made, this document will be 81 updated. 83 The details (particularly any vocabularies) described in this 84 document are expected to change based on experience gained in 85 implementing the RFC production center's toolset. Revised documents 86 will be published capturing those changes as the toolset is 87 completed. Other implementers must not expect those changes to 88 remain backwards-compatible with the details described in this 89 document. 91 2. v3 Prep Tool Usage Scenarios 93 The prep tool will have several settings: 95 o Internet-Draft preparation 96 o Canonical RFC preparation 98 There are only a few differences between the two settings. For 99 example, the boilerplate output will be different, as will the date 100 output on the front page. 102 Note that this only describes what the IETF-sponsored prep tool does. 103 Others might create their own work-alike prep tools for their own 104 formatting needs. However, an output format developer does not need 105 to change the prep tool in order to create their own formatter: they 106 only need to be able to consume prepared text. The IETF-sponsored 107 prep tool runs in two different modes: "I-D" mode when the tool is 108 run during Internet-Draft submission and processing, and "RFC 109 production mode" when the tool is run by the RFC Production Center 110 (RPC) while producing an RFC. 112 This tool is described as if it is a separate tool so that we can 113 reason about its architectural properties. In actual implementation, 114 it might be a part of a larger suite of functionality. 116 3. Internet-Draft Submission 118 When the IETF draft submission tool accepts v3 XML as an input 119 format, the submission tool runs the submitted file through the prep 120 tool. This is called "I-D mode" in this document. If the tool finds 121 no errors, it keeps two XML files: the submitted file and the prepped 122 file. 124 The prepped file provides a record of what a submitter was attesting 125 to at the time of submission. It represents a self-contained record 126 of what any external references resolved to at the time of 127 submission. 129 The prepped file is used by the IETF formatters to create outputs 130 such as HTML, PDF, and text (or the tools act in a way 131 indistinguishable from this). The message sent out by the draft 132 submission tool includes a link to the original XML as well as the 133 other outputs, including the prepped XML. 135 The prepped XML can be used by tools not yet developed to output new 136 formats that have as similar output as possible to the current IETF 137 formatters. For example, if the IETF creates a .mobi output renderer 138 later, it can run that renderer on all of the prepped XML that has 139 been saved, ensuring that the content of included external references 140 and all of the part numbers and boilerplate will be the same as what 141 was produced by the previous IETF formatters at the time the document 142 was first uploaded. 144 4. Canonical RFC Preparation 146 During AUTH48, the RPC will run the prep tool in canonical RFC 147 preparation mode and make the results available to the authors so 148 they can see what the final output might look like. When the 149 document is done with AUTH48 review, the RPC runs the prep tool in 150 canonical RFC preparation mode one last time, locks down the 151 canonicalized XML, runs the formatters for the publication formats, 152 and publishes all of those. It is probably a good idea for the RPC 153 to keep a copy of the input XML file from the various steps of the 154 RFC production process. 156 This document assumes that the prep tool will be used in the 157 following manner by the RFC Production Center; they may use something 158 different, or with different configuration. 160 Similarly to I-D's, the prepped XML can be used later to re-render 161 the output formats, or to generate new formats. 163 5. What the v3 Prep Tool Does 165 The steps listed here are in order of processing. In all cases where 166 the prep tool would "add" an attribute or element, if that attribute 167 or element already exists, the prep tool will check that the 168 attribute or element is correct. If the value is incorrect, the prep 169 tool will warn with the old and new values, then replace the 170 incorrect value with the new value. 172 1. Fully process any DTDs in the input document, then remove the 173 DTD. At a minimum, this entails processing the entityrefs and 174 includes for external files. 176 2. Process all elements. Note: d XML may 177 include more s (with relative URLs rooted at the 178 xml:base). The tool may be configurable with a limit on the 179 depth of recursion. 181 3. Run idnits. idnits will indicate if it encountered any errors, 182 and will also provide text with all of the warnings and errors 183 in a human-readable form. The prep tool displays all the 184 warnings and errors, and stops if there was an error. 186 4. Remove processing instructions. 188 5. If in RFC production mode, remove comments. 190 6. Add the "Status of this Memo" text with current values. 191 However, if different boilerplate text already exists in the 192 input, produce a warning that says that other tools, 193 specifically the draft submission tool, will treat that 194 condition as an error. The application will use the 195 "submissionType", and "consensus" attributes of the 196 element, and the "status" and "stream" attributes of the 197 element, to determine which [RFC5741] boilerplate 198 to include, as described in Appendix A of [I-D.iab-xml2rfc]. 200 7. Add the "Copyright Notice" text. The application will use the 201 "ipr" and "submissionType" attributes of the element and 202 the element to determine which portions and which version 203 of the TLP to use, as described in A.1 of [I-D.iab-xml2rfc]. 205 8. Fill in the "prepTime" attribute of with the current 206 datetime. 208 9. Fill in the "name" attribute of the in the 209 with a string indicating the type of prepping that was done (RFC 210 production or I-D mode). 212 10. If in I-D mode, if there is a element with a 213 "removeInRFC" attribute that has the value "true", add a 214 paragraph to the top of the element that says "This note 215 is to be removed before publishing as an RFC.", if such a 216 paragraph does not yet exist. 218 11. If in I-D mode, fill in "expiresDate" attribute of based 219 on the element of the document's element, if 220 there is one. Use the same expiry date (if needed) in the 221 boilerplate. 223 12. Fill in any default values for attributes on elements, except 224 "keepWithNext" and "keepWithPrevious" of , and "toc" of 225
. 227 13. For any element that does not already have a 228 "target" attribute, fill that attribute in if the element has 229 one or more child element(s). The particular URLs 230 for RFCs and Internet-Drafts for this step will be specified 231 later by the RFC Editor and the IESG. These URLs might also be 232 different before and after the v3 format is adopted. 234 14. For each or that has an associated 235 , replace the value of the "anchor" attribute 236 with the value of the "to" attribute of the associated 237 . 239 15. Add a "slugifiedName" attribute to each element that does 240 not contain one; replace the attribute if it contains a value 241 that begins with "n-". 243 16. Add "pn" attributes for all parts. Parts are: 245 *
: pn='s-1.4.2' 247 * : pn='s-abstract' 249 * : pn='s-note-2' 251 * : pn='s-boilerplate' 253 * : pn='t-3' 255 *
: pn='f-4' 257 * ,