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

Qin Wu <bill.wu@huawei.com> Thu, 28 June 2018 01:21 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 23569130EC9 for <netmod@ietfa.amsl.com>; Wed, 27 Jun 2018 18:21:51 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.2
X-Spam-Level:
X-Spam-Status: No, score=-4.2 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=unavailable 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 Wm4jLCLxRAde for <netmod@ietfa.amsl.com>; Wed, 27 Jun 2018 18:21:49 -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 C2D1F130EC8 for <netmod@ietf.org>; Wed, 27 Jun 2018 18:21:48 -0700 (PDT)
Received: from LHREML712-CAH.china.huawei.com (unknown [172.18.7.106]) by Forcepoint Email with ESMTP id D924537CD4CE6 for <netmod@ietf.org>; Thu, 28 Jun 2018 02:21:44 +0100 (IST)
Received: from NKGEML413-HUB.china.huawei.com (10.98.56.74) by LHREML712-CAH.china.huawei.com (10.201.108.35) with Microsoft SMTP Server (TLS) id 14.3.382.0; Thu, 28 Jun 2018 02:21:45 +0100
Received: from NKGEML513-MBX.china.huawei.com ([169.254.1.193]) by NKGEML413-HUB.china.huawei.com ([10.98.56.74]) with mapi id 14.03.0382.000; Thu, 28 Jun 2018 09:21:40 +0800
From: Qin Wu <bill.wu@huawei.com>
To: Kent Watsen <kwatsen@juniper.net>, Robert Wilton <rwilton=40cisco.com@dmarc.ietf.org>, "netmod@ietf.org" <netmod@ietf.org>
Thread-Topic: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04
Thread-Index: AQHUCpK0us9UwwoDtU2EaBoFZiTowKRza3iAgADuLYCAAIw7EA==
Date: Thu, 28 Jun 2018 01:21:40 +0000
Message-ID: <B8F9A780D330094D99AF023C5877DABA9AEB9BE8@nkgeml513-mbx.china.huawei.com>
References: <B8F9A780D330094D99AF023C5877DABA9AEB4274@nkgeml513-mbx.china.huawei.com> <194df0e3-038d-d0cc-ea45-f5448fc10562@cisco.com> <70F6E49F-C83F-4C38-92CB-860631B4C050@juniper.net>
In-Reply-To: <70F6E49F-C83F-4C38-92CB-860631B4C050@juniper.net>
Accept-Language: zh-CN, en-US
Content-Language: zh-CN
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
x-originating-ip: [10.134.30.132]
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/SrMwF_7EBsY0zijtXM1VQGxny0k>
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: Thu, 28 Jun 2018 01:21:51 -0000

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

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,

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

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



> 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



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:

 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

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

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

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

> Rob

Kent // contributor