--- 1/draft-ietf-netmod-artwork-folding-11.txt 2020-01-20 17:13:17.803481227 -0800 +++ 2/draft-ietf-netmod-artwork-folding-12.txt 2020-01-20 17:13:17.859482651 -0800 @@ -1,23 +1,23 @@ NETMOD Working Group K. Watsen Internet-Draft Watsen Networks -Intended status: Informational E. Erik -Expires: May 6, 2020 Individual Contributor +Intended status: Informational E. Auerswald +Expires: July 23, 2020 Individual Contributor A. Farrel Old Dog Consulting Q. Wu Huawei Technologies - November 3, 2019 + January 20, 2020 Handling Long Lines in Inclusions in Internet-Drafts and RFCs - draft-ietf-netmod-artwork-folding-11 + draft-ietf-netmod-artwork-folding-12 Abstract This document defines two strategies for handling long lines in width-bounded text content. One strategy is based on the historical 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 is thereby able to handle @@ -43,25 +43,25 @@ 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 May 6, 2020. + This Internet-Draft will expire on July 23, 2020. Copyright Notice - Copyright (c) 2019 IETF Trust and the persons identified as the + Copyright (c) 2020 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 carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as @@ -107,21 +107,21 @@ 9.3.2. Using '\\' . . . . . . . . . . . . . . . . . . . . . 15 9.4. Example Showing "Forced" Folding . . . . . . . . . . . . 16 9.4.1. Using '\' . . . . . . . . . . . . . . . . . . . . . . 17 9.4.2. Using '\\' . . . . . . . . . . . . . . . . . . . . . 17 10. Security Considerations . . . . . . . . . . . . . . . . . . . 18 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 12.1. Normative References . . . . . . . . . . . . . . . . . . 18 12.2. Informative References . . . . . . . . . . . . . . . . . 19 Appendix A. Bash Shell Script: rfcfold . . . . . . . . . . . . . 20 - Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 29 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 30 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 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 @@ -1028,21 +1028,21 @@ equal_chars="=======================================================" space_chars=" " temp_dir="" prog_name='rfcfold' # functions for diagnostic messages prog_msg() { if [[ "$quiet" -eq 0 ]]; then format_string="${prog_name}: $1: %s\n" shift - printf -- "$format_string" "$@" >&2 + printf -- "$format_string" "$*" >&2 fi } err() { prog_msg 'Error' "$@" } warn() { prog_msg 'Warning' "$@" } @@ -1050,47 +1050,44 @@ dbg() { if [[ "$debug" -eq 1 ]]; then prog_msg 'Debug' "$@" fi } # determine name of [g]sed binary type gsed > /dev/null 2>&1 && SED=gsed || SED=sed # warn if a non-GNU sed utility is used - "$SED" --version < /dev/null 2> /dev/null \ - | grep GNU > /dev/null 2>&1 || \ - warn 'not using GNU `sed` (likely cause if an error occurs)' - + "$SED" --version < /dev/null 2> /dev/null | grep -q GNU || \ + warn 'not using GNU `sed` (likely cause if an error occurs).' cleanup() { rm -rf "$temp_dir" } trap 'cleanup' EXIT fold_it_1() { # ensure input file doesn't contain the fold-sequence already if [[ -n "$("$SED" -n '/\\$/p' "$infile")" ]]; then - err "infile has a line ending with a '\\' character."\ - "This file cannot be folded using the '\\' strategy"\ + err "infile '$infile' has a line ending with a '\\' character."\ + "This script cannot fold this file using the '\\' strategy"\ "without there being false positives produced in the"\ - "unfolding (i.e., this script does not force-fold"\ - "such lines, as described in BCP XXX, RFC XXXX)." + "unfolding." return 1 fi # where to fold foldcol=$(expr "$maxcol" - 1) # for the inserted '\' char # ensure input file doesn't contain whitespace on the fold column grep -q "^\(.\{$foldcol\}\)\{1,\} " "$infile" if [[ $? -eq 0 ]]; then - err "infile has a space character occurring on the"\ + err "infile '$infile' has a space character occurring on the"\ "folding column. This file cannot be folded using the"\ "'\\' strategy." return 1 fi # center header text length=$(expr ${#hdr_txt_1} + 2) left_sp=$(expr \( "$maxcol" - "$length" \) / 2) right_sp=$(expr "$maxcol" - "$length" - "$left_sp") header=$(printf "%.*s %s %.*s" "$left_sp" "$equal_chars"\ @@ -1099,34 +1096,32 @@ # generate outfile echo "$header" > "$outfile" echo "" >> "$outfile" "$SED" 's/\(.\{'"$foldcol"'\}\)\(..\)/\1\\\n\2/;t M;b;:M;P;D;'\ < "$infile" >> "$outfile" 2> /dev/null if [[ $? -ne 0 ]]; then return 1 fi return 0 } + fold_it_2() { # where to fold foldcol=$(expr "$maxcol" - 1) # for the inserted '\' char - # ensure input file doesn't contain the fold-sequence already - if [[ -n "$("$SED" -n '/\\$/{N;s/\\\n[ ]*\\/&/p}' "$infile")" ]] + if [[ -n "$("$SED" -n '/\\$/{N;s/\\\n[ ]*\\/&/p;D}' "$infile")" ]] then - err "infile has a line ending with a '\\' character"\ + err "infile '$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 force-fold such lines, as described"\ - "in BCP XXX, RFC XXXX)." + "false positives produced in the unfolding." return 1 fi # center header text length=$(expr ${#hdr_txt_2} + 2) left_sp=$(expr \( "$maxcol" - "$length" \) / 2) right_sp=$(expr "$maxcol" - "$length" - "$left_sp") header=$(printf "%.*s %s %.*s" "$left_sp" "$equal_chars"\ "$hdr_txt_2" "$right_sp" "$equal_chars") @@ -1138,59 +1133,62 @@ if [[ $? -ne 0 ]]; then return 1 fi return 0 } fold_it() { # ensure input file doesn't contain a TAB grep -q $'\t' "$infile" if [[ $? -eq 0 ]]; then - err "infile contains a TAB character, which is not allowed." + err "infile '$infile' contains a TAB character, which is not"\ + "allowed." return 1 fi # folding of input containing ASCII control or non-ASCII characters # may result in a wrong folding column and is not supported if type gawk > /dev/null 2>&1; then env LC_ALL=C gawk '/[\000-\014\016-\037\177]/{exit 1}' "$infile"\ - || warn 'infile contains ASCII control characters (unsupported).' + || warn "infile '$infile' contains ASCII control characters"\ + "(unsupported)." env LC_ALL=C gawk '/[^\000-\177]/{exit 1}' "$infile"\ - || warn 'infile contains non-ASCII characters (unsupported).' + || warn "infile '$infile' contains non-ASCII characters"\ + "(unsupported)." else - dbg 'no GNU Awk, skipping checks for special characters.' + dbg "no GNU Awk, skipping checks for special characters." fi # check if file needs folding testcol=$(expr "$maxcol" + 1) grep -q ".\{$testcol\}" "$infile" if [[ $? -ne 0 ]]; then - dbg "nothing to do" + dbg "nothing to do; copying infile to outfile." cp "$infile" "$outfile" return 255 fi if [[ "$strategy" -eq 1 ]]; then fold_it_1 return $? fi if [[ "$strategy" -eq 2 ]]; then fold_it_2 return $? fi quiet_sav="$quiet" quiet=1 fold_it_1 result=$? quiet="$quiet_sav" if [[ "$result" -ne 0 ]]; then - dbg "Folding strategy 1 didn't succeed, trying strategy 2..." + dbg "Folding strategy '1' didn't succeed, trying strategy '2'..." fold_it_2 return $? fi return 0 } unfold_it_1() { temp_dir=$(mktemp -d) # output all but the first two lines (the header) to wip file @@ -1214,87 +1212,104 @@ return 0 } unfold_it() { # check if file needs unfolding line=$(head -n 1 "$infile") line2=$("$SED" -n '2p' "$infile") result=$(echo "$line" | fgrep "$hdr_txt_1") if [[ $? -eq 0 ]]; then if [[ -n "$line2" ]]; then - err "the second line is not empty." + err "the second line in '$infile' is not empty." return 1 fi unfold_it_1 return $? fi result=$(echo "$line" | fgrep "$hdr_txt_2") if [[ $? -eq 0 ]]; then if [[ -n "$line2" ]]; then - err "the second line is not empty." + err "the second line in '$infile' is not empty." return 1 fi unfold_it_2 return $? fi - dbg "nothing to do" + dbg "nothing to do; copying infile to outfile." cp "$infile" "$outfile" return 255 } process_input() { while [[ "$1" != "" ]]; do if [[ "$1" == "-h" ]] || [[ "$1" == "--help" ]]; then print_usage exit 0 elif [[ "$1" == "-d" ]]; then debug=1 elif [[ "$1" == "-q" ]]; then quiet=1 elif [[ "$1" == "-s" ]]; then + if [[ "$#" -eq "1" ]]; then + err "option '-s' needs an argument (use -h for help)." + exit 1 + fi strategy="$2" shift elif [[ "$1" == "-c" ]]; then + if [[ "$#" -eq "1" ]]; then + err "option '-c' needs an argument (use -h for help)." + exit 1 + fi col_gvn=1 maxcol="$2" shift elif [[ "$1" == "-r" ]]; then reversed=1 elif [[ "$1" == "-i" ]]; then + if [[ "$#" -eq "1" ]]; then + err "option '-i' needs an argument (use -h for help)." + exit 1 + fi infile="$2" shift elif [[ "$1" == "-o" ]]; then + if [[ "$#" -eq "1" ]]; then + err "option '-o' needs an argument (use -h for help)." + exit 1 + fi outfile="$2" shift else - warn "ignoring unknown option '$1'" + warn "ignoring unknown option '$1'." fi shift done if [[ -z "$infile" ]]; then - err "infile parameter missing (use -h for help)" + err "infile parameter missing (use -h for help)." exit 1 fi if [[ -z "$outfile" ]]; then - err "outfile parameter missing (use -h for help)" + err "outfile parameter missing (use -h for help)." exit 1 fi if [[ ! -f "$infile" ]]; then - err "specified file \"$infile\" is does not exist." + err "specified file '$infile' does not exist." exit 1 + fi if [[ "$col_gvn" -eq 1 ]] && [[ "$reversed" -eq 1 ]]; then - warn "'-c' option ignored when unfolding (option '-r')" + warn "'-c' option ignored when unfolding (option '-r')." fi if [[ "$strategy" -eq 0 ]] || [[ "$strategy" -eq 2 ]]; then min_supported=$(expr ${#hdr_txt_2} + 8) else min_supported=$(expr ${#hdr_txt_1} + 8) fi if [[ "$maxcol" -lt "$min_supported" ]]; then err "the folding column cannot be less than $min_supported." exit 1 @@ -1333,26 +1348,22 @@ Acknowledgements The authors thank the RFC Editor for confirming that there was previously no set convention, at the time of this document's publication, for handling long lines in source code inclusions, thus instigating this work. The authors thank the following folks for their various contributions while producing this document (sorted by first name): Benoit Claise, - Gianmarco Bruno, Italo Busi, Joel Jaeggli, Jonathan Hansford, Lou - Berger, Martin Bjorklund, and Rob Wilton. - - Special acknowledgement to Erik Auerswald for his contributions to - the `rfcfold` script, especially for greatly improving the `sed` one- - liners used therein. + Ben Kaduk, Gianmarco Bruno, Italo Busi, Joel Jaeggli, Jonathan + Hansford, Lou Berger, Martin Bjorklund, and Rob Wilton. Authors' Addresses Kent Watsen Watsen Networks EMail: kent+ietf@watsen.net Erik Auerswald Individual Contributor