--- 1/draft-ietf-netmod-artwork-folding-07.txt 2019-08-02 12:13:15.065729958 -0700 +++ 2/draft-ietf-netmod-artwork-folding-08.txt 2019-08-02 12:13:15.133731688 -0700 @@ -1,21 +1,21 @@ NETMOD Working Group K. Watsen Internet-Draft Watsen Networks Intended status: Best Current Practice A. Farrel -Expires: January 24, 2020 Old Dog Consulting +Expires: February 3, 2020 Old Dog Consulting Q. Wu Huawei Technologies - July 23, 2019 + August 2, 2019 Handling Long Lines in Inclusions in Internet-Drafts and RFCs - draft-ietf-netmod-artwork-folding-07 + draft-ietf-netmod-artwork-folding-08 Abstract This document defines two strategies for handling long lines in width-bounded text content. One strategy is based on the historic use of a single backslash ('\') character to indicate where line- folding has occurred, with the continuation occurring with the first non-space (' ') character on the next line. The second strategy extends the first strategy by adding a second backslash character to identify where the continuation begins and thereby able to handle @@ -31,21 +31,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on January 24, 2020. + This Internet-Draft will expire on February 3, 2020. Copyright Notice Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -75,40 +75,43 @@ 7.1.2. Body . . . . . . . . . . . . . . . . . . . . . . . . 7 7.2. Algorithm . . . . . . . . . . . . . . . . . . . . . . . . 7 7.2.1. Folding . . . . . . . . . . . . . . . . . . . . . . . 7 7.2.2. Unfolding . . . . . . . . . . . . . . . . . . . . . . 9 8. The Double Backslash Strategy ('\\') . . . . . . . . . . . . 9 8.1. Folded Structure . . . . . . . . . . . . . . . . . . . . 9 8.1.1. Header . . . . . . . . . . . . . . . . . . . . . . . 9 8.1.2. Body . . . . . . . . . . . . . . . . . . . . . . . . 10 8.2. Algorithm . . . . . . . . . . . . . . . . . . . . . . . . 10 8.2.1. Folding . . . . . . . . . . . . . . . . . . . . . . . 10 - 8.2.2. Unfolding . . . . . . . . . . . . . . . . . . . . . . 11 + 8.2.2. Unfolding . . . . . . . . . . . . . . . . . . . . . . 12 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 12 9.1. Example Showing Boundary Conditions . . . . . . . . . . . 12 9.1.1. Using '\' . . . . . . . . . . . . . . . . . . . . . . 12 9.1.2. Using '\\' . . . . . . . . . . . . . . . . . . . . . 13 9.2. Example Showing Multiple Wraps of a Single Line . . . . . 13 9.2.1. Using '\' . . . . . . . . . . . . . . . . . . . . . . 13 - 9.2.2. Using '\\' . . . . . . . . . . . . . . . . . . . . . 13 - 9.3. Example Showing "Smart" Folding . . . . . . . . . . . . . 13 + 9.2.2. Using '\\' . . . . . . . . . . . . . . . . . . . . . 14 + 9.3. Example Showing "Smart" Folding . . . . . . . . . . . . . 14 9.3.1. Using '\' . . . . . . . . . . . . . . . . . . . . . . 14 9.3.2. Using '\\' . . . . . . . . . . . . . . . . . . . . . 15 - 10. Security Considerations . . . . . . . . . . . . . . . . . . . 16 - 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 - 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 - 12.1. Normative References . . . . . . . . . . . . . . . . . . 16 - 12.2. Informative References . . . . . . . . . . . . . . . . . 16 - Appendix A. POSIX Shell Script: rfcfold . . . . . . . . . . . . 18 - Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 26 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 + 9.4. Example Showing "Forced" Folding . . . . . . . . . . . . 16 + 9.4.1. Using '\' . . . . . . . . . . . . . . . . . . . . . . 17 + 9.4.2. Using '\\' . . . . . . . . . . . . . . . . . . . . . 17 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 17 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 + 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 12.1. Normative References . . . . . . . . . . . . . . . . . . 18 + 12.2. Informative References . . . . . . . . . . . . . . . . . 18 + Appendix A. POSIX Shell Script: rfcfold . . . . . . . . . . . . 19 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 28 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 1. Introduction [RFC7994] sets out the requirements for plain-text RFCs and states that each line of an RFC (and hence of an Internet-Draft) must be limited to 72 characters followed by the character sequence that denotes an end-of-line (EOL). Internet-Drafts and RFCs often include example text or code fragments. Many times the example text or code exceeds the 72 @@ -335,35 +338,39 @@ horizontal tab characters appear, either resolve them to space characters or exit, forcing the input provider to convert them to space characters themselves first. Scan the text content to ensure at least one line exceeds the desired maximum. If no line exceeds the desired maximum, exit (this text content does not need to be folded). Scan the text content to ensure no existing lines already end with a backslash ('\') character, as this would lead to an ambiguous result. - If such a line is found, exit (this text content cannot be folded). + If such a line is found, and its width is less than the desired + maximum, then it SHOULD be flagged for forced folding (folding even + though unnecessary). If the folding implementation doesn't support + forced foldings, it MUST exit. If this text content needs to and can be folded, insert the header described in Section 7.1.1, ensuring that any additional printable characters surrounding the header does not result in a line exceeding the desired maximum. For each line in the text content, from top-to-bottom, if the line - exceeds the desired maximum, then fold the line by: + exceeds the desired maximum, or requires a forced folding, then fold + the line by: 1. Determine where the fold will occur. This location MUST be before or at the desired maximum column, and MUST NOT be chosen such that the character immediately after the fold is a space (' ') character. If no such location can be found, then exit (this - text content cannot be folded) + text content cannot be folded). 2. At the location where the fold is to occur, insert a backslash ('\') character followed by the end of line character sequence. 3. On the following line, insert any number of space (' ') characters. The result of the previous operation is that the next line starts with an arbitrary number of space (' ') characters, followed by the character that was previously occupying the position where the fold @@ -607,22 +613,22 @@ 9.3. Example Showing "Smart" Folding This example illustrates how readability can be improved via "smart" folding, whereby folding occurs at format-specific locations and format-specific indentations are used. The text content was manually folded, since the script in the appendix does not implement smart folding. - Note that the header is surrounded by different printable characters - then shown in the script-generated examples. + Note that the headers are surrounded by different printable + characters than shown in the script-generated examples. 9.3.1. Using '\' [NOTE: '\' line wrapping per BCP XX (RFC XXXX)] @@ -698,20 +704,88 @@ ietf-interfaces 2018-02-20 urn:ietf:params:xml:ns:yang:ietf-interfaces ... ... +9.4. Example Showing "Forced" Folding + + This example illustrates how invalid sequences in lines that do not + have to be folded can be handled via forced folding, whereby the + folding occurs even though unnecessary. + + The following line exceeds a 68-char max, thus demands folding + 123456789012345678901234567890123456789012345678901234567890123456789 + + This line ends with a backslash \ + + This line ends with a backslash \ + \ This line begins with a backslash + + Following is an indented 3x3 block of backslashes: + \\\ + \\\ + \\\ + + The samples below were manually folded, since the script in the + appendix does not implement forced folding. + + Note that the headers are prefixed by a pound ('#') character, rather + than surrounded by equal ('=') characters as shown in the script- + generated examples. + +9.4.1. Using '\' + + # NOTE: '\' line wrapping per BCP XX (RFC XXXX) + + The following line exceeds a 68-char max, thus demands folding + 1234567890123456789012345678901234567890123456789012345678901234567\ + 89 + + This line ends with a backslash \\ + + This line ends with a backslash \\ + + \ This line begins with a backslash + + Following is an indented 3x3 block of backslashes: + \\\\ + + \\\\ + + \\\ + +9.4.2. Using '\\' + + # NOTE: '\\' line wrapping per BCP XX (RFC XXXX) + + The following line exceeds a 68-char max, thus demands folding + 1234567890123456789012345678901234567890123456789012345678901234567\ + \89 + + This line ends with a backslash \ + + This line ends with a backslash \\ + \ + \ This line begins with a backslash + + Following is an indented 3x3 block of backslashes: + \\\\ + \ + \\\\ + \ + \\\ + 10. Security Considerations This BCP has no Security Considerations. 11. IANA Considerations This BCP has no IANA Considerations. 12. References @@ -768,23 +842,34 @@ within a larger document (e.g., an Internet draft or RFC), then another tool must be used to extract the content from the larger document before utilizing this script. For readability purposes, this script forces the minimally supported line length to be eight characters longer than the raw header text defined in Section 7.1.1 and Section 8.1.1 so as to ensure that the header can be wrapped by a space (' ') character and three equal ('=') characters on each side of the raw header text. + This script does not implement the whitespace-avoidance logic + described in Section 7.2.1. In such case, the script will exit with + one of the following message: + + Error: infile has a space character occuring on the + folding column. This file cannot be folded using the + '\' strategy. + This script does not implement the "forced folding" logic described - in Section 8.2.1. In such cases the script will exit with the - message: + in Section 7.2.1 or Section 8.2.1. In such cases the script will + exit with one of the following message: + + Error: infile has a line ending with a '\' character + This file cannot be folded using the '\' strategy. Error: infile has a line ending with a '\' character followed by a '\' character as the first non-space character on the next line. This script cannot fold this file using '\\' strategy without there being false positives produced in the unfolding (i.e., this script does not attempt to proactively force-fold such lines, as described in RFC XXXX). Shell-level end-of-line backslash ('\') characters have been @@ -1025,33 +1111,33 @@ return 0 } unfold_it_1() { temp_dir=`mktemp -d` # output all but the first two lines (the header) to wip file awk "NR>2" $infile > $temp_dir/wip # unfold wip file - "$SED" ':S;$!N;s/\\\n *//;t S;P;D' $temp_dir/wip > $outfile + "$SED" '{H;$!d};x;s/^\n//;s/\\\n *//g' $temp_dir/wip > $outfile return 0 } unfold_it_2() { temp_dir=`mktemp -d` # output all but the first two lines (the header) to wip file awk "NR>2" $infile > $temp_dir/wip # unfold wip file - "$SED" ':S;$!N;s/\\\n *\\//;t S;P;D' $temp_dir/wip > $outfile + "$SED" '{H;$!d};x;s/^\n//;s/\\\n *\\//g' $temp_dir/wip > $outfile return 0 } unfold_it() { # check if file needs unfolding line=`head -n 1 $infile` result=`echo $line | fgrep "$hdr_txt_1"` if [ $? -eq 0 ]; then unfold_it_1