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

Qin Wu <bill.wu@huawei.com> Wed, 27 June 2018 04:01 UTC

Return-Path: <bill.wu@huawei.com>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id AFBA8130E10 for <netmod@ietfa.amsl.com>; Tue, 26 Jun 2018 21:01:45 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.201
X-Spam-Level:
X-Spam-Status: No, score=-4.201 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id h4NoINZA_Egu for <netmod@ietfa.amsl.com>; Tue, 26 Jun 2018 21:01:43 -0700 (PDT)
Received: from huawei.com (lhrrgout.huawei.com [194.213.3.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 15D9F12785F for <netmod@ietf.org>; Tue, 26 Jun 2018 21:01:43 -0700 (PDT)
Received: from lhreml704-cah.china.huawei.com (unknown [172.18.7.107]) by Forcepoint Email with ESMTP id 94AE066C9EF40 for <netmod@ietf.org>; Wed, 27 Jun 2018 05:01:39 +0100 (IST)
Received: from NKGEML412-HUB.china.huawei.com (10.98.56.73) by lhreml704-cah.china.huawei.com (10.201.108.45) with Microsoft SMTP Server (TLS) id 14.3.382.0; Wed, 27 Jun 2018 05:01:40 +0100
Received: from NKGEML513-MBX.china.huawei.com ([169.254.1.193]) by nkgeml412-hub.china.huawei.com ([10.98.56.73]) with mapi id 14.03.0382.000; Wed, 27 Jun 2018 12:01:32 +0800
From: Qin Wu <bill.wu@huawei.com>
To: Kent Watsen <kwatsen@juniper.net>, Martin Bjorklund <mbj@tail-f.com>
CC: "netmod@ietf.org" <netmod@ietf.org>
Thread-Topic: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04
Thread-Index: AQHUCpK0us9UwwoDtU2EaBoFZiTowKRx1OgAgAB01oCAABo9gIAAB6+AgAEP9uA=
Date: Wed, 27 Jun 2018 04:01:32 +0000
Message-ID: <B8F9A780D330094D99AF023C5877DABA9AEB8C4E@nkgeml513-mbx.china.huawei.com>
References: <B8F9A780D330094D99AF023C5877DABA9AEB4274@nkgeml513-mbx.china.huawei.com> <20180626.122602.1952551623315308243.mbj@tail-f.com> <34C78C9F-57A9-4234-8F30-39F69F0B2F04@juniper.net> <20180626.205807.1642470222068426969.mbj@tail-f.com> <21CFADF6-9FB8-4B0B-A7FC-517FDDAF6F8C@juniper.net>
In-Reply-To: <21CFADF6-9FB8-4B0B-A7FC-517FDDAF6F8C@juniper.net>
Accept-Language: zh-CN, en-US
Content-Language: zh-CN
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
x-originating-ip: [10.138.33.244]
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: base64
MIME-Version: 1.0
X-CFilter-Loop: Reflected
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/feB_uAUel3T39c7bkZ8QOQw1Up4>
Subject: Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.26
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 27 Jun 2018 04:01:46 -0000

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




> (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?


See below for more comments.

[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).
>> 
>> 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.
>
> Hmm, I thought it had variable-length indentation.

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

[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.
>
> I like the algorithm in the other draft better - it had variable 
> placement of the line break ("\\n" sequence), and variable 
> indentation.

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.


> 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.


>> >>   - 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.
>> >
>> > 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.
>> 
>> 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).
>
> 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?


>> >> 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.
>> 
>> 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:
>
>  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 '='.

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?



> But if we adopt the algorithm in the other draft, we don't need a 
> 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.

> /martin

Kent