Subject: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04

From: Qin Wu <[email-masked]>
Date: Sat, 23 Jun 2018 01:37:11 +0000

Dear WG,

As you may recall I presented yang-xml-doc-conventions in London.  There was strong support for trying to solve the problem and mixed views on the solution, other than that we should do it fast.  In the meanwhile, Kent submitted artwork-folding as an alternative solution.

The authors of the two drafts decided to combine efforts.  After several internal iterations on both drafts, the drafts were becoming more alike than different(both support auto wrapping or auto folding).  The artwork-folding draft was selected as a preferred offering basis (i.e., draft-kwatsen-netmod-artwork-folding-04) to the working group to consider for adoption.

The primary feature differences remained are:
  - all folded lines continue of column 0 without two character indentation, i.e., whether auto indentation should be supported.
  - handle two special case on backslash and space at the end of broken line in yang-xml-doc-conventions.
  - propose to use <WRAPPED TEXT BEGIN><WRAPPED TEXT END> to extract artwork from I-Ds.

Thanks,
Qin, Kent, Benoit and Adrian
-----邮件原件-----
发件人: [email-masked] [mailto:[email-masked]] 
发送时间: 2018年6月23日 9:33
收件人: Benoit Claise; Qin Wu; Kent Watsen; Adrian Farrel; Benoît Claise
主题: New Version Notification for draft-kwatsen-netmod-artwork-folding-04.txt

A new version of I-D, draft-kwatsen-netmod-artwork-folding-04.txt
has been successfully submitted by Qin Wu and posted to the IETF repository.

Name:		draft-kwatsen-netmod-artwork-folding
Revision:	04
Title:		Handling Long Lines in Artwork in Drafts
Document date:	2018-06-22
Group:		Individual Submission
Pages:		9
URL:            https://www.ietf.org/internet-drafts/draft-kwatsen-netmod-artwork-folding-04.txt
Status:         https://datatracker.ietf.org/doc/draft-kwatsen-netmod-artwork-folding/
Htmlized:       https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-04
Htmlized:       https://datatracker.ietf.org/doc/html/draft-kwatsen-netmod-artwork-folding
Diff:           https://www.ietf.org/rfcdiff?url2=draft-kwatsen-netmod-artwork-folding-04

