rfc8792xml2.original.xml   rfc8792.xml 
<?xml version='1.0'?> <?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd"> <!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">
<?rfc toc="yes"?> <rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="info"
<?rfc symrefs="yes"?> ipr="trust200902" docName="draft-ietf-netmod-artwork-folding-12"
<?rfc sortrefs="yes" ?> number="8792" obsoletes="" updates="" submissionType="IETF"
<?rfc compact="yes"?> consensus="true" xml:lang="en" tocInclude="true" symRefs="true" sortRefs="t
<?rfc subcompact="no"?> rue" version="3">
<?rfc linkmailto="no" ?> <!-- xml2rfc v2v3 conversion 2.40.1 -->
<?rfc editing="no" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes"?>
<?rfc rfcedstyle="yes"?>
<?rfc-ext allow-markup-in-artwork="yes" ?>
<?rfc-ext include-index="no" ?>
<!--<?rfc strict="no"?> -->
<rfc category="info"
ipr="trust200902"
docName="draft-ietf-netmod-artwork-folding-12">
<front> <front>
<title abbrev="Handling Long Lines in Inclusions">Handling Long Lines in I <title abbrev="Handling Long Lines in Content">Handling Long Lines in
nclusions in Internet-Drafts and RFCs</title> Content of Internet-Drafts and RFCs</title>
<author initials="K." surname="Watsen" fullname="Kent Watsen">
<organization>Watsen Networks</organization> <seriesInfo name="RFC" value="8792"/>
<address> <author initials="K." surname="Watsen" fullname="Kent Watsen">
<email>kent+ietf@watsen.net</email> <organization>Watsen Networks</organization>
</address> <address>
</author> <email>kent+ietf@watsen.net</email>
<author initials="E." surname="Auerswald" fullname="Erik Auerswald"> </address>
<organization>Individual Contributor</organization> </author>
<address> <author initials="E." surname="Auerswald" fullname="Erik Auerswald">
<email>auerswal@unix-ag.uni-kl.de</email> <organization>Individual Contributor</organization>
</address> <address>
</author> <email>auerswal@unix-ag.uni-kl.de</email>
<author initials="A." surname="Farrel" fullname="Adrian Farrel" > </address>
<organization>Old Dog Consulting</organization> </author>
<address> <author initials="A." surname="Farrel" fullname="Adrian Farrel">
<email>adrian@olddog.co.uk</email> <organization>Old Dog Consulting</organization>
</address> <address>
</author> <email>adrian@olddog.co.uk</email>
<author initials="Q." surname="Wu" fullname="Qin Wu"> </address>
<organization>Huawei Technologies</organization> </author>
<address> <author initials="Q." surname="Wu" fullname="Qin Wu">
<email>bill.wu@huawei.com</email> <organization>Huawei Technologies</organization>
</address> <address>
</author> <email>bill.wu@huawei.com</email>
<date/> </address>
<area>Operations</area> </author>
<workgroup>NETMOD Working Group</workgroup> <date month="June" year="2020"/>
<keyword>sourcecode</keyword> <keyword>sourcecode</keyword>
<keyword>artwork</keyword> <keyword>artwork</keyword>
<abstract> <abstract>
<t>This document defines two strategies for handling long lines in wid <t>This document defines two strategies for handling long lines in width-b
th-bounded ounded
text content. One strategy is based on the historical use of a single text content. One strategy, called the "single backslash" strategy, i
backslash s based on the historical use of a single backslash
('\') character to indicate where line-folding has occurred, with the continuation ('\') character to indicate where line-folding has occurred, with the continuation
occurring with the first non-space (' ') character on the next line. occurring with the first character that is not a space character ('&nb
The second sp;') on the next line. The second
strategy extends the first strategy by adding a second backslash chara strategy, called the "double backslash" strategy, extends the first st
cter to rategy by adding a second backslash character to
identify where the continuation begins and is thereby able to handle c ases not identify where the continuation begins and is thereby able to handle c ases not
supported by the first strategy. Both strategies use a self-describin g header supported by the first strategy. Both strategies use a self-describin g header
enabling automated reconstitution of the original content.</t> enabling automated reconstitution of the original content.</t>
</abstract> </abstract>
<note title="Editorial Note (To be removed by RFC Editor)"> </front>
<t>Please be aware that this document uses throughout the five-charact <middle>
er text <section numbered="true" toc="default">
sequence located between the following two double-quotes: "(' ')". <name>Introduction</name>
It has been <t><xref target="RFC7994" format="default"/> sets out the requirements for
observed that some renderings of this text sequence produces a natur
al
line break at the space character in the middle, thus causing "('" t
o appear
at the end of the first line and "')" to appear at the beginning of
the next
line. Such a line-break is confusing and should not occur in the RF
C output
formats.</t>
</note>
</front>
<middle>
<section title="Introduction">
<t><xref target="RFC7994"/> sets out the requirements for
plain-text RFCs and states that each line of an RFC (and hence of 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 an Internet-Draft) must be limited to 72 characters followed by
the character sequence that denotes an end-of-line (EOL).</t> the character sequence that denotes an end-of-line (EOL).</t>
<t>Internet-Drafts and RFCs often include example text or code
<t>Internet-Drafts and RFCs often include example text or code fragments. Many times, the example text or code exceeds the 72-characte
fragments. Many times the example text or code r line-length limit. The 'xml2rfc' utility <xref target="xml2rfc" format="defau
exceeds the 72 character line-length limit. The `xml2rfc` <xref target= lt"/>, at the time of this document's publication, does not
"xml2rfc"/>
utility, at the time of this document's publication, does not
attempt to wrap the content of such inclusions, simply issuing attempt to wrap the content of such inclusions, simply issuing
a warning whenever lines exceed 69 characters. Historically, a warning whenever lines exceed 69 characters. Historically,
there has been no RFC-Editor-recommended convention in place there has been no convention recommended by the RFC Editor in place
for how to handle long lines in such inclusions, other than advising for how to handle long lines in such inclusions, other than advising
authors to clearly indicate what manipulation has occurred.</t> authors to clearly indicate what manipulation has occurred.</t>
<t>This document defines two strategies for handling long lines in width-b ounded <t>This document defines two strategies for handling long lines in width-b ounded
text content. One strategy is based on the historical use of a single b ackslash text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash
('\') character to indicate where line-folding has occurred, with the co ntinuation ('\') character to indicate where line-folding has occurred, with the co ntinuation
occurring with the first non-space (' ') character on the next line. Th occurring with the first character that is not a space character ('&nbsp
e second ;') on the next line. The second
strategy extends the first strategy by adding a second backslash charact strategy, called the "double backslash" strategy, extends the first stra
er to tegy by adding a second backslash character to
identify where the continuation begins and is thereby able to handle cas es not identify where the continuation begins and is thereby able to handle cas es not
supported by the first strategy. Both strategies use a self-describing header supported by the first strategy. Both strategies use a self-describing header
enabling automated reconstitution of the original content.</t> enabling automated reconstitution of the original content.</t>
<t>The strategies defined in this document work on any text content but ar
<t>The strategies defined in this document work on any text content, but a e
re
primarily intended for a structured sequence of lines, such as would be primarily intended for a structured sequence of lines, such as would be
referenced by the &lt;sourcecode&gt; element defined in Section 2.48 of referenced by the &lt;sourcecode&gt; element defined in <xref target="RF
<xref target="RFC7991"/>, rather than for two-dimensional imagery, such C7991" sectionFormat="of" section="2.48"/>, rather than for two-dimensional imag
as would be referenced by the &lt;artwork&gt; element defined in Section ery, such
2.5 of <xref target="RFC7991"/>.</t> as would be referenced by the &lt;artwork&gt; element defined in <xref t
arget="RFC7991" sectionFormat="of" section="2.5"/>.</t>
<t>Note that text files are represented as lines having their first <t>Note that text files are represented as lines having their first
character in column 1, and a line length of N where the last character in column 1, and a line length of N where the last
character is in the Nth column and is immediately followed by an end character is in the Nth column and is immediately followed by an
of line character sequence.</t> end-of-line character sequence.</t>
</section> </section>
<section numbered="true" toc="default">
<section title="Applicability Statement"> <name>Applicability Statement</name>
<t>The formats and algorithms defined in this document may be used <t>The formats and algorithms defined in this document may be used
in any context, whether for IETF documents or in other situations in any context, whether for IETF documents or in other situations
where structured folding is desired.</t> where structured folding is desired.</t>
<t>Within the IETF, this work primarily targets the xml2rfc v3 <t>Within the IETF, this work primarily targets the xml2rfc v3
&lt;sourcecode&gt; element (Section 2.48 of <xref target="RFC7991"/>) &lt;sourcecode&gt; element (<xref target="RFC7991" sectionFormat="of"
and the xml2rfc v2 &lt;artwork&gt; element (Section 2.5 of section="2.48"/>)
<xref target="RFC7749"/>) that, for lack of a better option, is and the xml2rfc&nbsp;v2 &lt;artwork&gt; element (<xref
currently used for both source code and artwork. This work may target="RFC7749" sectionFormat="of" section="2.5"/>), which, for
lack of a better option, is used in xml2rfc v2 for both source code an
d artwork. This work may
also be used for the xml2rfc v3 &lt;artwork&gt; element also be used for the xml2rfc v3 &lt;artwork&gt; element
(Section 2.5 of <xref target="RFC7991"/>) but, as described in (<xref target="RFC7991" sectionFormat="of" section="2.5"/>), but as de
<xref target="not-for-art"/>, it is generally not recommended.</t> scribed in
</section> <xref target="not-for-art" format="default"/>, it is generally not rec
ommended.</t>
<section title="Requirements Language" anchor="requirements-language"> </section>
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL <section anchor="requirements-language" numbered="true" toc="default">
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", <name>Requirements Language</name>
"MAY", and "OPTIONAL" in this document are to be interpreted as <t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>",
when, and only when, they appear in all capitals, as shown here.</t> "<bcp14>SHALL NOT</bcp14>", "<bcp14>SHOULD</bcp14>",
</section> "<bcp14>SHOULD NOT</bcp14>",
"<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
<section title="Goals"> "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document
<section title="Automated Folding of Long Lines in Text Content"> are to be interpreted as described in BCP&nbsp;14
<t>Automated folding of long lines is needed in order to support <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only
drafts that are dynamically compiled to include content with when, they appear in all capitals, as shown here.</t>
</section>
<section numbered="true" toc="default">
<name>Goals</name>
<section numbered="true" toc="default">
<name>Automated Folding of Long Lines in Text Content</name>
<t>Automated folding of long lines is needed in order to support
documents that are dynamically compiled to include content with
potentially unconstrained line lengths. For instance, the potentially unconstrained line lengths. For instance, the
build process may wish to include content from other local build process may wish to include content from other local
files or dynamically generated by some external process. files or content that is dynamically generated by some external proc ess.
Both of these cases are discussed next.</t> Both of these cases are discussed next.</t>
<t>Many drafts need to include the content from local files (e.g., <t>Many documents need to include the content from local files (e.g.,
XML, JSON, ABNF, ASN.1). Prior to including a file's content, XML, JSON, ABNF, ASN.1). Prior to including a file's content,
the build process SHOULD first validate these source files the build process <bcp14>SHOULD</bcp14> first validate these source files
using format-specific validators. In order for such tooling using format-specific validators. In order for such tooling
to be able to process the files, the files must be in their to be able to process the files, the files must be in their
original/natural state, which may entail them having some long original/natural state, which may entail them having some long
lines. Thus, these source files need to be folded before lines. Thus, these source files need to be folded before
inclusion into the XML document, in order to satisfy `xml2rfc` inclusion into the XML document, in order to satisfy 'xml2rfc'
line length limits.</t> line-length limits.</t>
<t>Similarly, drafts sometimes contain dynamically generated <t>Similarly, documents sometimes contain dynamically generated
output, typically from an external process operating on the output, typically from an external process operating on the
same source files discussed in the previous paragraph. For same source files discussed in the previous paragraph. For
instance, such processes may translate the input format to instance, such processes may translate the input format to
another format or render a report over or a view of the input another format, or they may render a report on, or a view of, the in put
file. In some cases, the dynamically generated output may file. In some cases, the dynamically generated output may
contain lines exceeding the `xml2rfc` line length limits.</t> contain lines exceeding the 'xml2rfc' line-length limits.</t>
<t>In both cases, folding is required and SHOULD be automated <t>In both cases, folding is required and <bcp14>SHOULD</bcp14> be autom
ated
to reduce effort and errors resulting from manual processing.</t> to reduce effort and errors resulting from manual processing.</t>
</section> </section>
<section title="Automated Reconstitution of the Original Text Content"> <section numbered="true" toc="default">
<t>Automated reconstitution of the exact original text content is need <name>Automated Reconstitution of the Original Text Content</name>
ed to <t>Automated reconstitution of the exact original text content is needed
to
support validation of text-based content extracted from documents.</ t> support validation of text-based content extracted from documents.</ t>
<t>For instance, already YANG <xref target="RFC7950"/> modules are <t>For instance, YANG modules <xref target="RFC7950"
format="default"/> are already
extracted from Internet-Drafts and validated as part of the extracted from Internet-Drafts and validated as part of the
draft-submission process. Additionally, the desire to validate submission process. Additionally, the desire to validate
instance examples (i.e., XML/JSON documents) contained within instance examples (i.e., XML/JSON documents) contained within
Internet-Drafts has been discussed (<xref target="yang-doctors-threa Internet-Drafts has been discussed <xref
d"/>).</t> target="yang-doctors-thread" format="default"/>.
</section> </t>
</section> </section>
</section>
<section title="Limitations"> <section numbered="true" toc="default">
<section title="Not Recommended for Graphical Artwork" anchor="not-for-a <name>Limitations</name>
rt"> <section anchor="not-for-art" numbered="true" toc="default">
<t>While the solution presented in this document works on any <name>Not Recommended for Graphical Artwork</name>
<t>While the solution presented in this document works on any
kind of text-based content, it is most useful on content that kind of text-based content, it is most useful on content that
represents source code (XML, JSON, etc.) or, more generally, on represents source code (XML, JSON, etc.) or, more generally, on
content that has not been laid out in two dimensions (e.g., diagrams). </t> content that has not been laid out in two dimensions (e.g., diagrams). </t>
<t>Fundamentally, the issue is whether the text content remains readab le <t>Fundamentally, the issue is whether the text content remains readable
once folded. Text content that is unpredictable is especially suscept ible once folded. Text content that is unpredictable is especially suscept ible
to looking bad when folded; falling into this category are most to looking bad when folded; falling into this category are most
UML diagrams, YANG tree diagrams, and ASCII art in general.</t> Unified Modeling Language (UML) diagrams, YANG tree diagrams, and ASCI
<t>It is NOT RECOMMENDED to use the solution presented in I art in general.</t>
<t>It is <bcp14>NOT RECOMMENDED</bcp14> to use the solution presented in
this document on graphical artwork.</t> this document on graphical artwork.</t>
</section> </section>
<section title="Doesn't Work as Well as Format-Specific Options"> <section numbered="true" toc="default">
<t>The solution presented in this document works generically <name>Doesn't Work as Well as Format-Specific Options</name>
<t>The solution presented in this document works generically
for all text-based content, as it only views content as plain for all text-based content, as it only views content as plain
text. However, various formats sometimes have built-in mechanisms text. However, various formats sometimes have built-in mechanisms
that are better suited to prevent long lines.</t> that are better suited to prevent long lines.</t>
<t>For instance, both the `pyang` <xref target="pyang"/> and `yanglint <t>For instance, both the 'pyang' and 'yanglint' utilities <xref target=
` <xref target="yanglint"/> utilities "pyang"
have the command line option "--tree-line-length" that can format="default"/> <xref target="yanglint" format="default"/>
be used to indicate a desired maximum line length for when have the command-line option "tree-line-length", which can
generating tree diagrams <xref target="RFC8340"/>.</t> be used to indicate a desired maximum line length when
<t>In another example, some source formats (e.g., YANG generating YANG tree diagrams <xref target="RFC8340" format="default"/
<xref target="RFC7950"/>) allow any quoted string to be >.
</t>
<t>In another example, some source formats (e.g., YANG
<xref target="RFC7950" format="default"/>) allow any quoted string to
be
broken up into substrings separated by a concatenation broken up into substrings separated by a concatenation
character (e.g., '+'), any of which can be on a different character (e.g., '+'), any of which can be on a different
line.</t> line.</t>
<t>It is RECOMMENDED that authors do as much as possible <t>It is <bcp14>RECOMMENDED</bcp14> that authors do as much as possible
within the selected format to avoid long lines.</t> within the selected format to avoid long lines.</t>
</section>
</section> </section>
</section>
<section title="Two Folding Strategies" anchor="two-strategies"> <section anchor="two-strategies" numbered="true" toc="default">
<t>This document defines two nearly identical strategies for folding <name>Two Folding Strategies</name>
<t>This document defines two nearly identical strategies for folding
text-based content. text-based content.
<list style="hanging" hangIndent="6"> </t>
<t hangText=" The Single Backslash Strategy ('\'):">Uses a backsla <dl newline="true" spacing="normal">
sh <dt>The Single Backslash Strategy ('\'):</dt>
('\') character at the end of the line where folding occurs, and <dd>Uses a backslash
assumes that the continuation begins at the first character that i ('\') character at the end of the line where folding occurs,
s not and assumes that the continuation begins at the first character th
a space character (' ') on the following line.</t> at is not
<t hangText=" The Double Backslash Strategy ('\\'):">Uses a backsl a space character ('&nbsp;') on the following line.</dd>
ash <dt>The Double Backslash Strategy ('\\'):</dt>
('\') character at the end of the line where folding occurs, and <dd>Uses a backslash
assumes that the continuation begins after a second backslash ('\' ('\') character at the end of the line where folding occurs,
) and assumes that the continuation begins after a second backslash
character on the following line.</t> ('\')
</list> character on the following line.</dd>
</t> </dl>
<section title="Comparison"> <section numbered="true" toc="default">
<t>The first strategy produces more readable output, however it is <name>Comparison</name>
<t>The first strategy produces output that is more readable. However, (1
)&nbsp;it is
significantly more likely to encounter unfoldable input (e.g., significantly more likely to encounter unfoldable input (e.g.,
a long line containing only space characters) and, for long lines a long line containing only space characters), and (2)&nbsp;for long lines
that can be folded, automation implementations may encounter that can be folded, automation implementations may encounter
scenarios that will produce errors without special care.</t> scenarios that, without special care, will produce errors.</t>
<t>The second strategy produces less readable output, but is <t>The second strategy produces output that is less readable, but it is
unlikely to encounter unfoldable input, there are no long lines unlikely to encounter unfoldable input, there are no long lines
that cannot be folded, and no special care is required for when that cannot be folded, and no special care is required when
folding a long line.</t> folding a long line.</t>
</section> </section>
<section title="Recommendation"> <section numbered="true" toc="default">
<t>It is RECOMMENDED for implementations to first attempt to fold <name>Recommendation</name>
<t>It is <bcp14>RECOMMENDED</bcp14> that implementations first attempt t
o fold
content using the single backslash strategy and, only in the content using the single backslash strategy and, only in the
unlikely event that it cannot fold the input or the folding unlikely event that it cannot fold the input or the folding
logic is unable to cope with a contingency occurring on the logic is unable to cope with a contingency occurring on the
desired folding column, then fallback to the double backslash desired folding column, then fall back to the double backslash
strategy.</t> strategy.</t>
</section>
</section> </section>
</section>
<section title="The Single Backslash Strategy ('\')" anchor="single-slash" <section anchor="single-slash" numbered="true" toc="default">
> <name>The Single Backslash Strategy ('\')</name>
<section title="Folded Structure"> <section numbered="true" toc="default">
<t>Text content that has been folded as specified by this strategy <name>Folded Structure</name>
MUST adhere to the following structure.</t> <t>Text content that has been folded as specified by this strategy
<section title="Header" anchor="single-header"> <bcp14>MUST</bcp14> adhere to the following structure.</t>
<t>The header is two lines long.</t> <section anchor="single-header" numbered="true" toc="default">
<t>The first line is the following 46-character string that <name>Header</name>
MAY be surrounded by any number of printable characters. <t>The header is two lines long.</t>
<t>The first line is the following 36-character string; this string
<bcp14>MAY</bcp14> be surrounded by any number of printable characte
rs.
This first line cannot itself be folded. This first line cannot itself be folded.
<figure> </t>
<artwork><![CDATA[ <artwork name="header1_line1.txt"><![CDATA[
NOTE: '\' line wrapping per BCP XXX (RFC XXXX) NOTE: '\' line wrapping per RFC 8792]]></artwork>
]]></artwork> <t>The second line is an empty line, containing only the end-of-line
<postamble>
[Note to RFC Editor: Please replace XXX and XXXX with the numb
ers
assigned to this document and delete this note. Please make t
his
change in multiple places in this document.]
</postamble>
</figure>
</t>
<t>The second line is an empty line, containing only the end-of-line
character sequence. This line provides visual separation for character sequence. This line provides visual separation for
readability.</t> readability.</t>
</section> </section>
<section title="Body"> <section numbered="true" toc="default">
<t>The character encoding is the same as described in Section 2 <name>Body</name>
of <xref target="RFC7994"/>, except that, per <xref target="RFC7991" <t>The character encoding is the same as the encoding described in <xr
/>, ef target="RFC7994" sectionFormat="of" section="2"/>, except that, per <xref tar
get="RFC7991" format="default"/>,
tab characters are prohibited.</t> tab characters are prohibited.</t>
<t>Lines that have a backslash ('\') occurring as the last character in <t>Lines that have a backslash ('\') occurring as the last character i n
a line are considered "folded".</t> a line are considered "folded".</t>
<t>Exceptionally long lines may be folded multiple times.</t> <t>Exceptionally long lines MAY be folded multiple times.</t>
</section>
</section> </section>
</section>
<section title="Algorithm" anchor="single-algorithm"> <section anchor="single-algorithm" numbered="true" toc="default">
<t>This section describes a process for folding and unfolding long <name>Algorithm</name>
<t>This section describes a process for folding and unfolding long
lines when they are encountered in text content.</t> lines when they are encountered in text content.</t>
<t>The steps are complete, but implementations MAY achieve the same <t>The steps are complete, but implementations <bcp14>MAY</bcp14> achiev e the same
result in other ways.</t> result in other ways.</t>
<t>When a larger document contains multiple instances of text content <t>When a larger document contains multiple instances of text content
that may need to be folded or unfolded, another process must that may need to be folded or unfolded, another process must
insert/extract the individual text content instances to/from the insert&wj;/extract the individual text content instances to/from the
larger document prior to utilizing the algorithms described in this larger document prior to utilizing the algorithms described in this
section. For example, the `xiax` utility <xref target="xiax"/> does section. For example, the 'xiax' utility <xref target="xiax" format
this.</t> ="default"/> does this.</t>
<section title="Folding" anchor="single-folding"> <section anchor="single-folding" numbered="true" toc="default">
<t>Determine the desired maximum line length from input to the <name>Folding</name>
line-wrapping process, such as from a command line <t>Determine the desired maximum line length from input to the
line-wrapping process, such as from a command-line
parameter. If no value is explicitly specified, the value "69" parameter. If no value is explicitly specified, the value "69"
SHOULD be used.</t> <bcp14>SHOULD</bcp14> be used.</t>
<t>Ensure that the desired maximum line length is not less than <t>Ensure that the desired maximum line length is not less than
the minimum header, which is 46 characters. If the desired the minimum header, which is 36 characters. If the desired
maximum line length is less than this minimum, exit (this text-based maximum line length is less than this minimum, exit (this text-based
content cannot be folded).</t> content cannot be folded).</t>
<t>Scan the text content for horizontal tab characters. If any <t>Scan the text content for horizontal tab characters. If any
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 characters or exit, forcing the input provider to convert them
to space characters themselves first.</t> to space characters themselves first.</t>
<t>Scan the text content to ensure at least one line exceeds the <t>Scan the text content to ensure that at least one line exceeds the
desired maximum. If no line exceeds the desired maximum, exit desired maximum. If no line exceeds the desired maximum, exit
(this text content does not (this text content does not
need to be folded).</t> need to be folded).</t>
<t>Scan the text content to ensure no existing lines already end wit h a <t>Scan the text content to ensure that no existing lines already end with a
backslash ('\') character, as this could lead to an ambiguous result . backslash ('\') character, as this could lead to an ambiguous result .
If such a line is found, and its width is less than the desired maxi mum, If such a line is found, and its width is less than the desired maxi mum,
then it SHOULD be flagged for forced folding (folding even though then it <bcp14>SHOULD</bcp14> be flagged for "forced" folding (foldi ng even though
unnecessary). If the folding implementation doesn't support forced unnecessary). If the folding implementation doesn't support forced
foldings, it MUST exit.</t> foldings, it <bcp14>MUST</bcp14> exit.</t>
<t>If this text content needs to and can be folded, insert the heade <t>If this text content needs to, and can, be folded, insert the heade
r r
described in <xref target="single-header" />, ensuring that any addi described in <xref target="single-header" format="default"/>, ensuri
tional ng that any additional
printable characters surrounding the header do not result in a printable characters surrounding the header do not result in a
line exceeding the desired maximum.</t> line exceeding the desired maximum.</t>
<t>For each line in the text content, from top-to-bottom, if the lin <t>For each line in the text content, from top to bottom, if the line
e exceeds the desired maximum or requires a forced folding, then fol
exceeds the desired maximum, or requires a forced folding, then fo d
ld the line by performing the following steps:
the line by: </t>
<list style="numbers"> <ol spacing="normal" type="1">
<t>Determine where the fold will occur. This location MUST be b <li>Determine where the fold will occur. This location <bcp14>MUST<
efore /bcp14> be before
or at the desired maximum column, and MUST NOT be chosen such or at the desired maximum column and <bcp14>MUST NOT</bcp14> b
that e chosen such that
the character immediately after the fold is a space (' ') char the character immediately after the fold is a space ('&nbsp;')
acter. character.
For forced foldings, the location is between the '\' and the e For forced foldings, the location is between the '\' and the e
nd of nd-of-line sequence. If no such location can be found, then exit (this
line sequence. If no such location can be found, then exit (t text content cannot be folded).</li>
his <li>At the location where the fold is to occur, insert a backslash
text content cannot be folded).</t> ('\') character followed by the end-of-line character sequence
<t>At the location where the fold is to occur, insert a backslas .</li>
h <li>On the following line, insert any number of space ('&nbsp;') cha
('\') character followed by the end of line character sequence racters,
.</t> provided that the resulting line does not
<t>On the following line, insert any number of space (' ') chara exceed the desired maximum.
cters, </li>
subject to the resulting line not exceeding the desired maximu </ol>
m.</t> <t>The result of the previous operation is that the next line starts
</list> with an arbitrary number of space ('&nbsp;') characters, followed by
</t> the
<t>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 character that was previously occupying the position where the fold
occurred.</t> occurred.</t>
<t>Continue in this manner until reaching the end of the text conten t. Note <t>Continue in this manner until reaching the end of the text content. Note
that this algorithm naturally addresses the case where the remainder that this algorithm naturally addresses the case where the remainder
of a folded line is still longer than the desired maximum, and hence of a folded line is still longer than the desired maximum and, hence ,
needs to be folded again, ad infinitum.</t> needs to be folded again, ad infinitum.</t>
<t>The process described in this section is illustrated by the "fold <t>The process described in this section is illustrated by the "fold_i
_it_1()" t_1()"
function in <xref target="script" />.</t> function in <xref target="script" format="default"/>.</t>
</section> </section>
<section title="Unfolding"> <section numbered="true" toc="default">
<t>Scan the beginning of the text content for the header described i <name>Unfolding</name>
n <t>Scan the beginning of the text content for the header described in
<xref target="single-header"/>. If the header is not present, exi <xref target="single-header" format="default"/>. If the header is
t not present, exit
(this text content does not need to be unfolded).</t> (this text content does not need to be unfolded).</t>
<t>Remove the 2-line header from the text content.</t> <t>Remove the two-line header from the text content.</t>
<t>For each line in the text content, from top-to-bottom, if the lin <t>For each line in the text content, from top to bottom, if the line
e has has
a backslash ('\') character immediately followed by the end of line a backslash ('\') character immediately followed by the end-of-line
character sequence, then the line can be unfolded. character sequence, then the line can be unfolded.
Remove the backslash ('\') character, the end of line character Remove the backslash ('\') character, the end-of-line character
sequence, and any leading space (' ') characters, which will bring u sequence, and any leading space ('&nbsp;') characters, which will br
p ing up
the next line. Then continue to scan each line in the text content the next line. Then continue to scan each line in the text content
starting with the current line (in case it was multiply folded).</t> starting with the current line (in case it was multiply folded).</t>
<t>Continue in this manner until reaching the end of the text conten <t>Continue in this manner until reaching the end of the text content.
t.</t> </t>
<t>The process described in this section is illustrated by the "unfo <t>The process described in this section is illustrated by the "unfold
ld_it_1()" _it_1()"
function in <xref target="script" />.</t> function in <xref target="script" format="default"/>.</t>
</section>
</section> </section>
</section> </section>
</section>
<section title="The Double Backslash Strategy ('\\')" anchor="double-slash <section anchor="double-slash" numbered="true" toc="default">
"> <name>The Double Backslash Strategy ('\\')</name>
<section numbered="true" toc="default">
<section title="Folded Structure"> <name>Folded Structure</name>
<t>Text content that has been folded as specified by this strategy <t>Text content that has been folded as specified by this strategy
MUST adhere to the following structure.</t> <bcp14>MUST</bcp14> adhere to the following structure.</t>
<section title="Header" anchor="double-header"> <section anchor="double-header" numbered="true" toc="default">
<t>The header is two lines long.</t> <name>Header</name>
<t>The first line is the following 47-character string that <t>The header is two lines long.</t>
MAY be surrounded by any number of printable characters. <t>The first line is the following 37-character string; this string
<bcp14>MAY</bcp14> be surrounded by any number of printable characte
rs.
This first line cannot itself be folded. This first line cannot itself be folded.
<figure> </t>
<artwork><![CDATA[ <artwork name="header2_line1.txt"><![CDATA[
NOTE: '\\' line wrapping per BCP XXX (RFC XXXX) NOTE: '\\' line wrapping per RFC 8792]]></artwork>
]]></artwork> <t>The second line is an empty line, containing only the end-of-line
<postamble>
[Note to RFC Editor: Please replace XXX and XXXX with the numb
ers
assigned to this document and delete this note. Please make t
his
change in multiple places in this document.]
</postamble>
</figure>
</t>
<t>The second line is an empty line, containing only the end-of-line
character sequence. This line provides visual separation for character sequence. This line provides visual separation for
readability.</t> readability.</t>
</section> </section>
<section title="Body"> <section numbered="true" toc="default">
<t>The character encoding is the same as described in Section 2 <name>Body</name>
of <xref target="RFC7994"/>, except that, per <xref target="RFC7991" <t>The character encoding is the same as the encoding described in <xr
/>, ef target="RFC7994" sectionFormat="of" section="2"/>, except that, per <xref tar
get="RFC7991" format="default"/>,
tab characters are prohibited.</t> tab characters are prohibited.</t>
<t>Lines that have a backslash ('\') occurring as the last character <t>Lines that have a backslash ('\') occurring as the last character i
in n
a line immediately followed by the end of line character sequence, w a line immediately followed by the end-of-line character sequence, w
hen hen
the subsequent line starts with a backslash ('\') as the first non-s the subsequent line starts with a backslash ('\') as the first
pace character that is not a space character ('&nbsp;'), are considered "
(' ') character, are considered "folded".</t> folded".</t>
<t>Exceptionally long lines may be folded multiple times.</t> <t>Exceptionally long lines MAY be folded multiple times.</t>
</section>
</section> </section>
</section>
<section title="Algorithm" anchor="double-algorithm"> <section anchor="double-algorithm" numbered="true" toc="default">
<t>This section describes a process for folding and unfolding long <name>Algorithm</name>
<t>This section describes a process for folding and unfolding long
lines when they are encountered in text content.</t> lines when they are encountered in text content.</t>
<t>The steps are complete, but implementations MAY achieve the same <t>The steps are complete, but implementations <bcp14>MAY</bcp14> achiev e the same
result in other ways.</t> result in other ways.</t>
<t>When a larger document contains multiple instances of text content <t>When a larger document contains multiple instances of text content
that may need to be folded or unfolded, another process must that may need to be folded or unfolded, another process must
insert/extract the individual text content instances to/from the insert&wj;/extract the individual text content instances to/from the
larger document prior to utilizing the algorithms described in this larger document prior to utilizing the algorithms described in this
section. For example, the `xiax` utility <xref target="xiax"/> does section. For example, the 'xiax' utility <xref target="xiax" format
this.</t> ="default"/> does this.</t>
<section title="Folding" anchor="double-folding"> <section anchor="double-folding" numbered="true" toc="default">
<t>Determine the desired maximum line length from input to the <name>Folding</name>
line-wrapping process, such as from a command line <t>Determine the desired maximum line length from input to the
line-wrapping process, such as from a command-line
parameter. If no value is explicitly specified, the value "69" parameter. If no value is explicitly specified, the value "69"
SHOULD be used.</t> <bcp14>SHOULD</bcp14> be used.</t>
<t>Ensure that the desired maximum line length is not less than <t>Ensure that the desired maximum line length is not less than
the minimum header, which is 47 characters. If the desired the minimum header, which is 37 characters. If the desired
maximum line length is less than this minimum, exit (this text-based maximum line length is less than this minimum, exit (this text-based
content cannot be folded).</t> content cannot be folded).</t>
<t>Scan the text content for horizontal tab characters. If any <t>Scan the text content for horizontal tab characters. If any
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 characters or exit, forcing the input provider to convert them
to space characters themselves first.</t> to space characters themselves first.</t>
<t>Scan the text content to see if any line exceeds the desired maxi mum. <t>Scan the text content to see if any line exceeds the desired maximu m.
If no line exceeds the desired maximum, exit (this text content does not If no line exceeds the desired maximum, exit (this text content does not
need to be folded).</t> need to be folded).</t>
<t>Scan the text content to ensure no existing lines already end wit h a <t>Scan the text content to ensure that no existing lines already end with a
backslash ('\') character while the subsequent line starts with a backslash ('\') character while the subsequent line starts with a
backslash ('\') character as the first non-space (' ') character, backslash ('\') character as the first character that is not a
as this could lead to an ambiguous result. If such a line is found, space character ('&nbsp;'),
and its width is less than the desired maximum, then it SHOULD be as this could lead to an ambiguous result. If such a line is found
and its width is less than the desired maximum, then it <bcp14>SHOUL
D</bcp14> be
flagged for forced folding (folding even though unnecessary). If flagged for forced folding (folding even though unnecessary). If
the folding implementation doesn't support forced foldings, it MUST the folding implementation doesn't support forced foldings, it <bcp1 4>MUST</bcp14>
exit.</t> exit.</t>
<t>If this text content needs to and can be folded, insert the heade <t>If this text content needs to, and can, be folded, insert the heade
r r
described in <xref target="double-header" />, ensuring that any addi described in <xref target="double-header" format="default"/>, ensuri
tional ng that any additional
printable characters surrounding the header do not result in a printable characters surrounding the header do not result in a
line exceeding the desired maximum.</t> line exceeding the desired maximum.</t>
<t>For each line in the text content, from top-to-bottom, if the lin <t>For each line in the text content, from top to bottom, if the line
e exceeds the desired maximum or requires a forced folding, then
exceeds the desired maximum, or requires a forced folding, then fold the line by performing the following steps:
fold the line by: </t>
<list style="numbers"> <ol spacing="normal" type="1">
<t>Determine where the fold will occur. This location MUST be b <li>Determine where the fold will occur. This location <bcp14>MUST<
efore /bcp14> be before
or at the desired maximum column. For forced foldings, the lo cation or at the desired maximum column. For forced foldings, the lo cation
is between the '\' and the end of line sequence on the first l is between the '\' and the end-of-line sequence on the first l
ine.</t> ine.</li>
<t>At the location where the fold is to occur, insert a first <li>At the location where the fold is to occur, insert a first
backslash ('\') character followed by the end of line characte backslash ('\') character followed by the end-of-line characte
r r
sequence.</t> sequence.</li>
<t>On the following line, insert any number of space (' ') chara <li>On the following line, insert any number of space ('&nbsp;') cha
cters, racters,
subject to the resulting line not exceeding the desired maximu provided that the resulting line does not
m, exceed the desired maximum,
followed by a second backslash ('\') character.</t> followed by a second backslash ('\') character.</li>
</list> </ol>
</t> <t>The result of the previous operation is that the next line starts
<t>The result of the previous operation is that the next line starts with an arbitrary number of space ('&nbsp;') characters, followed by
with an arbitrary number of space (' ') characters, followed by a a
backslash ('\') character, immediately followed by the character tha t backslash ('\') character, immediately followed by the character tha t
was previously occupying the position where the fold occurred.</t> was previously occupying the position where the fold occurred.</t>
<t>Continue in this manner until reaching the end of the text conten t. Note <t>Continue in this manner until reaching the end of the text content. Note
that this algorithm naturally addresses the case where the remainder that this algorithm naturally addresses the case where the remainder
of a folded line is still longer than the desired maximum, and hence of a folded line is still longer than the desired maximum and, hence ,
needs to be folded again, ad infinitum.</t> needs to be folded again, ad infinitum.</t>
<t>The process described in this section is illustrated by the "fold <t>The process described in this section is illustrated by the "fold_i
_it_2()" t_2()"
function in <xref target="script" />.</t> function in <xref target="script" format="default"/>.</t>
</section> </section>
<section title="Unfolding"> <section numbered="true" toc="default">
<t>Scan the beginning of the text content for the header described i <name>Unfolding</name>
n <t>Scan the beginning of the text content for the header described in
<xref target="double-header"/>. If the header is not present, exi <xref target="double-header" format="default"/>. If the header is
t not present, exit
(this text content does not need to be unfolded).</t> (this text content does not need to be unfolded).</t>
<t>Remove the 2-line header from the text content.</t> <t>Remove the two-line header from the text content.</t>
<t>For each line in the text content, from top-to-bottom, if the lin <t>For each line in the text content, from top to bottom, if the line
e has has
a backslash ('\') character immediately followed by the end of line a backslash ('\') character immediately followed by the end-of-line
character sequence, and if the next line has a backslash ('\') chara character sequence and if the next line has a backslash ('\') charac
cter ter
as the first non-space (' ') character, then the lines can be unfold as the first character that is not a space character ('&nbsp;'), the
ed. n the lines can be unfolded.
Remove the first backslash ('\') character, the end of line characte Remove the first backslash ('\') character, the end-of-line characte
r r
sequence, any leading space (' ') characters, and the second backsla sequence, any leading space ('&nbsp;') characters, and the second ba
sh ckslash
('\') character, which will bring up the next line. Then continue t ('\') character, which will bring up the next line. Then, continue
o to
scan each line in the text content starting with the current line (i n case scan each line in the text content starting with the current line (i n case
it was multiply folded).</t> it was multiply folded).</t>
<t>Continue in this manner until reaching the end of the text conten <t>Continue in this manner until reaching the end of the text content.
t.</t> </t>
<t>The process described in this section is illustrated by the "unfo <t>The process described in this section is illustrated by the "unfold
ld_it_2()" _it_2()"
function in <xref target="script" />.</t> function in <xref target="script" format="default"/>.</t>
</section>
</section> </section>
</section> </section>
</section>
<section anchor="example" title="Examples"> <section anchor="example" numbered="true" toc="default">
<t>The following self-documenting examples illustrate folded <name>Examples</name>
<t>The following self-documenting examples illustrate folded
text-based content.</t> text-based content.</t>
<t>The source text content cannot be presented here, as it would
<t>The source text content cannot be presented here, as it would
again be folded. Alas, only the results can be provided.</t> again be folded. Alas, only the results can be provided.</t>
<section numbered="true" toc="default">
<section title="Example Showing Boundary Conditions"> <name>Example Showing Boundary Conditions</name>
<t>This example illustrates boundary conditions. The input contains <t>This example illustrates boundary conditions. The input contains
seven lines, each line one character longer than the previous line. seven lines, each line one character longer than the previous line.
Numbers for counting purposes. The default desired maximum column Numbers are used for counting purposes. The default desired maximum column
value "69" is used.</t> value "69" is used.</t>
<section title="Using '\'"> <section numbered="true" toc="default">
<figure> <name>Using '\'</name>
<artwork><![CDATA[ <artwork name="example-1.1.txt.folded" type="" align="left" alt=""><![
========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== CDATA[
========== NOTE: '\' line wrapping per RFC 8792 ===========
123456789012345678901234567890123456789012345678901234567890123456 123456789012345678901234567890123456789012345678901234567890123456
1234567890123456789012345678901234567890123456789012345678901234567 1234567890123456789012345678901234567890123456789012345678901234567
12345678901234567890123456789012345678901234567890123456789012345678 12345678901234567890123456789012345678901234567890123456789012345678
123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789
12345678901234567890123456789012345678901234567890123456789012345678\ 12345678901234567890123456789012345678901234567890123456789012345678\
90 90
12345678901234567890123456789012345678901234567890123456789012345678\ 12345678901234567890123456789012345678901234567890123456789012345678\
901 901
12345678901234567890123456789012345678901234567890123456789012345678\ 12345678901234567890123456789012345678901234567890123456789012345678\
9012 9012]]></artwork>
]]></artwork> </section>
</figure> <section numbered="true" toc="default">
</section> <name>Using '\\'</name>
<section title="Using '\\'"> <artwork name="example-1.2.txt.folded" type="" align="left" alt=""><![
<figure> CDATA[
<artwork><![CDATA[ ========== NOTE: '\\' line wrapping per RFC 8792 ==========
========== NOTE: '\\' line wrapping per BCP XXX (RFC XXXX) ==========
123456789012345678901234567890123456789012345678901234567890123456 123456789012345678901234567890123456789012345678901234567890123456
1234567890123456789012345678901234567890123456789012345678901234567 1234567890123456789012345678901234567890123456789012345678901234567
12345678901234567890123456789012345678901234567890123456789012345678 12345678901234567890123456789012345678901234567890123456789012345678
123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789
12345678901234567890123456789012345678901234567890123456789012345678\ 12345678901234567890123456789012345678901234567890123456789012345678\
\90 \90
12345678901234567890123456789012345678901234567890123456789012345678\ 12345678901234567890123456789012345678901234567890123456789012345678\
\901 \901
12345678901234567890123456789012345678901234567890123456789012345678\ 12345678901234567890123456789012345678901234567890123456789012345678\
\9012 \9012]]></artwork>
]]></artwork>
</figure>
</section>
</section> </section>
</section>
<section title="Example Showing Multiple Wraps of a Single Line"> <section numbered="true" toc="default">
<t>This example illustrates what happens when a very long line needs t <name>Example Showing Multiple Wraps of a Single Line</name>
o <t>This example illustrates what happens when a very long line needs to
be folded multiple times. The input contains one line containing be folded multiple times. The input contains one line containing
280 characters. Numbers for counting purposes. The default 280 characters. Numbers are used for counting purposes. The defaul t
desired maximum column value "69" is used.</t> desired maximum column value "69" is used.</t>
<section title="Using '\'"> <section numbered="true" toc="default">
<figure> <name>Using '\'</name>
<artwork><![CDATA[ <artwork name="example-2.1.txt.folded" type="" align="left" alt=""><![
========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== CDATA[
========== NOTE: '\' line wrapping per RFC 8792 ===========
12345678901234567890123456789012345678901234567890123456789012345678\ 12345678901234567890123456789012345678901234567890123456789012345678\
90123456789012345678901234567890123456789012345678901234567890123456\ 90123456789012345678901234567890123456789012345678901234567890123456\
78901234567890123456789012345678901234567890123456789012345678901234\ 78901234567890123456789012345678901234567890123456789012345678901234\
56789012345678901234567890123456789012345678901234567890123456789012\ 56789012345678901234567890123456789012345678901234567890123456789012\
34567890 34567890]]></artwork>
]]></artwork> </section>
</figure> <section numbered="true" toc="default">
</section> <name>Using '\\'</name>
<section title="Using '\\'"> <artwork name="example-2.2.txt.folded" type="" align="left" alt=""><![
<figure> CDATA[
<artwork><![CDATA[ ========== NOTE: '\\' line wrapping per RFC 8792 ==========
========== NOTE: '\\' line wrapping per BCP XXX (RFC XXXX) ==========
12345678901234567890123456789012345678901234567890123456789012345678\ 12345678901234567890123456789012345678901234567890123456789012345678\
\9012345678901234567890123456789012345678901234567890123456789012345\ \9012345678901234567890123456789012345678901234567890123456789012345\
\6789012345678901234567890123456789012345678901234567890123456789012\ \6789012345678901234567890123456789012345678901234567890123456789012\
\3456789012345678901234567890123456789012345678901234567890123456789\ \3456789012345678901234567890123456789012345678901234567890123456789\
\01234567890 \01234567890]]></artwork>
]]></artwork>
</figure>
</section>
</section> </section>
</section>
<section title="Example Showing &quot;Smart&quot; Folding"> <section numbered="true" toc="default">
<t>This example illustrates how readability can be improved via "smart <name>Example Showing "Smart" Folding</name>
" <t>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.</t> format-specific indentations are used.</t>
<t>The text content was manually folded, since the script in the appen dix <t>The text content was manually folded, since the script in <xref targe t="script"/>
does not implement smart folding.</t> does not implement smart folding.</t>
<t>Note that the headers are surrounded by different printable charact <t>Note that the headers are surrounded by different printable character
ers s
than shown in the script-generated examples.</t> than those shown in the script-generated examples.</t>
<section title="Using '\'"> <section numbered="true" toc="default">
<figure> <name>Using '\'</name>
<artwork><![CDATA[ <artwork name="example-3.1.txt.folded.smart"><![CDATA[
[NOTE: '\' line wrapping per BCP XXX (RFC XXXX)] [NOTE: '\' line wrapping per RFC 8792]
<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>
<name>config-modules</name> <name>config-modules</name>
<module> <module>
<name>ietf-interfaces</name> <name>ietf-interfaces</name>
<revision>2018-02-20</revision> <revision>2018-02-20</revision>
<namespace>\ <namespace>\
urn:ietf:params:xml:ns:yang:ietf-interfaces\ urn:ietf:params:xml:ns:yang:ietf-interfaces\
</namespace> </namespace>
</module> </module>
... ...
</module-set> </module-set>
... ...
</yang-library> </yang-library>]]></artwork>
]]></artwork> <t>Below is the equivalent of the above, but it was folded using the
</figure> script in <xref target="script"/>.</t>
<t>Below is the equivalent to the above, but it was folded using the <artwork name="example-3.1.txt.folded.rfcfold"><![CDATA[
script in the appendix.</t> ========== NOTE: '\' line wrapping per RFC 8792 ===========
<figure>
<artwork><![CDATA[
========== NOTE: '\' line wrapping per BCP XXX (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>
<name>config-modules</name> <name>config-modules</name>
<module> <module>
<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>]]></artwork>
]]></artwork> </section>
</figure> <section numbered="true" toc="default">
</section> <name>Using '\\'</name>
<section title="Using '\\'"> <artwork name="example-3.2.txt.folded.smart"><![CDATA[
<figure> [NOTE: '\\' line wrapping per RFC 8792]
<artwork><![CDATA[
[NOTE: '\\' line wrapping per BCP XXX (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>
<name>config-modules</name> <name>config-modules</name>
<module> <module>
<name>ietf-interfaces</name> <name>ietf-interfaces</name>
<revision>2018-02-20</revision> <revision>2018-02-20</revision>
<namespace>\ <namespace>\
\urn:ietf:params:xml:ns:yang:ietf-interfaces\ \urn:ietf:params:xml:ns:yang:ietf-interfaces\
\</namespace> \</namespace>
</module> </module>
... ...
</module-set> </module-set>
... ...
</yang-library> </yang-library>]]></artwork>
]]></artwork> <t>Below is the equivalent of the above, but it was folded using the
</figure> script in <xref target="script"/>.</t>
<t>Below is the equivalent to the above, but it was folded using the <artwork name="example-3.2.txt.folded.rfcfold"><![CDATA[
script in the appendix.</t> ========== NOTE: '\\' line wrapping per RFC 8792 ==========
<figure>
<artwork><![CDATA[
========== NOTE: '\\' line wrapping per BCP XXX (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>
<name>config-modules</name> <name>config-modules</name>
<module> <module>
<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>]]></artwork>
]]></artwork>
</figure>
</section>
</section> </section>
</section>
<section title="Example Showing &quot;Forced&quot; Folding"> <section numbered="true" toc="default">
<t>This example illustrates how invalid sequences in lines that do not <name>Example Showing "Forced" Folding</name>
<t>This example illustrates how invalid sequences in lines that do not
have to be folded can be handled via forced folding, whereby the fol ding have to be folded can be handled via forced folding, whereby the fol ding
occurs even though unnecessary.</t> occurs even though unnecessary.</t>
<t>
<figure> <artwork name="example-4.txt" type="" align="left" alt=""><![CDATA[
<artwork><![CDATA[ The following line exceeds a 68-char max and, thus, demands folding:
The following line exceeds a 68-char max, thus demands folding
123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789
This line ends with a backslash \ This line ends with a backslash \
This line ends with a backslash \ This line ends with a backslash \
\ This line begins with a backslash \ This line begins with a backslash
Following is an indented 3x3 block of backslashes: The following is an indented 3x3 block of backslashes:
\\\
\\\ \\\
\\\ \\\
]]></artwork> \\\]]></artwork>
</figure> <t>The samples below were manually folded, since the script in the appen
</t> dix
<t>The samples below were manually folded, since the script in the app
endix
does not implement forced folding.</t> does not implement forced folding.</t>
<t>Note that the headers are prefixed by a pound ('#') character, rath <t>Note that the headers are prefixed by a pound ('#') character, rather
er than surrounded by 'equals' ('=') characters as shown in the script-
than surrounded by equal ('=') characters as shown in the script-gen generated
erated
examples.</t> examples.</t>
<section title="Using '\'"> <section numbered="true" toc="default">
<figure> <name>Using '\'</name>
<artwork><![CDATA[ <artwork name="example-4.1.txt.folded.forced" type="" align="left" alt
# NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =""><![CDATA[
# NOTE: '\' line wrapping per RFC 8792
The following line exceeds a 68-char max, thus demands folding The following line exceeds a 68-char max and, thus, demands folding:
1234567890123456789012345678901234567890123456789012345678901234567\ 1234567890123456789012345678901234567890123456789012345678901234567\
89 89
This line ends with a backslash \\ This line ends with a backslash \\
This line ends with a backslash \\ This line ends with a backslash \\
\ This line begins with a backslash \ This line begins with a backslash
Following is an indented 3x3 block of backslashes: The following is an indented 3x3 block of backslashes:
\\\\ \\\\
\\\\ \\\\
\\\ \\\]]></artwork>
]]></artwork> </section>
</figure> <section numbered="true" toc="default">
</section> <name>Using '\\'</name>
<section title="Using '\\'"> <artwork name="example-4.2.txt.folded.forced" type="" align="left" alt
<figure> =""><![CDATA[
<artwork><![CDATA[ # NOTE: '\\' line wrapping per RFC 8792
# NOTE: '\\' line wrapping per BCP XXX (RFC XXXX)
The following line exceeds a 68-char max, thus demands folding The following line exceeds a 68-char max and, thus, demands folding:
1234567890123456789012345678901234567890123456789012345678901234567\ 1234567890123456789012345678901234567890123456789012345678901234567\
\89 \89
This line ends with a backslash \ This line ends with a backslash \
This line ends with a backslash \\ This line ends with a backslash \\
\ \
\ This line begins with a backslash \ This line begins with a backslash
Following is an indented 3x3 block of backslashes: The following is an indented 3x3 block of backslashes:
\\\\ \\\\
\ \
\\\\ \\\\
\ \
\\\ \\\]]></artwork>
]]></artwork>
</figure>
</section>
</section> </section>
</section> </section>
</section>
<section title="Security Considerations" anchor="sec-cons"> <section anchor="sec-cons" numbered="true" toc="default">
<t>This BCP has no Security Considerations.</t> <name>Security Considerations</name>
</section> <t>This document has no security considerations.</t>
</section>
<section title="IANA Considerations" anchor="iana-cons"> <section anchor="iana-cons" numbered="true" toc="default">
<t>This BCP has no IANA Considerations.</t> <name>IANA Considerations</name>
</section> <t>This document has no IANA actions.</t>
</section>
</middle> </middle>
<back>
<back> <references>
<name>References</name>
<references title="Normative References"> <references>
<?rfc include="reference.RFC.2119.xml"?> <name>Normative References</name>
<?rfc include="reference.RFC.7991.xml"?> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.
<?rfc include="reference.RFC.8174.xml"?> xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7991.
xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.
xml"/>
</references> </references>
<references>
<references title="Informative References"> <name>Informative References</name>
<?rfc include="reference.RFC.7950.xml"?> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7950.
<?rfc include="reference.RFC.7749.xml"?> xml"/>
<?rfc include="reference.RFC.7994.xml"?> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7749.
<?rfc include="reference.RFC.8340.xml"?> xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7994.
xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8340.
xml"/>
<reference anchor="yang-doctors-thread" target="https://mailarchive.ietf .org/arch/msg/yang-doctors/DCfBqgfZPAD7afzeDFlQ1Xm2X3g"> <reference anchor="yang-doctors-thread" target="https://mailarchive.ietf .org/arch/msg/yang-doctors/DCfBqgfZPAD7afzeDFlQ1Xm2X3g">
<front> <front>
<title>[yang-doctors] automating yang doctor reviews</title> <title>[yang-doctors] automating yang doctor reviews</title>
<author/> <author initials="K" surname="Watsen" />
<date/> <date day="18" month="April" year="2018" />
</front> </front>
<refcontent>message to the yang-doctors mailing list</refcontent>
</reference> </reference>
<reference anchor="bash" target="https://www.gnu.org/software/bash/manua l"> <reference anchor="bash" target="https://www.gnu.org/software/bash/manua l">
<front><title>GNU Bash Manual</title><author/><date/></front> <front>
<title>GNU Bash Manual</title>
<author/>
</front>
</reference> </reference>
<reference anchor="xiax" target="https://pypi.org/project/xiax/"> <reference anchor="xiax" target="https://pypi.org/project/xiax/">
<front><title>The `xiax` Python Package</title><author/><date/></front <front>
> <title>The 'xiax' Python Package</title>
<author/>
</front>
</reference> </reference>
<reference anchor="pyang" target="https://pypi.org/project/pyang/"> <reference anchor="pyang" target="https://pypi.org/project/pyang/">
<front><title>An extensible YANG (RFC 6020/7950) validator.</title><au <front>
thor/><date/></front> <title>pyang</title>
<author/>
</front>
</reference> </reference>
<reference anchor="xml2rfc" target="https://pypi.org/project/xml2rfc/"> <reference anchor="xml2rfc" target="https://pypi.org/project/xml2rfc/">
<front><title>Xml2rfc generates RFCs and IETF drafts from document sou <front>
rce in XML according to the IETF xml2rfc v2 and v3 vocabularies.</title><author/ <title>xml2rfc</title>
><date/></front> <author/>
</front>
</reference> </reference>
<reference anchor="yanglint" target="https://github.com/CESNET/libyang#y anglint"> <reference anchor="yanglint" target="https://github.com/CESNET/libyang#y anglint">
<front><title>A feature-rich tool for validation and conversion of the <front>
schemas and YANG modeled data.</title><author/><date/></front> <title>yanglint</title>
<seriesInfo name="commit" value="1b7d73d"/>
<author/>
<date month="February" year="2020"/>
</front>
</reference> </reference>
</references> </references>
</references>
<!-- APPENDICIES --> <section anchor="script" numbered="true" toc="default">
<section title="Bash Shell Script: rfcfold" anchor="script"> <name>Bash Shell Script: rfcfold</name>
<t>This non-normative appendix section includes a Bash <xref target="bas <t>This non-normative appendix includes a Bash shell script <xref target="
h"/> shell script bash" format="default"/>
that can both fold and unfold text content using both the that can both fold and unfold text content using both the
single and double backslash strategies described in single and double backslash strategies described in Sections&nbsp;<xre
<xref target="single-slash"/> and <xref target="double-slash"/> f target="single-slash" format="counter"/> and <xref target="double-slash" forma
respectively.</t> t="counter"/>,
<t>This script is intended to be applied to a single text content respectively. This shell script, called 'rfcfold', is maintained at
<eref brackets="angle" target="https://github.com/ietf-tools/rfcfold"/>.</
t>
<t>This script is intended to be applied to a single text content
instance. If it is desired to fold or unfold text content instances instance. If it is desired to fold or unfold text content instances
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.</t> document before utilizing this script.</t>
<t>For readability purposes, this script forces the minimally <t>For readability purposes, this script forces the minimum
supported line length to be eight characters longer than the supported line length to be eight characters longer than the
raw header text defined in <xref target="single-header"/> and raw header text defined in Sections&nbsp;<xref target="single-header"
<xref target="double-header"/> so as to ensure that the header format="counter"/> and
can be wrapped by a space (' ') character and three equal ('=') <xref target="double-header" format="counter"/> so as to ensure that t
characters on each side of the raw header text.</t> he header
<t>When a TAB character is detected in the input file, this script can be wrapped by a space ('&nbsp;') character and three 'equals' ('='
exits with the error message:</t> )
<t> characters on each side of the raw header text.
<figure> </t>
<artwork><![CDATA[ <t>When a tab character is detected in the input file, this script
Error: infile contains a TAB character, which is not allowed. exits with the following error message:</t>
]]></artwork> <ul empty="true">
</figure> <li>Error: infile contains a tab character, which is not allowed.</li>
</t> </ul>
<t>This script tests for the availability of GNU awk (gawk), in <t>This script tests for the availability of GNU awk (gawk), in
order to test for ASCII-based control characters and non-ASCII order to test for ASCII-based control characters and non-ASCII
characters in the input file (see below). Note that testing characters in the input file (see below). Note that testing
revealed flaws in the default version of `awk` on some platforms. revealed flaws in the default version of 'awk' on some platforms.
As the use of `gawk` is only used to issue warning messages, As this script uses 'gawk' only to issue warning messages,
if `gawk` of not found, this script issues the debug message: if 'gawk' is not found, this script issues the following debug
</t> message:
<t> </t>
<figure> <ul empty="true">
<artwork><![CDATA[ <li>Debug: no GNU awk; skipping checks for special characters.</li>
Debug: no GNU Awk, skipping checks for special characters. </ul>
]]></artwork> <t>When 'gawk' is available (see above) and ASCII-based control
</figure>
</t>
<t>When `gawk` is available (see above) and ASCII-based control
characters are detected in the input file, this script issues characters are detected in the input file, this script issues
the warning message:</t> the following warning message:</t>
<t> <ul empty="true">
<figure> <li>Warning: infile contains ASCII control characters (unsupported).</li>
<artwork><![CDATA[ </ul>
Warning: infile contains ASCII control characters (unsupported). <t>When 'gawk' is available (see above) and non-ASCII characters
]]></artwork> are detected in the input file, this script issues the following warni
</figure> ng
</t>
<t>When `gawk` is available (see above) and non-ASCII characters
are detected in the input file, this script issues the warning
message:</t> message:</t>
<t> <ul empty="true">
<figure> <li>Warning: infile contains non-ASCII characters (unsupported).</li>
<artwork><![CDATA[ </ul>
Warning: infile contains non-ASCII characters (unsupported). <t>This script does not implement the whitespace-avoidance logic
]]></artwork> described in <xref target="single-folding" format="default"/>. In
</figure> such a case,
</t> the script will exit with the following error message:</t>
<t>This script does not implement the whitespace-avoidance logic
described in <xref target="single-folding"/>. In such case, <ul empty="true">
the script will exit with the following message:</t> <li>Error: infile has a space character occurring on the
<t>
<figure>
<artwork><![CDATA[
Error: infile has a space character occurring on the
folding column. This file cannot be folded using the folding column. This file cannot be folded using the
'\' strategy. '\' strategy.</li>
]]></artwork> </ul>
</figure> <t>While this script can unfold input that contains forced foldings,
</t>
<t>While this script can unfold input that contains forced foldings,
it is unable to fold files that would require forced foldings. Forced it is unable to fold files that would require forced foldings. Forced
folding is described in <xref target="single-folding"/> and folding is described in Sections&nbsp;<xref target="single-folding" fo
<xref target="double-folding"/>. When being asked to fold a file rmat="counter"/> and
<xref target="double-folding" format="counter"/>. When being asked to
fold a file
that would require forced folding, the script will instead exit that would require forced folding, the script will instead exit
with the following message:</t> with one of the following error messages:</t>
<t> <t>For '\':</t>
<figure> <ul empty="true">
<preamble>For '\':</preamble> <li>Error: infile has a line ending with a '\' character.
<artwork><![CDATA[
Error: infile has a line ending with a '\' character.
This file cannot be folded using the '\' strategy without This file cannot be folded using the '\' strategy without
there being false positives produced in the unfolding there being false positives produced in the unfolding
(i.e., this script does not force-fold such lines, as (i.e., this script does not force-fold such lines, as
described in BCP XXX, RFC XXXX). described in RFC 8792).</li>
]]></artwork> </ul>
</figure> <t>For '\\':</t>
</t> <ul empty="true">
<t> <li>Error: infile has a line ending with a '\' character
<figure>
<preamble>For '\\':</preamble>
<artwork><![CDATA[
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 the '\\' 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 force-fold such lines, as described script does not force-fold such lines, as described
in BCP XXX, RFC XXXX). in RFC 8792).
]]></artwork> </li>
</figure> </ul>
</t> <t>Shell-level end-of-line backslash ('\') characters have been
<t>Shell-level end-of-line backslash ('\') characters have been
purposely added to the script so as to ensure that the script is purposely added to the script so as to ensure that the script is
itself not folded in this document, thus simplifying the ability to itself not folded in this document, thus simplifying the ability to
copy/paste the script for local use. As should be evident by the copy/paste the script for local use. As should be evident by the
lack of the mandatory header described in <xref target="single-header" lack of the mandatory header described in <xref target="single-header"
/>, format="default"/>,
these backslashes do not designate a folded line, such as described these backslashes do not designate a folded line (e.g., as described
in <xref target="single-slash"/>.</t> in <xref target="single-slash" format="default"/>).</t>
<t> <sourcecode name="rfcfold" type="bash" markers="true"><![CDATA[
<figure>
<preamble>&lt;CODE BEGINS&gt;</preamble>
<artwork name="rfcfold"><![CDATA[
#!/bin/bash --posix #!/bin/bash --posix
# This script may need some adjustments to work on a given system. # This script may need some adjustments to work on a given system.
# For instance, the utility `gsed` may need to be installed. # For instance, the utility 'gsed' may need to be installed.
# Also, please be advised that `bash` (not `sh`) must be used. # Also, please be advised that 'bash' (not 'sh') must be used.
# Copyright (c) 2019 IETF Trust, Kent Watsen, and Erik Auerswald. # Copyright (c) 2020 IETF Trust, Kent Watsen, and Erik Auerswald.
# All rights reserved. # All rights reserved.
# #
# Redistribution and use in source and binary forms, with or without # Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions # modification, are permitted provided that the following conditions
# are met: # are met:
# #
# * Redistributions of source code must retain the above copyright # * Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer. # notice, this list of conditions and the following disclaimer.
# #
# * Redistributions in binary form must reproduce the above # * Redistributions in binary form must reproduce the above
skipping to change at line 938 skipping to change at line 887
# provided with the distribution. # provided with the distribution.
# #
# * Neither the name of Internet Society, IETF or IETF Trust, nor # * Neither the name of Internet Society, IETF or IETF Trust, nor
# the names of specific contributors, may be used to endorse or # the names of specific contributors, may be used to endorse or
# promote products derived from this software without specific # promote products derived from this software without specific
# prior written permission. # prior written permission.
# #
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, # COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) # STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
# ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
print_usage() { print_usage() {
printf "\n" printf "\n"
printf "Folds or unfolds the input text file according to BCP XXX" printf "Folds or unfolds the input text file according to"
printf " (RFC XXXX).\n" printf " RFC 8792.\n"
printf "\n" printf "\n"
printf "Usage: rfcfold [-h] [-d] [-q] [-s <strategy>] [-c <col>]" printf "Usage: rfcfold [-h] [-d] [-q] [-s <strategy>] [-c <col>]"
printf " [-r] -i <infile> -o <outfile>\n" printf " [-r] -i <infile> -o <outfile>\n"
printf "\n" printf "\n"
printf " -s: strategy to use, '1' or '2' (default: try 1," printf " -s: strategy to use, '1' or '2' (default: try 1,"
printf " else 2)\n" printf " else 2)\n"
printf " -c: column to fold on (default: 69)\n" printf " -c: column to fold on (default: 69)\n"
printf " -r: reverses the operation\n" printf " -r: reverses the operation\n"
printf " -i: the input filename\n" printf " -i: the input filename\n"
printf " -o: the output filename\n" printf " -o: the output filename\n"
skipping to change at line 979 skipping to change at line 928
# global vars, do not edit # global vars, do not edit
strategy=0 # auto strategy=0 # auto
debug=0 debug=0
quiet=0 quiet=0
reversed=0 reversed=0
infile="" infile=""
outfile="" outfile=""
maxcol=69 # default, may be overridden by param maxcol=69 # default, may be overridden by param
col_gvn=0 # maxcol overridden? col_gvn=0 # maxcol overridden?
hdr_txt_1="NOTE: '\\' line wrapping per BCP XXX (RFC XXXX)" hdr_txt_1="NOTE: '\\' line wrapping per RFC 8792"
hdr_txt_2="NOTE: '\\\\' line wrapping per BCP XXX (RFC XXXX)" hdr_txt_2="NOTE: '\\\\' line wrapping per RFC 8792"
equal_chars="=======================================================" equal_chars="======================================================="
space_chars=" " space_chars=" "
temp_dir="" temp_dir=""
prog_name='rfcfold' prog_name='rfcfold'
# functions for diagnostic messages # functions for diagnostic messages
prog_msg() { prog_msg() {
if [[ "$quiet" -eq 0 ]]; then if [[ "$quiet" -eq 0 ]]; then
format_string="${prog_name}: $1: %s\n" format_string="${prog_name}: $1: %s\n"
shift shift
skipping to change at line 1038 skipping to change at line 987
return 1 return 1
fi fi
# where to fold # where to fold
foldcol=$(expr "$maxcol" - 1) # for the inserted '\' char foldcol=$(expr "$maxcol" - 1) # for the inserted '\' char
# ensure input file doesn't contain whitespace on the fold column # ensure input file doesn't contain whitespace on the fold column
grep -q "^\(.\{$foldcol\}\)\{1,\} " "$infile" grep -q "^\(.\{$foldcol\}\)\{1,\} " "$infile"
if [[ $? -eq 0 ]]; then if [[ $? -eq 0 ]]; then
err "infile '$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"\ "folding column. This file cannot be folded using the"\
"'\\' strategy." "'\\' strategy."
return 1 return 1
fi fi
# center header text # center header text
length=$(expr ${#hdr_txt_1} + 2) length=$(expr ${#hdr_txt_1} + 2)
left_sp=$(expr \( "$maxcol" - "$length" \) / 2) left_sp=$(expr \( "$maxcol" - "$length" \) / 2)
right_sp=$(expr "$maxcol" - "$length" - "$left_sp") right_sp=$(expr "$maxcol" - "$length" - "$left_sp")
header=$(printf "%.*s %s %.*s" "$left_sp" "$equal_chars"\ header=$(printf "%.*s %s %.*s" "$left_sp" "$equal_chars"\
"$hdr_txt_1" "$right_sp" "$equal_chars") "$hdr_txt_1" "$right_sp" "$equal_chars")
skipping to change at line 1071 skipping to change at line 1020
fold_it_2() { fold_it_2() {
# where to fold # where to fold
foldcol=$(expr "$maxcol" - 1) # for the inserted '\' char foldcol=$(expr "$maxcol" - 1) # for the inserted '\' char
# ensure input file doesn't contain the fold-sequence already # ensure input file doesn't contain the fold-sequence already
if [[ -n "$("$SED" -n '/\\$/{N;s/\\\n[ ]*\\/&/p;D}' "$infile")" ]] if [[ -n "$("$SED" -n '/\\$/{N;s/\\\n[ ]*\\/&/p;D}' "$infile")" ]]
then then
err "infile '$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"\ "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 the '\\\\' strategy without there being"\
"false positives produced in the unfolding." "false positives produced in the unfolding."
return 1 return 1
fi fi
# center header text # center header text
length=$(expr ${#hdr_txt_2} + 2) length=$(expr ${#hdr_txt_2} + 2)
left_sp=$(expr \( "$maxcol" - "$length" \) / 2) left_sp=$(expr \( "$maxcol" - "$length" \) / 2)
right_sp=$(expr "$maxcol" - "$length" - "$left_sp") right_sp=$(expr "$maxcol" - "$length" - "$left_sp")
header=$(printf "%.*s %s %.*s" "$left_sp" "$equal_chars"\ header=$(printf "%.*s %s %.*s" "$left_sp" "$equal_chars"\
"$hdr_txt_2" "$right_sp" "$equal_chars") "$hdr_txt_2" "$right_sp" "$equal_chars")
skipping to change at line 1095 skipping to change at line 1044
echo "" >> "$outfile" echo "" >> "$outfile"
"$SED" 's/\(.\{'"$foldcol"'\}\)\(..\)/\1\\\n\\\2/;t M;b;:M;P;D;'\ "$SED" 's/\(.\{'"$foldcol"'\}\)\(..\)/\1\\\n\\\2/;t M;b;:M;P;D;'\
< "$infile" >> "$outfile" 2> /dev/null < "$infile" >> "$outfile" 2> /dev/null
if [[ $? -ne 0 ]]; then if [[ $? -ne 0 ]]; then
return 1 return 1
fi fi
return 0 return 0
} }
fold_it() { fold_it() {
# ensure input file doesn't contain a TAB # ensure input file doesn't contain a tab
grep -q $'\t' "$infile" grep -q $'\t' "$infile"
if [[ $? -eq 0 ]]; then if [[ $? -eq 0 ]]; then
err "infile '$infile' contains a TAB character, which is not"\ err "infile '$infile' contains a tab character, which is not"\
"allowed." "allowed."
return 1 return 1
fi fi
# folding of input containing ASCII control or non-ASCII characters # folding of input containing ASCII control or non-ASCII characters
# may result in a wrong folding column and is not supported # may result in a wrong folding column and is not supported
if type gawk > /dev/null 2>&1; then if type gawk > /dev/null 2>&1; then
env LC_ALL=C gawk '/[\000-\014\016-\037\177]/{exit 1}' "$infile"\ env LC_ALL=C gawk '/[\000-\014\016-\037\177]/{exit 1}' "$infile"\
|| warn "infile '$infile' contains ASCII control characters"\ || warn "infile '$infile' contains ASCII control characters"\
"(unsupported)." "(unsupported)."
env LC_ALL=C gawk '/[^\000-\177]/{exit 1}' "$infile"\ env LC_ALL=C gawk '/[^\000-\177]/{exit 1}' "$infile"\
|| warn "infile '$infile' contains non-ASCII characters"\ || warn "infile '$infile' contains non-ASCII characters"\
"(unsupported)." "(unsupported)."
else else
dbg "no GNU Awk, skipping checks for special characters." dbg "no GNU awk; skipping checks for special characters."
fi fi
# check if file needs folding # check if file needs folding
testcol=$(expr "$maxcol" + 1) testcol=$(expr "$maxcol" + 1)
grep -q ".\{$testcol\}" "$infile" grep -q ".\{$testcol\}" "$infile"
if [[ $? -ne 0 ]]; then if [[ $? -ne 0 ]]; then
dbg "nothing to do; copying infile to outfile." dbg "nothing to do; copying infile to outfile."
cp "$infile" "$outfile" cp "$infile" "$outfile"
return 255 return 255
fi fi
skipping to change at line 1139 skipping to change at line 1088
if [[ "$strategy" -eq 2 ]]; then if [[ "$strategy" -eq 2 ]]; then
fold_it_2 fold_it_2
return $? return $?
fi fi
quiet_sav="$quiet" quiet_sav="$quiet"
quiet=1 quiet=1
fold_it_1 fold_it_1
result=$? result=$?
quiet="$quiet_sav" quiet="$quiet_sav"
if [[ "$result" -ne 0 ]]; then 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 fold_it_2
return $? return $?
fi fi
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
skipping to change at line 1300 skipping to change at line 1249
if [[ "$reversed" -eq 0 ]]; then if [[ "$reversed" -eq 0 ]]; then
fold_it fold_it
code=$? code=$?
else else
unfold_it unfold_it
code=$? code=$?
fi fi
exit "$code" exit "$code"
} }
main "$@" main "$@"]]></sourcecode>
]]></artwork>
<postamble>&lt;CODE ENDS&gt;</postamble>
</figure>
</t>
</section>
<section title="Acknowledgements" numbered="no"> </section>
<t>The authors thank the RFC Editor for confirming that there was <section numbered="false" toc="default">
<name>Acknowledgements</name>
<t>The authors thank the RFC Editor for confirming that there was
previously no set convention, at the time of this document's publicati on, previously no set convention, at the time of this document's publicati on,
for handling long lines in source code inclusions, thus instigating th is for handling long lines in source code inclusions, thus instigating th is
work.</t> work.</t>
<t>The authors thank the following folks for their various
<t>The authors thank the following folks for their various
contributions while producing this document (sorted by first name): contributions while producing this document (sorted by first name):
Benoît Claise, <contact fullname="Ben Kaduk"/>,
Ben Kaduk, <contact fullname="Benoit Claise"/>,
Gianmarco Bruno, <contact fullname="Gianmarco Bruno"/>,
Italo Busi, <contact fullname="Italo Busi"/>,
Joel Jaeggli, <contact fullname="Joel Jaeggli"/>,
Jonathan Hansford, <contact fullname="Jonathan Hansford"/>,
Lou Berger, <contact fullname="Lou Berger"/>,
Martin Bjorklund, <contact fullname="Martin Bjorklund"/>,
and Rob Wilton.</t> and <contact fullname="Rob Wilton"/>.</t>
</section>
</section> </back>
</back>
</rfc> </rfc>
 End of changes. 156 change blocks. 
713 lines changed or deleted 667 lines changed or added

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