idnits 2.17.1 draft-kwatsen-netmod-artwork-folding-04.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 22, 2018) is 2125 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) 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 Internet Architecture Board (IAB) K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Best Current Practice Q. Wu 5 Expires: December 24, 2018 Huawei Technologies 6 A. Farrel 7 Juniper Networks 8 B. Claise 9 Cisco Systems, Inc. 10 June 22, 2018 12 Handling Long Lines in Artwork in Drafts 13 draft-kwatsen-netmod-artwork-folding-04 15 Abstract 17 This document introduces a simple and yet time-proven strategy for 18 handling long lines in artwork in drafts using a backslash ('\') 19 character where line-folding has occurred. The strategy works on any 20 text based artwork, producing consistent results regardless the 21 artwork content. Using a per-artwork header, the strategy is both 22 self-documenting and enables automated reconstitution of the original 23 artwork. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on December 24, 2018. 42 Copyright Notice 44 Copyright (c) 2018 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 61 3. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3.1. Automated folding of long lines in artwork . . . . . . . 3 63 3.2. Automated reconstitution of original artwork . . . . . . 3 64 4. Limitations . . . . . . . . . . . . . . . . . . . . . . . . . 3 65 4.1. Doesn't work well on graphical artwork . . . . . . . . . 3 66 4.2. Doesn't work as well as format-specific options . . . . . 4 67 5. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 5.1. Header . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 5.2. Folding . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 5.3. Unfolding . . . . . . . . . . . . . . . . . . . . . . . . 5 71 5.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 6 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 74 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 75 8.1. Normative References . . . . . . . . . . . . . . . . . . 6 76 8.2. Informative References . . . . . . . . . . . . . . . . . 7 77 Appendix A. POSIX Shell Script . . . . . . . . . . . . . . . . . 8 78 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 8 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 81 1. Introduction 83 Internet drafts many times contain artwork that exceed the 72 84 character limit specified by RFC 7994 [RFC7994]. The "xml2rfc" 85 utility, in an effort to maintain clean formatting, issues a warning 86 whenever artwork lines exceed 69 characters. According to RFC 87 Editor, there is currently no convention in place for how to handle 88 long lines, other than clearly indicating that some manipulation has 89 occurred. 91 This document introduces a simple and yet time-proven strategy for 92 handling long lines using a backslash ('\') character where line- 93 folding has occurred. The strategy works on any text based artwork, 94 producing consistent results regardless the artwork content. Using a 95 per-artwork header, the strategy is both self-documenting and enables 96 automated reconstitution of the original artwork. 98 2. Requirements Language 100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 102 "OPTIONAL" in this document are to be interpreted as described in BCP 103 14 [RFC2119] [RFC8174] when, and only when, they appear in all 104 capitals, as shown here. 106 3. Goals 108 3.1. Automated folding of long lines in artwork 110 Automated folding of long lines is needed in order to support draft 111 compilations that entail a) validation of source input files (e.g., 112 YANG, XML, JSON, ABNF, ASN.1) and/or b) dynamic generation of output 113 (e.g., tree diagrams) that are stitched into the final draft to be 114 submitted. 116 Generally, in order for tooling to be able to process input files, 117 the files must be in their original/natural state, which may include 118 having some long lines. Thus, these source files need to be modified 119 before inclusion in the draft in order to satisfy the line length 120 limits. This modification SHOULD be automated to reduce effort and 121 errors resulting from manual effort. 123 Similarly, dynamically generated output (e.g., tree diagrams) must 124 also be modified, if necessary, in order for the resulting I-D to 125 satisfy the line length limits. When needed, this effort again 126 SHOULD be automated to reduce effort and errors resulting from manual 127 effort. 129 3.2. Automated reconstitution of original artwork 131 Automated reconstitution of the original artwork is needed to support 132 validation of artwork extracted from drafts. Already YANG modules 133 are extracted from drafts and validated as part of the draft- 134 submission process. Additionally, there has been some discussion 135 regarding needing to do the same for examples contained within drafts 136 ([yang-doctors-list]). Thus, it SHOULD be possible to mechanically 137 reconstitute artwork in order to satisfy the tooling input parsers. 139 4. Limitations 141 4.1. Doesn't work well on graphical artwork 143 While the solution presented in this document will work on any kind 144 of text-based artwork, it is most useful on artwork that represents 145 sourcecode (e.g., YANG, XML, JSON, etc.) or, more generally, on 146 artwork that has not been laid out in two dimensions (e.g., 147 diagrams). 149 The issue regards the readability of the folded artwork in the draft. 150 Artwork that is unpredictable is especially susceptible is looking 151 bad when folded; falling into this category are most UML diagrams. 152 Artwork that is somewhat structured (e.g., YANG tree diagrams 153 [RFC8340]) fair better when folded, as the eyes seem to be able to 154 still see the vertical lines, even when they are interrupted. 156 It is thus NOT RECOMMENDED to use the solution presented in this 157 document on graphical artwork. 159 4.2. Doesn't work as well as format-specific options 161 The solution presented in this document works generically for all 162 artwork, as it only views artwork as plain text. However, various 163 formats sometimes have mechanisms that can be used to prevent long 164 lines. 166 For instance, some source formats allow any quoted string to be 167 broken up into substrings separated by a concatenation character 168 ('+'), any of which can by on a different line. 170 In another example, some languages allow factoring out chucks of code 171 out into "functions" or "groupings". Using such call outs is 172 especially helpful when in some deeply-nested code, as it typically 173 resets the indentation back to the first column. 175 As such, it is RECOMMENDED that authors do as much as possible within 176 the selected format to avoid long lines. 178 5. Solution 180 The following two sections provide the folding and unfolding 181 algorithms that MUST be implemented to align with this BCP. 183 5.1. Header 185 Any artwork that has been folded as specificed by this document MUST 186 contain the header described in this section. 188 The header is two lines long. 190 The first line is the following 53-character string that has been 191 padded with roughly equal numbers of equal ('=') characters to reach 192 the artwork's maximum line length. This line is self-describing in 193 three ways: use of '\' character, identification of BCP/RFC, and 194 identification of what the maximum line length is for the artwork. 195 Following is the mimimal header string (53-characters): 197 === NOTE: '\' line wrapping per BCP XX (RFC XXXX) === 199 The second line is a blank line. This line provides visual 200 seperation for the readability. 202 5.2. Folding 204 Scan the artwork to see if any line exceeds the desired maximum. If 205 no line exceeds the desired maximum, exit (this artwork does not need 206 to be folded). 208 Ensure that the desired maximum is not less than then minumum header, 209 which is 53 characters. If the desired maximum is less than this 210 minimum, exit (this artwork can not be folded). 212 Scan the artwork to ensure no existing lines already end with a '\' 213 character on the desired maximum column, as this would be lead to an 214 ambiguous result. If such a line is found, exit (this artwork cannot 215 be folded). 217 For each line in the artwork, from top-to-bottom, if the line exceeds 218 the desired maximum, then fold the line at the desired maximum column 219 by inserting the string "\\n" (backlash followed by line return) at 220 the column before the maximum column. Note that the column before 221 needs to be used in order to enable the '\' character to be placed on 222 the desired maximum column. The result of this operation is that the 223 character that was on the maximum colomn is now the first character 224 of the next line. 226 Continue in this manner until reaching the end of the artwork. Note 227 that this algorithm naturally addresses the case where the remainder 228 of a folded line is still longer than the desired maximum, and hence 229 needs to be folded again, ad infinitum. 231 5.3. Unfolding 233 Scan the beginning of the artwork for the header described in 234 Section 5.1. If the header is not present, starting on the first 235 line of the artwork, exit (this artwork does not need to be 236 unfolded). 238 Caluculate the folding-column used from the length of the provided 239 header. 241 Remove the 2-line header from the artwork. 243 For each line in the artwork, from top-to-bottom, if the line has a 244 '\' on the folding-column followed by a '\n' character, then remove 245 both the '\' and '\n' characters, which will bring up the next line, 246 and then scan the remainder of the line to see if it again has a '\' 247 after folding-column characters followed by a '\n' character, and so 248 on. 250 Continue in this manner until reaching the end of the artwork. 252 5.4. Example 254 The following self-documenting example illustrates the result of the 255 folding algorithm running over a specific artwork input. 257 The specific input used cannot be presented here, as it would again 258 need to be folded. Alas, only the result can be provided. 260 Some things to note about the following example: 262 o This artwork is exactly 69 characters wide, the widest possible 263 before `xml2rfc` starts to issue warnings. 265 o The line having the 'x' character on the 69th column would've been 266 illegal input had the '\' been used. 268 INSERT_TEXT_FROM_FILE(refs/folding-needed.txt.folded) 270 6. Security Considerations 272 This BCP has no Security Considerations. 274 7. IANA Considerations 276 This BCP has no IANA Considerations. 278 8. References 280 8.1. Normative References 282 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 283 Requirement Levels", BCP 14, RFC 2119, 284 DOI 10.17487/RFC2119, March 1997, 285 . 287 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 288 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 289 May 2017, . 291 8.2. Informative References 293 [RFC7994] Flanagan, H., "Requirements for Plain-Text RFCs", 294 RFC 7994, DOI 10.17487/RFC7994, December 2016, 295 . 297 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 298 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 299 . 301 [yang-doctors-list] 302 "[yang-doctors] automating yang doctor reviews", 303 . 306 Appendix A. POSIX Shell Script 308 This non-normative appendix section includes a shell script that can 309 both fold and unfold artwork based on the solution presented in this 310 document. 312 As a testament for the simplicity of this solution, note that at the 313 core of the script are the following two one-liners: 315 For folding: 316 gsed "/.\{$testcol\}/s/\(.\{$foldcol\}\)/\1\\\\\n/g" 318 For unfolding: 319 gsed ":x; /[^\t]\\{$foldcol\\}\\\\\$/N; s/\\\\\n/\t/; tx; s/\t//g" 321 Disclaimer: this script has the limitation of disallowing the input 322 file from containing any TAB ('\t') characters. 324 =====START SCRIPT===== 326 INSERT_TEXT_FROM_FILE(fold-artwork.sh) 328 =====END SCRIPT===== 330 Acknowledgements 332 The authors thank the RFC Editor for confirming that there are no set 333 convention today for handling long lines in artwork. 335 Authors' Addresses 337 Kent Watsen 338 Juniper Networks 340 EMail: kwatsen@juniper.net 342 Qin Wu 343 Huawei Technologies 345 EMail: bill.wu@huawei.com 347 Adrian Farrel 348 Juniper Networks 350 EMail: afarrel@juniper.net 351 Benoit Claise 352 Cisco Systems, Inc. 353 De Kleetlaan 6a b1 354 1831 Diegem 355 Belgium 357 Phone: +32 2 704 5622 358 EMail: bclaise@cisco.com