Abstract:
   This document introduces a simple and yet time-proven strategy for
   handling long lines in artwork in drafts using a backslash ('\')
   character where line-folding has occurred.  The strategy works on any
   text based artwork, producing consistent results regardless the
   artwork content.  Using a per-artwork header, the strategy is both
   self-documenting and enables automated reconstitution of the original
   artwork.

Please note that it may take a couple of minutes from the time of submission until the htmlized version and diff are available at tools.ietf.org.

The IETF Secretariat

---

From: joel jaeggli <[email-masked]>
Date: Sat, 23 Jun 2018 21:33:26 -0700

I support this.

thanks

joel

On 6/22/18 6:37 PM, Qin Wu wrote:
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 26 Jun 2018 12:26:02 +0200 (CEST)

Hi,

I support this work.   See below for some comments.

Qin Wu <[email-masked]> wrote:
> Dear WG,
> 
> As you may recall I presented yang-xml-doc-conventions in London.
> There was strong support for trying to solve the problem and mixed
> views on the solution, other than that we should do it fast.  In the
> meanwhile, Kent submitted artwork-folding as an alternative solution.
> 
> The authors of the two drafts decided to combine efforts.  After
> several internal iterations on both drafts, the drafts were becoming
> more alike than different(both support auto wrapping or auto folding).
> The artwork-folding draft was selected as a preferred offering basis
> (i.e., draft-kwatsen-netmod-artwork-folding-04) to the working group
> to consider for adoption.
> 
>   - all folded lines continue of column 0 without two character
>     indentation, i.e., whether auto indentation should be supported.

I really liked the flexible indentation in the other draft.  I suggest
it is added to this draft.  It enhances readability (if the author
wants it).

>   - propose to use <WRAPPED TEXT BEGIN><WRAPPED TEXT END> to extract

The artwork draft proposes only a header, which means that it is not
quite clear where the artwork ends.

In the artwork draft, section 5.3, you write:

   This line is self-describing in
   three ways: use of '\' character, identification of BCP/RFC, and
   identification of what the maximum line length is for the artwork.

I was confused about this maximum line length; it seems you define the
maximum line length ot be 53, but that seems too limiting, and indeed
in the example in 5.4 the max line length is 69.  (BTW, the example is
missing in the draft, as is the shell script in Appendix A).   In any
case, I don't see how the header identifies the max line length.

Also, in section 5.2, the first sentence is:

  Scan the artwork to see if any line exceeds the desired maximum.

But what is the desired maximum?   I assume that the idea is that the
author first selects a desired max?  Maybe add a line that explains
this, and again write that 69 is a reasonable value for use in I-Ds
and RFCs.

/martin

> 主题: New Version Notification for
> draft-kwatsen-netmod-artwork-folding-04.txt
> 
> 
> URL:
> https://www.ietf.org/internet-drafts/draft-kwatsen-netmod-artwork-folding-04.txt
> Status:
> https://datatracker.ietf.org/doc/draft-kwatsen-netmod-artwork-folding/
> Htmlized:
> https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-04
> Htmlized:
> https://datatracker.ietf.org/doc/html/draft-kwatsen-netmod-artwork-folding
> Diff:
> https://www.ietf.org/rfcdiff?url2=draft-kwatsen-netmod-artwork-folding-04
> 
> Abstract:
> Please note that it may take a couple of minutes from the time of
> submission until the htmlized version and diff are available at
> tools.ietf.org.
> 
> The IETF Secretariat
>

---

From: Kent Watsen <[email-masked]>
Date: Tue, 26 Jun 2018 17:24:13 +0000

Hi Martin,

First, I just posted -05 to address the missing artwork:
https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-05.

See below for more comments.

Kent // contributor

===== original message =====

> it is added to this draft.  It enhances readability (if the author

Variable indentation, when the folded-line starts on same column as
the previous line, looks nice.  The current yang-xml-doc-conventions
draft has a fixed two-space indent, which would only look nice sometimes 
while introducing a surprise factor other times.

Variable indent introduces significant complexity; at least, it's beyond
what can be accomplished by a `sed` one-liner, such as in the current 
draft.  A fixed two-space indent is possible (easy), but zero-space 
indent is more common (less surprising) than a fixed indent.

> quite clear where the artwork ends.

Interesting point, but I think that artwork-framing is a different problem
from artwork-folding.  If the goal is to support extracting artwork from
txt-based RFC scripts, regardless if the artwork is folded or not, then we
could level-up this draft to that role, while still supporting folding.

If we were to add a footer, maybe something like this:

  ===padding=== End Folding per BCP XX (RFC XXXX) ===padding===

where the "padding" fills in '=' characters until the max-line width is
reached (same as how the header is done).

> case, I don't see how the header identifies the max line length.

The draft says that the *minimal* header string is 53-characters).  We
can make it less if needed, but it involves needing to fold the header
itself, which could become messy.  Thoughts?

Per the line just before the one quoted above, this line is '=' padded
on both sides until reaching the max value.  Apparently, this isn't 
clear enough in the text, or do you think it's okay now?

For what it's worth, I originally had the actually fold-column 
(e.g., 69) printed in the header, but it was realized that it was 
noise to the reader (humans don't care about the fold column number),
whereas padding the line out provides visually meaningful information
(e.g., one can hover the cursor over the end and then scroll the
document to find all the folds).

> this, and again write that 69 is a reasonable value for use in I-Ds

Right, the idea is that the author has a target fold-column in mind.
It's an input parameter to the script in the appendix.  The max value
defaults to 69.

I added the following sentence before the "scan" line above:

   Determine the desired maximum line length from input.  If no
   value is explicitly specified, the value "69" SHOULD be used.

> /martin

Kent // contributor

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 26 Jun 2018 20:58:07 +0200 (CEST)

> https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-05.

Thanks!

(The exmaples with just a string of '\' are highy confusing.  Unclear
what they try to tell me... probably that the alg is much more
difficult than I originally thought ;-)

> while introducing a surprise factor other times.

Hmm, I thought it had variable-length indentation.

> indent is more common (less surprising) than a fixed indent.

I like the algorithm in the other draft better - it had variable
placement of the line break ("\\n" sequence), and variable
indentation.

Note that your proposed format is just a special case of the format in
the other draft, so you can still use your "one-liner" sed to produce
your result.

> reached (same as how the header is done).

Ok.

> clear enough in the text, or do you think it's okay now?

The draft says:

  The header is two lines long.

  The first line is the following 53-character string

This is what made me confused.  I now understand that the idea is to pad
with '='.

But if we adopt the algorithm in the other draft, we don't need a
maximum line length like this.

/martin

---

From: Kent Watsen <[email-masked]>
Date: Tue, 26 Jun 2018 19:25:37 +0000

> difficult than I originally thought ;-)

Those are torture tests, but they due illustrate the one case where having
the '\\n' on the fold column would've been illegal input (and hence the '\'
was replaced with a 'x').  Great for internal algorithm validation, but
perhaps unnecessary for the example in the text.  Or maybe enhance the
comments above these lines to explain why they're there?

