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

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/