idnits 2.17.1 draft-kwatsen-netmod-artwork-folding-05.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 25, 2018) is 2131 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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) == Missing Reference: '-r' is mentioned on line 373, but not defined Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Best Current Practice Q. Wu 5 Expires: December 27, 2018 Huawei Technologies 6 A. Farrel 7 Juniper Networks 8 B. Claise 9 Cisco Systems, Inc. 10 June 25, 2018 12 Handling Long Lines in Artwork in Drafts 13 draft-kwatsen-netmod-artwork-folding-05 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 27, 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 . . . . . . . . . . . . . . . . . . . 7 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 74 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 8.1. Normative References . . . . . . . . . . . . . . . . . . 8 76 8.2. Informative References . . . . . . . . . . . . . . . . . 8 77 Appendix A. POSIX Shell Script . . . . . . . . . . . . . . . . . 9 78 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 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 minimal 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 separation 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 minimum 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 column 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 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 270 # boundary condition tests using numbers for counting purposes 271 123456789012345678901234567890123456789012345678901234567890123456 272 1234567890123456789012345678901234567890123456789012345678901234567 273 12345678901234567890123456789012345678901234567890123456789012345678 274 123456789012345678901234567890123456789012345678901234567890123456789 275 12345678901234567890123456789012345678901234567890123456789012345678\ 276 90 277 12345678901234567890123456789012345678901234567890123456789012345678\ 278 901 280 # same as above, but every character converted to a backslash, 281 # and the offending "\\n" on column 69 is replaced by an 'x\n'. 282 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 283 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 284 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 285 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\x 286 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 287 \\ 288 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 289 \\\ 291 # one very long line (280 characters) 292 12345678901234567890123456789012345678901234567890123456789012345678\ 293 90123456789012345678901234567890123456789012345678901234567890123456\ 294 78901234567890123456789012345678901234567890123456789012345678901234\ 295 56789012345678901234567890123456789012345678901234567890123456789012\ 296 34567890 298 # same as above, but every character converted to a backslash 299 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 300 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 301 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 302 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 303 \\\\\\\\ 305 6. Security Considerations 307 This BCP has no Security Considerations. 309 7. IANA Considerations 311 This BCP has no IANA Considerations. 313 8. References 315 8.1. Normative References 317 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 318 Requirement Levels", BCP 14, RFC 2119, 319 DOI 10.17487/RFC2119, March 1997, 320 . 322 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 323 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 324 May 2017, . 326 8.2. Informative References 328 [RFC7994] Flanagan, H., "Requirements for Plain-Text RFCs", 329 RFC 7994, DOI 10.17487/RFC7994, December 2016, 330 . 332 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 333 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 334 . 336 [yang-doctors-list] 337 "[yang-doctors] automating yang doctor reviews", 338 . 341 Appendix A. POSIX Shell Script 343 This non-normative appendix section includes a shell script that can 344 both fold and unfold artwork based on the solution presented in this 345 document. 347 As a testament for the simplicity of this solution, note that at the 348 core of the script are the following two one-liners: 350 For folding: 351 gsed "/.\{$testcol\}/s/\(.\{$foldcol\}\)/\1\\\\\n/g" 353 For unfolding: 354 gsed ":x; /[^\t]\\{$foldcol\\}\\\\\$/N; s/\\\\\n/\t/; tx; s/\t//g" 356 Disclaimer: this script has the limitation of disallowing the input 357 file from containing any TAB ('\t') characters. 359 =====START SCRIPT===== 361 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 363 #!/bin/bash 364 # 365 # the only reason why /bin/sh isn't being used 366 # is because "echo -n" is broken on the Mac. 368 print_usage() { 369 echo 370 echo "Folds the text file, only if needed, at the specified" 371 echo "column, according to BCP XX." 372 echo 373 echo "Usage: $0 [-c ] [-r] -i -o " 374 echo 375 echo " -c: column to fold on (default: 69)" 376 echo " -r: reverses the operation" 377 echo " -i: the input filename" 378 echo " -o: the output filename" 379 echo " -d: show debug messages" 380 echo " -h: show this message" 381 echo 382 echo "Exit status code: zero on success, non-zero otherwise." 383 echo 384 } 386 # global vars, do not edit 387 debug=0 388 reversed=0 389 infile="" 390 outfile="" 391 maxcol=69 # default, may be overridden by param 392 hdr_txt="=== NOTE: '\' line wrapping per BCP XX (RFC XXXX) ===" 393 equal_chars="===========================================" 395 fold_it() { 396 # since upcomming tests are >= (not >) 397 testcol=`expr "$maxcol" + 1` 399 # check if file needs folding 400 grep ".\{$testcol\}" $infile >> /dev/null 2>&1 401 if [ $? -ne 0 ]; then 402 if [[ $debug -eq 1 ]]; then 403 echo "nothing to do" 404 fi 405 cp $infile $outfile 406 return 0 407 fi 409 foldcol=`expr "$maxcol" - 1` # for the inserted '\' char 411 # ensure file doesn't have any '\' char on $maxcol already 412 # - as this would lead to false positives... 413 grep "^.\{$foldcol\}\\\\$" $infile >> /dev/null 2>&1 414 if [ $? -eq 0 ]; then 415 echo 416 echo "Error: infile has a '\\\' on colomn $maxcol already." 417 echo 418 exit 1 419 fi 421 # calculate '=' character-filled header 422 length=${#hdr_txt} 423 left_sp=`expr \( "$maxcol" - "$length" \) / 2` 424 right_sp=`expr "$maxcol" - "$length" - "$left_sp"` 425 header=`printf "%.*s%s%.*s" "$left_sp" "$equal_chars" "$hdr_txt" "\ 426 $right_sp" "$equal_chars"` 428 # generate outfile and return 429 echo -ne "$header\n\n" > $outfile 430 gsed "/.\{$testcol\}/s/\(.\{$foldcol\}\)/\1\\\\\n/g" < $infile >> \ 431 $outfile 432 return 0 433 } 434 unfold_it() { 435 # check if it looks like a BCP XX header 436 line=`head -n 1 $infile | fgrep "$hdr_txt"` 437 if [ $? -ne 0 ]; then 438 if [[ $debug -eq 1 ]]; then 439 echo "nothing to do" 440 fi 441 cp $infile $outfile 442 return 0 443 fi 445 # determine what maxcol value was used 446 maxcol=${#line} 448 # output all but the first two lines (the header) to wip (work in \ 449 progress) file 450 awk "NR>2" $infile > /tmp/wip 452 # unfold wip file 453 foldcol=`expr "$maxcol" - 1` # for the inserted '\' char 454 gsed ":x; /[^\t]\\{$foldcol\\}\\\\\$/N; s/\\\\\n/\t/; tx; s/\t//g"\ 455 /tmp/wip > $outfile 457 # clean up and return 458 rm /tmp/wip 459 return 0 460 } 462 process_input() { 463 while [ "$1" != "" ]; do 464 if [ "$1" == "-h" -o "$1" == "--help" ]; then 465 print_usage 466 exit 1 467 fi 468 if [ "$1" == "-d" ]; then 469 debug=1 470 fi 471 if [ "$1" == "-c" ]; then 472 maxcol="$2" 473 shift 474 fi 475 if [ "$1" == "-r" ]; then 476 reversed=1 477 fi 478 if [ "$1" == "-i" ]; then 479 infile="$2" 480 shift 482 fi 483 if [ "$1" == "-o" ]; then 484 outfile="$2" 485 shift 486 fi 487 shift 488 done 490 if [ -z "$infile" ]; then 491 echo 492 echo "Error: infile parameter missing (use -h for help)" 493 echo 494 exit 1 495 fi 497 if [ -z "$outfile" ]; then 498 echo 499 echo "Error: outfile parameter missing (use -h for help)" 500 echo 501 exit 1 502 fi 504 if [ ! -f "$infile" ]; then 505 echo 506 echo "Error: specified file \"$infile\" is does not exist." 507 echo 508 exit 1 509 fi 511 min_supported=${#hdr_txt} 512 if [ $maxcol -lt $min_supported ]; then 513 echo 514 echo "Error: the folding column cannot be less than $min_support\ 515 ed" 516 echo 517 exit 1 518 fi 520 max_supported=`expr ${#equal_chars} + ${#hdr_txt} + ${#equal_chars\ 521 }` 522 if [ $maxcol -gt $max_supported ]; then 523 echo 524 echo "Error: the folding column cannot be more than $max_support\ 525 ed" 526 echo 527 exit 1 528 fi 530 } 532 main() { 533 if [ "$#" == "0" ]; then 534 print_usage 535 exit 1 536 fi 538 process_input $@ 540 if [[ $reversed -eq 0 ]]; then 541 fold_it 542 code=$? 543 else 544 unfold_it 545 code=$? 546 fi 547 exit $code 548 } 550 main "$@" 552 =====END SCRIPT===== 554 Acknowledgements 556 The authors thank the RFC Editor for confirming that there are no set 557 convention today for handling long lines in artwork. 559 Authors' Addresses 561 Kent Watsen 562 Juniper Networks 564 EMail: kwatsen@juniper.net 566 Qin Wu 567 Huawei Technologies 569 EMail: bill.wu@huawei.com 571 Adrian Farrel 572 Juniper Networks 574 EMail: afarrel@juniper.net 575 Benoit Claise 576 Cisco Systems, Inc. 578 EMail: bclaise@cisco.com