> Hmm, I thought it had variable-length indentation.

It was, but removed later, I think from WG comments.   Qin may know more.

> placement of the line break ("\\n" sequence), and variable

How can you automated variable placement of the line-break, assuming no
awareness of the file format?  Additionally, be aware that variable '\n'
placement would necessitate pre-scanning the file to ensure *no* line
ends in a '\\n', as opposed to just the lines that need folding.

> the other draft, so you can still use your "one-liner" sed to produce

True.

>> reached (same as how the header is done).

I assume that you're okay-ing the proposed footer, but the real question is
if we should expand the scope of this draft to include artwork-framing also?

> This is what made me confused.  I now understand that the idea is to pad

Right, the full sentence is:

   The first line is the following 53-character string that has been
   padded with roughly equal numbers of equal ('=') characters to reach
   the artwork's maximum line length.

So, leave as is for now?

> maximum line length like this.

There still needs to be a maximum line length, whether it's identified
in the header could be discussed.

> /martin

Kent

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 26 Jun 2018 22:08:07 +0200 (CEST)

> comments above these lines to explain why they're there?

I suggest you remove this.

> ends in a '\\n', as opposed to just the lines that need folding.

I envision this format being used not just by a program, but also by
humans trying to construct nice looking examples.

Also, I would prefer a description of the format, rather than of one
algorithm that produces the format.

> if we should expand the scope of this draft to include artwork-framing also?

I think I would prefer if there is also a footer.

>    the artwork's maximum line length.

Well ... I don't think this text is even correct...  The section
describes the header with the first line being 53 characters.  But
that is just an example.  Maybe:

    The first line is an N-character string on the following form:

    === NOTE: '\' line wrapping per BCP XX (RFC XXXX) ===

    where N is the artwork's maximum length (the minimum length is
    53).  The string is padded with roughly equal numbers of equal
    ('=') characters in the beginning and end to reach the artwork's
    maximum line length.

... but as I wrote, I'd prefer a variable-length format.

/martin

---

From: Qin Wu <[email-masked]>
Date: Wed, 27 Jun 2018 04:01:32 +0000

-----邮件原件-----
发件人: Kent Watsen [mailto:[email-masked]] 
发送时间: 2018年6月27日 3:26
收件人: Martin Bjorklund
抄送: Qin Wu; [email-masked]
主题: Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04

