idnits 2.17.1 draft-kwatsen-netmod-artwork-folding-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 (June 18, 2018) is 2132 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 369, 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 Internet Architecture Board (IAB) K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Best Current Practice Q. Wu 5 Expires: December 20, 2018 Huawei Technologies 6 June 18, 2018 8 Handling Long Lines in Artwork in Drafts 9 draft-kwatsen-netmod-artwork-folding-03 11 Abstract 13 This document introduces a simple and yet time-proven strategy for 14 handling long lines in artwork in drafts using a backslash ('\') 15 character where line-folding has occurred. The strategy works on any 16 text based artwork, producing consistent results regardless the 17 artwork content. Using a per-artwork header, the strategy is both 18 self-documenting and enables automated reconstitution of the original 19 artwork. 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 https://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 December 20, 2018. 38 Copyright Notice 40 Copyright (c) 2018 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 (https://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 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 57 3. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3.1. Automated folding of long lines in artwork . . . . . . . 3 59 3.2. Automated reconstitution of original artwork . . . . . . 3 60 4. Limitations . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 4.1. Doesn't work well on graphical artwork . . . . . . . . . 3 62 4.2. Doesn't work as well as format-specific options . . . . . 4 63 5. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 5.1. Header . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 5.2. Folding . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 5.3. Unfolding . . . . . . . . . . . . . . . . . . . . . . . . 5 67 5.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 69 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 8.1. Normative References . . . . . . . . . . . . . . . . . . 8 72 8.2. Informative References . . . . . . . . . . . . . . . . . 8 73 Appendix A. POSIX Shell Script . . . . . . . . . . . . . . . . . 9 74 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 77 1. Introduction 79 Internet drafts many times contain artwork that exceed the 72 80 character limit specified by RFC 7994 [RFC7994]. The "xml2rfc" 81 utility, in an effort to maintain clean formatting, issues a warning 82 whenever artwork lines exceed 69 characters. According to RFC 83 Editor, there is currently no convention in place for how to handle 84 long lines, other than clearly indicating that some manipulation has 85 occurred. 87 This document introduces a simple and yet time-proven strategy for 88 handling long lines using a backslash ('\') character where line- 89 folding has occurred. The strategy works on any text based artwork, 90 producing consistent results regardless the artwork content. Using a 91 per-artwork header, the strategy is both self-documenting and enables 92 automated reconstitution of the original artwork. 94 2. Requirements Language 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 98 "OPTIONAL" in this document are to be interpreted as described in BCP 99 14 [RFC2119] [RFC8174] when, and only when, they appear in all 100 capitals, as shown here. 102 3. Goals 104 3.1. Automated folding of long lines in artwork 106 Automated folding of long lines is needed in order to support draft 107 compilations that entail a) validation of source input files (e.g., 108 YANG, XML, JSON, ABNF, ASN.1) and/or b) dynamic generation of output 109 (e.g., tree diagrams) that are stitched into the final draft to be 110 submitted. 112 Generally, in order for tooling to be able to process input files, 113 the files must be in their original/natural state, which may include 114 having some long lines. Thus, these source files need to be modified 115 before inclusion in the draft in order to satisfy the line length 116 limits. This modification SHOULD be automated to reduce effort and 117 errors resulting from manual effort. 119 Similarly, dynamically generated output (e.g., tree diagrams) must 120 also be modified, if necessary, in order for the resulting I-D to 121 satisfy the line length limits. When needed, this effort again 122 SHOULD be automated to reduce effort and errors resulting from manual 123 effort. 125 3.2. Automated reconstitution of original artwork 127 Automated reconstitution of the original artwork is needed to support 128 validation of artwork extracted from drafts. Already YANG modules 129 are extracted from drafts and validated as part of the draft- 130 submission process. Additionally, there has been some discussion 131 regarding needing to do the same for examples contained within drafts 132 ([yang-doctors-list]). Thus, it SHOULD be possible to mechanically 133 reconstitute artwork in order to satisfy the tooling input parsers. 135 4. Limitations 137 4.1. Doesn't work well on graphical artwork 139 While the solution presented in this document will work on any kind 140 of text-based artwork, it is most useful on artwork that represents 141 sourcecode (e.g., YANG, XML, JSON, etc.) or, more generally, on 142 artwork that has not been laid out in two dimensions (e.g., 143 diagrams). 145 The issue regards the readability of the folded artwork in the draft. 146 Artwork that is unpredictable is especially susceptible is looking 147 bad when folded; falling into this category are most UML diagrams. 148 Artwork that is somewhat structured (e.g., YANG tree diagrams 149 [RFC8340]) fair better when folded, as the eyes seem to be able to 150 still see the vertical lines, even when they are interrupted. 152 It is thus NOT RECOMMENDED to use the solution presented in this 153 document on graphical artwork. 155 4.2. Doesn't work as well as format-specific options 157 The solution presented in this document works generically for all 158 artwork, as it only views artwork as plain text. However, various 159 formats sometimes have mechanisms that can be used to prevent long 160 lines. 162 For instance, some source formats allow any quoted string to be 163 broken up into substrings separated by a concatenation character 164 ('+'), any of which can by on a different line. 166 In another example, some languages allow factoring out chucks of code 167 out into "functions" or "groupings". Using such call outs is 168 especially helpful when in some deeply-nested code, as it typically 169 resets the indentation back to the first column. 171 As such, it is RECOMMENDED that authors do as much as possible within 172 the selected format to avoid long lines. 174 5. Solution 176 The following two sections provide the folding and unfolding 177 algorithms that MUST be implemented to align with this BCP. 179 5.1. Header 181 Any artwork that has been folded as specificed by this document MUST 182 contain the header described in this section. 184 The header is two lines long. 186 The first line is the following 53-character string that has been 187 padded with roughly equal numbers of equal ('=') characters to reach 188 the artwork's maximum line length. This line is self-describing in 189 three ways: use of '\' character, identification of BCP/RFC, and 190 identification of what the maximum line length is for the artwork. 191 Following is the mimimal header string (53-characters): 193 === NOTE: '\' line wrapping per BCP XX (RFC XXXX) === 195 The second line is a blank line. This line provides visual 196 seperation for the readability. 198 5.2. Folding 200 Scan the artwork to see if any line exceeds the desired maximum. If 201 no line exceeds the desired maximum, exit (this artwork does not need 202 to be folded). 204 Ensure that the desired maximum is not less than then minumum header, 205 which is 53 characters. If the desired maximum is less than this 206 minimum, exit (this artwork can not be folded). 208 Scan the artwork to ensure no existing lines already end with a '\' 209 character on the desired maximum column, as this would be lead to an 210 ambiguous result. If such a line is found, exit (this artwork cannot 211 be folded). 213 For each line in the artwork, from top-to-bottom, if the line exceeds 214 the desired maximum, then fold the line at the desired maximum column 215 by inserting the string "\\n" (backlash followed by line return) at 216 the column before the maximum column. Note that the column before 217 needs to be used in order to enable the '\' character to be placed on 218 the desired maximum column. The result of this operation is that the 219 character that was on the maximum colomn is now the first character 220 of the next line. 222 Continue in this manner until reaching the end of the artwork. Note 223 that this algorithm naturally addresses the case where the remainder 224 of a folded line is still longer than the desired maximum, and hence 225 needs to be folded again, ad infinitum. 227 5.3. Unfolding 229 Scan the beginning of the artwork for the header described in 230 Section 5.1. If the header is not present, starting on the first 231 line of the artwork, exit (this artwork does not need to be 232 unfolded). 234 Caluculate the folding-column used from the length of the provided 235 header. 237 Remove the 2-line header from the artwork. 239 For each line in the artwork, from top-to-bottom, if the line has a 240 '\' on the folding-column followed by a '\n' character, then remove 241 both the '\' and '\n' characters, which will bring up the next line, 242 and then scan the remainder of the line to see if it again has a '\' 243 after folding-column characters followed by a '\n' character, and so 244 on. 246 Continue in this manner until reaching the end of the artwork. 248 5.4. Example 250 The following self-documenting example illustrates the result of the 251 folding algorithm running over a specific artwork input. 253 The specific input used cannot be presented here, as it would again 254 need to be folded. Alas, only the result can be provided. 256 Some things to note about the following example: 258 o This artwork is exactly 69 characters wide, the widest possible 259 before `xml2rfc` starts to issue warnings. 261 o The line having the 'x' character on the 69th column would've been 262 illegal input had the '\' been used. 264 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 266 # boundary condition tests using numbers for counting purposes 267 123456789012345678901234567890123456789012345678901234567890123456 268 1234567890123456789012345678901234567890123456789012345678901234567 269 12345678901234567890123456789012345678901234567890123456789012345678 270 123456789012345678901234567890123456789012345678901234567890123456789 271 12345678901234567890123456789012345678901234567890123456789012345678\ 272 90 273 12345678901234567890123456789012345678901234567890123456789012345678\ 274 901 276 # same as above, but every character converted to a backslash 277 # ...and the offending "\\n" on column 69 is removed... 278 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 279 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 280 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 281 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\x 282 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 283 \\ 284 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 285 \\\ 287 # one very long line (280 characters) 288 12345678901234567890123456789012345678901234567890123456789012345678\ 289 90123456789012345678901234567890123456789012345678901234567890123456\ 290 78901234567890123456789012345678901234567890123456789012345678901234\ 291 56789012345678901234567890123456789012345678901234567890123456789012\ 292 34567890 294 # same as above, but every character converted to a backslash 295 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 296 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 297 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 298 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 299 \\\\\\\\ 301 6. Security Considerations 303 This BCP has no Security Considerations. 305 7. IANA Considerations 307 This BCP has no IANA Considerations. 309 8. References 311 8.1. Normative References 313 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 314 Requirement Levels", BCP 14, RFC 2119, 315 DOI 10.17487/RFC2119, March 1997, 316 . 318 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 319 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 320 May 2017, . 322 8.2. Informative References 324 [RFC7994] Flanagan, H., "Requirements for Plain-Text RFCs", 325 RFC 7994, DOI 10.17487/RFC7994, December 2016, 326 . 328 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 329 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 330 . 332 [yang-doctors-list] 333 "[yang-doctors] automating yang doctor reviews", 334 . 337 Appendix A. POSIX Shell Script 339 This non-normative appendix section includes a shell script that can 340 both fold and unfold artwork based on the solution presented in this 341 document. 343 As a testament for the simplicity of this solution, note that at the 344 core of the script are the following two one-liners: 346 For folding: 347 gsed "/.\{$testcol\}/s/\(.\{$foldcol\}\)/\1\\\\\n/g" 349 For unfolding: 350 gsed ":x; /[^\t]\\{$foldcol\\}\\\\\$/N; s/\\\\\n/\t/; tx; s/\t//g" 352 Disclaimer: this script has the limitation of disallowing the input 353 file from containing any TAB ('\t') characters. 355 =====START SCRIPT===== 357 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 359 #!/bin/bash 360 # 361 # the only reason why /bin/sh isn't being used 362 # is because "echo -n" is broken on the Mac. 364 print_usage() { 365 echo 366 echo "Folds the text file, only if needed, at the specified" 367 echo "column, according to BCP XX." 368 echo 369 echo "Usage: $0 [-c ] [-r] -i -o " 370 echo 371 echo " -c: column to fold on (default: 69)" 372 echo " -r: reverses the operation" 373 echo " -i: the input filename" 374 echo " -o: the output filename" 375 echo " -d: show debug messages" 376 echo " -h: show this message" 377 echo 378 echo "Exit status code: zero on success, non-zero otherwise." 379 echo 380 } 382 # global vars, do not edit 383 debug=0 384 reversed=0 385 infile="" 386 outfile="" 387 maxcol=69 # default, may be overridden by param 388 hdr_txt="=== NOTE: '\' line wrapping per BCP XX (RFC XXXX) ===" 389 equal_chars="===========================================" 391 fold_it() { 392 # since upcomming tests are >= (not >) 393 testcol=`expr "$maxcol" + 1` 395 # check if file needs folding 396 grep ".\{$testcol\}" $infile >> /dev/null 2>&1 397 if [ $? -ne 0 ]; then 398 if [[ $debug -eq 1 ]]; then 399 echo "nothing to do" 400 fi 401 cp $infile $outfile 402 return 0 403 fi 405 foldcol=`expr "$maxcol" - 1` # for the inserted '\' char 407 # ensure file doesn't have any '\' char on $maxcol already 408 # - as this would lead to false positives... 409 grep "^.\{$foldcol\}\\\\$" $infile >> /dev/null 2>&1 410 if [ $? -eq 0 ]; then 411 echo 412 echo "Error: infile has a '\\\' on colomn $maxcol already." 413 echo 414 exit 1 415 fi 417 # calculate '=' character-filled header 418 length=${#hdr_txt} 419 left_sp=`expr \( "$maxcol" - "$length" \) / 2` 420 right_sp=`expr "$maxcol" - "$length" - "$left_sp"` 421 header=`printf "%.*s%s%.*s" "$left_sp" "$equal_chars" "$hdr_txt" "\ 422 $right_sp" "$equal_chars"` 424 # generate outfile and return 425 echo -ne "$header\n\n" > $outfile 426 gsed "/.\{$testcol\}/s/\(.\{$foldcol\}\)/\1\\\\\n/g" < $infile >> \ 427 $outfile 428 return 0 429 } 430 unfold_it() { 431 # check if it looks like a BCP XX header 432 line=`head -n 1 $infile | fgrep "$hdr_txt"` 433 if [ $? -ne 0 ]; then 434 if [[ $debug -eq 1 ]]; then 435 echo "nothing to do" 436 fi 437 cp $infile $outfile 438 return 0 439 fi 441 # determine what maxcol value was used 442 maxcol=${#line} 444 # output all but the first two lines (the header) to wip (work in \ 445 progress) file 446 awk "NR>2" $infile > /tmp/wip 448 # unfold wip file 449 foldcol=`expr "$maxcol" - 1` # for the inserted '\' char 450 gsed ":x; /[^\t]\\{$foldcol\\}\\\\\$/N; s/\\\\\n/\t/; tx; s/\t//g"\ 451 /tmp/wip > $outfile 453 # clean up and return 454 rm /tmp/wip 455 return 0 456 } 458 process_input() { 459 while [ "$1" != "" ]; do 460 if [ "$1" == "-h" -o "$1" == "--help" ]; then 461 print_usage 462 exit 1 463 fi 464 if [ "$1" == "-d" ]; then 465 debug=1 466 fi 467 if [ "$1" == "-c" ]; then 468 maxcol="$2" 469 shift 470 fi 471 if [ "$1" == "-r" ]; then 472 reversed=1 473 fi 474 if [ "$1" == "-i" ]; then 475 infile="$2" 476 shift 478 fi 479 if [ "$1" == "-o" ]; then 480 outfile="$2" 481 shift 482 fi 483 shift 484 done 486 if [ -z "$infile" ]; then 487 echo 488 echo "Error: infile parameter missing (use -h for help)" 489 echo 490 exit 1 491 fi 493 if [ -z "$outfile" ]; then 494 echo 495 echo "Error: outfile parameter missing (use -h for help)" 496 echo 497 exit 1 498 fi 500 if [ ! -f "$infile" ]; then 501 echo 502 echo "Error: specified file \"$infile\" is does not exist." 503 echo 504 exit 1 505 fi 507 min_supported=${#hdr_txt} 508 if [ $maxcol -lt $min_supported ]; then 509 echo 510 echo "Error: the folding column cannot be less than $min_support\ 511 ed" 512 echo 513 exit 1 514 fi 516 max_supported=`expr ${#equal_chars} + ${#hdr_txt} + ${#equal_chars\ 517 }` 518 if [ $maxcol -gt $max_supported ]; then 519 echo 520 echo "Error: the folding column cannot be more than $max_support\ 521 ed" 522 echo 523 exit 1 524 fi 526 } 528 main() { 529 if [ "$#" == "0" ]; then 530 print_usage 531 exit 1 532 fi 534 process_input $@ 536 if [[ $reversed -eq 0 ]]; then 537 fold_it 538 code=$? 539 else 540 unfold_it 541 code=$? 542 fi 543 exit $code 544 } 546 main "$@" 548 =====END SCRIPT===== 550 Acknowledgements 552 The authors thank the RFC Editor for confirming that there are no set 553 convention today for handling long lines in artwork. 555 Authors' Addresses 557 Kent Watsen 558 Juniper Networks 560 EMail: kwatsen@juniper.net 562 Qin Wu 563 Huawei Technologies 565 EMail: bill.wu@huawei.com