> difficult than I originally thought ;-)

Those are torture tests, but they due illustrate the one case where having the '\\n' on the fold column would've been illegal input (and hence the '\'
was replaced with a 'x').  Great for internal algorithm validation, but perhaps unnecessary for the example in the text.  Or maybe enhance the comments above these lines to explain why they're there?

[Qin]: In draft-wu-netmod-yang-xml-doc-conventions-05, if we face a line of backslash or space, we will treat them in the same ways as normal characters in auto wrapping process,
But in auto unwrapping process, we will remove them all and make rule as follows:
"
     In extreme case, if a backslash character ("\") or space character
      appears full of line, the full line of backslash character ("\")
      or space character should be stripped.

"

>>> I really liked the flexible indentation in the other draft.  I 
>>> suggest it is added to this draft.  It enhances readability (if the 
>>> author wants it).
>> 
>> draft has a fixed two-space indent, which would only look nice 
>> sometimes while introducing a surprise factor other times.
>

[Qin]: Yes, it was removed in draft-wu-netmod-yang-xml-doc-conventions based on Charles's comment. 
In v-05, we change indentation rule as follows based on additional comments received from offline:
"
   o  Any continuation lines or new line MUST align with the first line
      and MAY chose be indented with two whitespace offset for
      readability purposes.
"
But in the python script of the appendix, we support variable-length indentation by using indent (text, prefix, predicate=None).
The prefix can be set to variable length characters.

>> Variable indent introduces significant complexity; at least, it's 
>> beyond what can be accomplished by a `sed` one-liner, such as in the 
>> current draft.  A fixed two-space indent is possible (easy), but 
>> zero-space indent is more common (less surprising) than a fixed indent.
>

How can you automated variable placement of the line-break, assuming no awareness of the file format?  Additionally, be aware that variable '\n'
placement would necessitate pre-scanning the file to ensure *no* line ends in a '\\n', as opposed to just the lines that need folding.

[Qin]: auto wrap proposed in draft-wu-netmod-yang-xml-doc-conventions support variable placement of the line-break and doesn't need to be aware of the file format.
Since we define textwrap.fill(eachline,max-line-length) in the python script.
We also can deal with special case such as line ends in a '\\n' or in a ' \n',etc.

True.

>> > The artwork draft proposes only a header, which means that it is 
>> > not quite clear where the artwork ends.
>> 
>> Interesting point, but I think that artwork-framing is a different 
>> problem from artwork-folding.  If the goal is to support extracting 
>> artwork from txt-based RFC scripts, regardless if the artwork is 
>> folded or not, then we could level-up this draft to that role, while still supporting folding.
>> 
>> where the "padding" fills in '=' characters until the max-line width 
>> is reached (same as how the header is done).
>
> Ok.

I assume that you're okay-ing the proposed footer, but the real question is if we should expand the scope of this draft to include artwork-framing also?

>> > I was confused about this maximum line length; it seems you define 
>> > the maximum line length ot be 53, but that seems too limiting, and 
>> > indeed in the example in 5.4 the max line length is 69.  (BTW, the example is
>> The draft says that the *minimal* header string is 53-characters).  
>> We can make it less if needed, but it involves needing to fold the 
>> header itself, which could become messy.  Thoughts?
>> 
>> Per the line just before the one quoted above, this line is '=' 
>> padded on both sides until reaching the max value.  Apparently, this 
>> isn't clear enough in the text, or do you think it's okay now?
>
> The draft says:
>
> This is what made me confused.  I now understand that the idea is to 
> pad with '='.

So, leave as is for now?

> maximum line length like this.

There still needs to be a maximum line length, whether it's identified in the header could be discussed.

[Qin]: In script of draft-wu-netmod-yang-xml-doc-conventions-05, we allow user to set maximum line 
length value as he like.

Kent

---

From: Qin Wu <[email-masked]>
Date: Wed, 27 Jun 2018 04:07:05 +0000

-----邮件原件-----
发件人: Martin Bjorklund [mailto:[email-masked]] 
发送时间: 2018年6月27日 4:08
收件人: [email-masked]
抄送: Qin Wu; [email-masked]
主题: Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04

Kent Watsen <[email-masked]> wrote:
> 
> 
> 
> > (The exmaples with just a string of '\' are highy confusing.  
> > Unclear what they try to tell me... probably that the alg is much 
> > more difficult than I originally thought ;-)
> 
> Those are torture tests, but they due illustrate the one case where 
> having the '\\n' on the fold column would've been illegal input (and hence the '\'
> was replaced with a 'x').  Great for internal algorithm validation, 
> but perhaps unnecessary for the example in the text.  Or maybe enhance 
> the comments above these lines to explain why they're there?

> >>> suggest it is added to this draft.  It enhances readability (if 
> >>> the author wants it).
> >> 
> >> the previous line, looks nice.  The current 
> >> yang-xml-doc-conventions draft has a fixed two-space indent, which 
> >> would only look nice sometimes while introducing a surprise factor other times.
> >
> >> beyond what can be accomplished by a `sed` one-liner, such as in 
> >> the current draft.  A fixed two-space indent is possible (easy), 
> >> but zero-space indent is more common (less surprising) than a fixed indent.
> >
> How can you automated variable placement of the line-break, assuming 
> no awareness of the file format?  Additionally, be aware that variable '\n'

I envision this format being used not just by a program, but also by humans trying to construct nice looking examples.

Also, I would prefer a description of the format, rather than of one algorithm that produces the format.

[Qin]: Tend to agree with this.

> > Note that your proposed format is just a special case of the format 
> > in the other draft, so you can still use your "one-liner" sed to 
> > produce your result.
> 
> True.
> 
> 
> >> where the "padding" fills in '=' characters until the max-line 
> >> width is reached (same as how the header is done).
> >
> > Ok.
> 
> I assume that you're okay-ing the proposed footer, but the real 
> question is if we should expand the scope of this draft to include artwork-framing also?

> >> > I was confused about this maximum line length; it seems you 
> >> > define the maximum line length ot be 53, but that seems too 
> >> > limiting, and indeed in the example in 5.4 the max line length is 69.  (BTW, the example is
> >> padded on both sides until reaching the max value.  Apparently, 
> >> this isn't clear enough in the text, or do you think it's okay now?
> >
> > The draft says:
> >

Well ... I don't think this text is even correct...  The section describes the header with the first line being 53 characters.  But that is just an example.  Maybe:

[Qin]: Good, Variable-length format can be supported by the script provided by draft-wu-netmod-yang-xml-doc-conventions-05.

/martin

---

From: Robert Wilton <[email-masked]>
Date: Wed, 27 Jun 2018 11:41:11 +0100

Support/adopt.

A couple of comments:

1) Section 4.2 suggests using groupings to presumably avoid folding.  I 
don't really support this as a strategy, since I think that groupings 
are overused and I think that they obfuscate the true structure of a 
YANG module, that can only be recovered by recompiling the module with 
the groupings expanded, or looking at the tree output.  Really, I think 
that an ideal solution would be to somehow have RFCs support longer 
lines for files like YANG - e.g. if I could choose any value without 
regard for backwards compatibility I would probably choose 120 
characters instead.

2) The proposed solution always left indents the wrapped line. Often for 
artwork (e.g. a YANG tree diagram), where whitespace is not significant, 
and the wrapping is relatively minor, then right indenting the wrapped 
line can make the results look more visually readable.

E.g.  I think that this is slightly easier to read:

module: ietf-flexible-encapsulation
   augment /if:interfaces/if:interface/if-cmn:encapsulation\
                                         /if-cmn:encaps-type:
     +--:(flexible)
        +--rw flexible
           +--rw match
           |  +--rw (match-type)
           |     +--:(default)
           |     |  +--rw default?                 empty
           |     +--:(untagged)
           |     |  +--rw untagged?                empty
           |     +--:(dot1q-priority-tagged)
           |     |  +--rw dot1q-priority-tagged
           |     |     +--rw tag-type?   dot1q-types:dot1q-\
                                                    tag-type
           |     +--:(dot1q-vlan-tagged)
           |        +--rw dot1q-vlan-tagged

rather than:

module: ietf-flexible-encapsulation
   augment /if:interfaces/if:interface/if-cmn:encapsulation\
/if-cmn:encaps-type:
     +--:(flexible)
        +--rw flexible
           +--rw match
           |  +--rw (match-type)
           |     +--:(default)
           |     |  +--rw default?                 empty
           |     +--:(untagged)
           |     |  +--rw untagged?                empty
           |     +--:(dot1q-priority-tagged)
           |     |  +--rw dot1q-priority-tagged
           |     |     +--rw tag-type?   dot1q-types:dot1q-\
tag-type
           |     +--:(dot1q-vlan-tagged)
           |        +--rw dot1q-vlan-tagged

Thanks,
Rob

---

From: Kent Watsen <[email-masked]>
Date: Wed, 27 Jun 2018 17:15:46 +0000

> I suggest you remove this.

Okay.

> humans trying to construct nice looking examples.

I really hope humans don't try to do this manually, as the results are 
error-prone, and it isn't consistent with the goal of integrating validation
in the build scripts that compile the drafts, for which automated-folding
is needed (see section 3.1).  I'm not saying that manual-folding shouldn't
be possible, I'm saying that it is ill-advised, and we shouldn't go out of
our way to support it.  I do not support variable placement of the 
line-break.

[Note: indentation of the beginning of the line is a different issue, and
one that I actually support, assuming it is easily automatable]

> algorithm that produces the format.

Okay, we will look into it.

> I think I would prefer if there is also a footer.

Why?  Do you propose the same for all artwork, regardless if it's been folded
or not?  To me, these are different issues.

>    ('=') characters in the beginning and end to reach the artwork's

Yes, this is better

> ... but as I wrote, I'd prefer a variable-length format.

Understood, being discussed above.

Kent // contributor

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 27 Jun 2018 22:43:11 +0200 (CEST)

Kent Watsen <[email-masked]> wrote:
> is needed (see section 3.1).

I disagree.  I often use my own markup in example files so that I can
validate the examples with tools, and then run a script that turns the
markup into newlines (in the future: '\' + newline).

For example:

           <namespace><!-- PPL -->urn:ietf:params:xml:ns:yang:ietf-yang-types</namespace>

turns into:

           <namespace>\
             urn:ietf:params:xml:ns:yang:ietf-yang-types
           </namespace>

(the <!-- PPL --> is my own markup).

Compare with

             <namespace>urn:ietf:params:xml:ns:yang:ietf-yang-types</n\
             amespace>

Not sure if this qualifies as "manual folding" or not.

> I'm not saying that manual-folding shouldn't
> our way to support it.

I don't think it is difficult to support variable placement of the
linebreak.   It is already specified in the other draft.

> I do not support variable placement of the 
> line-break.
> 

Hmm, good point.  Maybe ignore for now.

/martin

---

From: Kent Watsen <[email-masked]>
Date: Thu, 28 Jun 2018 00:53:39 +0000

All, I just posted -06 that addresses some comments from Rob, Martin,
and Jonathan.  I realize that there are still open issues, but a rapid
iteration for some of these things seems like it might be good:
https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-06.

Hi Robert,

> regard for backwards compatibility I would probably choose 120 

I removed the word "grouping" from the text.  Now it says "...call outs,
such as functions".

>           |        +--rw dot1q-vlan-tagged

The placement of the indents in the example above would be impossible
to automate - they're too artsy ;)   However, it should be possible 
to automate a variable indent that lines up with the first printable
character on the previous line.  Something like this:

[note: previous line indent matching is beyond what can be accomplished
via a simple `sed` or `awk` one-liner]. 

Regardless if automated or manual, I think the indent rule needs to be
rather strict.  In particular, arbitrary per-line indent can lead to
lossy round-tripping (unfolding errors), unless we introduce a rule
saying that the source artwork MUST NOT have a space (' ') character
that occurring on a fold column.  Otherwise the following might happen.

  ORIG:

     example:
        This very long line happens to have a space character immediately after the fold column.";

  FOLDED:  *** doesn't matter the indentation strategy ***

     ===== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =====
     example:
        This very long line happens to have a space character\
        immediately after the fold column.";

  UNFOLDED (using alg that chomps all leading whitespace):

     example:
        This very long line happens to have a space characterimmediately after the fold column.";

Note the error in the unfolded version.  I think disallowing
whitespace characters on the fold column in the source artwork is
overly limiting, spaces being so commonly used.   The only way I 
can think to preserve the space character is to have a fixed 
indent rule (e.g., some hardcoded column number, or always use 
the same indent as previous line, or the same as the previous 
line plus some fixed offset).  Given a clear rule, the unfolding
alg can chomp just the right amount of whitespace out, leaving
the any remaining whitespace, so the round-trip result is loss-less.

Kent // contributor

---

From: Qin Wu <[email-masked]>
Date: Thu, 28 Jun 2018 01:21:40 +0000

-----邮件原件-----
发件人: Kent Watsen [mailto:[email-masked]] 
发送时间: 2018年6月28日 8:54
收件人: Robert Wilton; Qin Wu; [email-masked]
主题: Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04

Hi Robert,

  ORIG:

     example:

     example:

Note the error in the unfolded version.  I think disallowing
whitespace characters on the fold column in the source artwork is
overly limiting, spaces being so commonly used.   

[Qin]: we can handle whitespace at any position and any line using code proposed in another draft.
Unfolded text will not be distorted by the whitespace in the above example.

The only way I 

[Qin]: Agree with Kent, this is exactly what we proposed in another draft, i.e., add fixed indentation, which doesn't require tool to understand the artwork format.
add left indentation or right indentation seems to indicate the tool must understand the format of artwork and may introduce a lot of complexity.

Kent // contributor

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 28 Jun 2018 08:08:13 +0200 (CEST)

> overly limiting, spaces being so commonly used.

But with variable placement of the '\' character you can do:

        This very long line happens to have a space character \
        immediately after the fold column.";

or

        This very long line happens to have a space \
        character immediately after the fold column.";

so I'm not sure that disallowing space at the fold column is a
problem.

Note that even with this, your original "one-liner sed" still produces
valid results, so if you just want a simple folding program you can
use that.

/martin

---

From: Bob Harold <[email-masked]>
Date: Thu, 28 Jun 2018 09:42:36 -0400

> valid results, so if you just want a simple folding program you can

The problem is that this does not work in cases where there are a lot of
spaces - particularly where there are more than 'line-length' spaces in a
row, in the middle of the line.

-- 
Bob Harold

---

From: Kent Watsen <[email-masked]>
Date: Thu, 28 Jun 2018 15:11:40 +0000

>>        immediately after the fold column.";

This would not work, since the line is one character too long

>>        character immediately after the fold column.";

This is legal, but is in the realm of manual-folding, or "semi-manual
folding", for what you do with your preprocessing-scripts.

>> valid results, so if you just want a simple folding program you can

True.  We could define a feature-rich format, for which the existing
script only-supports a lowest common denominator.  From a folding
perspective, that might be okay, but from an unfolding perspective,
it could not be used to unfold any folded-artwork, and so I'd push
to fix the script to unfold any input.

>> The problem is that this does not work in cases where there are a 
>> lot of spaces - particularly where there are more than 'line-length'
>> spaces in a row, in the middle of the line.

Right, so if the input was something like an empty table row:

       +------------------+------------------+-----------------+------etc.
       |                  |                  |                 |

Or a snippet of a UML diagram where the line is a 100% blank:

                                                                      etc.

Allowing arbitrary per-line indent makes decoding these cases ambiguous.

If the goal is to have a pair or rules like:

  1. Any line ending with "\\n" is considered folded, regardless of the column.
  2. The original/source artwork MUST NOT have any lines ending with '\' char.

which would support your semi-manual folding scripts, I think it is possible
(TBD), but it would entail having a fixed indent rule (e.g., some hardcoded
column number, or always use the same indent as previous line, or always use
the same indent as the previous line plus some fixed offset).  Given a clear
rule, the unfolding alg can chomp just the right amount of whitespace out,
leaving any remaining whitespace, for a loss-less decode.

Alternatively, we can have arbitrary per-line indent, but then we need to 
have a fixed fold-column, or assert that the source artwork has no whitespace
where the fold begins, which means blank lines could never be supported.  This
was mentioned above also.

PS: Regarding Rob's desire for 120-char line lengths, I forgot to mention
before that the current I-D doesn't specify a maximum.  It only says that
69 is the default, and 53 is the minimum, so 120 is fine.

Kent // contributor

---

From: Robert Wilton <[email-masked]>
Date: Thu, 28 Jun 2018 17:43:04 +0100

Hi Kent,

> I removed the word "grouping" from the text.  Now it says "...call outs,
OK, thanks.
> to automate - they're too artsy ;)
They are just right indented, so it is pretty easy to figure out?  E.g. 
start at  (Max line length - number of wrapped chars)

>     However, it should be possible
There other ways to solve this, at a slight increase in complexity.

E.g. You could use two marker characters, e.g. as below, where 
everything between and including the two '\' characters is stripped.  
Simple folding tools could just put the second '\' at the beginning of 
the next line, or at a fixed column,  more sophisticated tools could put 
more effort into making it more readable, but still preserve the ability 
to get the exact source back out again.

           |     |  +--rw default?                 empty
           |     +--:(untagged)
                                                   \tag-type

Thanks,
Rob

---

From: Kent Watsen <[email-masked]>
Date: Thu, 28 Jun 2018 23:03:00 +0000

Hi Robert,

> start at  (Max line length - number of wrapped chars)

My bad, I didn't catch that they were right-indented before.  Hmmmm, 
interesting idea, worth keeping in mind.  I see how it produces good
results sometimes, but it also seems like it could produce some results
that are not as good as indenting to the first whitespace character
from the previous line.

>           |        +--rw dot1q-vlan-tagged

Clever!  Having both seems to resolve many issues, and it might be within
reach of a `sed` one-liner again.  The only issue might be readability,
since it's so different than the time-aged convention...

Kent // contributor

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 29 Jun 2018 10:16:32 +0200 (CEST)

> Allowing arbitrary per-line indent makes decoding these cases ambiguous.

Yes, but is this really a problem?  I don't think it would be a good
idea to take a very width ascii-table and fold it like this - the
point of having a ascii table is to make the data easy to read; that
won't be the case if the table is folded.

IMO the problem we want to solve is folding when there is no
alternative.  E.g., XML or JSON snippets with long identifier names,
source code snippets etc.

/martin

---

From: Robert Wilton <[email-masked]>
Date: Fri, 29 Jun 2018 10:15:56 +0100

> that are not as good as indenting to the first whitespace character
Sure, that decision on how to intend the wrapped line could be down to 
the tool that is performing the folding, perhaps predicated by user 
input or the type of diagram that is being folded.

E.g. I agreed with Martin's comments that it is better to specify the 
required behavior rather than describe a specific algorithm on how it is 
constructed.

> since it's so different than the time-aged convention...
Only one thin character different ;-)

Perhaps it could be the start of a new convention that is a bit more 
flexible, explicit, and robust ...

Rob