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

Robert Wilton <rwilton@cisco.com> Thu, 28 June 2018 16:43 UTC

Return-Path: <rwilton@cisco.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 0E205130E1F for <netmod@ietfa.amsl.com>; Thu, 28 Jun 2018 09:43:09 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -14.51
X-Spam-Level:
X-Spam-Status: No, score=-14.51 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_HI=-5, SPF_PASS=-0.001, T_DKIMWL_WL_MED=-0.01, URIBL_BLOCKED=0.001, USER_IN_DEF_DKIM_WL=-7.5] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=cisco.com
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 SFdIQ84LQ-gp for <netmod@ietfa.amsl.com>; Thu, 28 Jun 2018 09:43:07 -0700 (PDT)
Received: from aer-iport-1.cisco.com (aer-iport-1.cisco.com [173.38.203.51]) (using TLSv1.2 with cipher DHE-RSA-SEED-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id CB6B3130DF0 for <netmod@ietf.org>; Thu, 28 Jun 2018 09:43:06 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=6864; q=dns/txt; s=iport; t=1530204187; x=1531413787; h=subject:to:references:from:message-id:date:mime-version: in-reply-to:content-transfer-encoding; bh=pZim98o/6g0flr/9Qopb1LgdM/vtOaRfL1k9DZSaK+c=; b=G3bD0rsULlwtf0H+Vl8iC8N4gPZXkdjU2J/+GCiHSwP0PCBFircgFUlI pemgI9x/sPV4CYrvtf63AlEoYHUW6wR/GTUd0c6RE7EyPJwUUz+vuoNIk jEQtl5WHxCi9cRYL0RDdTq7B1PSuXkRtLPDH6cc3L0I1f53cp3QXi5JjD s=;
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: =?us-ascii?q?A0CiAQAaDzVb/xbLJq1dGQEBAQEBAQE?= =?us-ascii?q?BAQEBAQcBAQEBAYMfgQxtEoQhiGONPAgilTKBZgsjhEkCgzs4FAECAQECAQE?= =?us-ascii?q?CbRwMhTYBAQEBAgEdBg8BBUYLCw4KAgImAgJXBgEMCAEBF4MFAYF3CA+tJYI?= =?us-ascii?q?chFuDeIEXBYELiTg/gQ8nDIJcgSiBcAEBA4FFGIMBglUChz6SAAmGAokOBoF?= =?us-ascii?q?Ahk0khRyKK4F/hU+BWCGBUjMaCBsVgyWCSmkBAodchT8+kQoBAQ?=
X-IronPort-AV: E=Sophos;i="5.51,284,1526342400"; d="scan'208";a="4846781"
Received: from aer-iport-nat.cisco.com (HELO aer-core-1.cisco.com) ([173.38.203.22]) by aer-iport-1.cisco.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 28 Jun 2018 16:43:04 +0000
Received: from [10.63.23.83] (dhcp-ensft1-uk-vla370-10-63-23-83.cisco.com [10.63.23.83]) by aer-core-1.cisco.com (8.14.5/8.14.5) with ESMTP id w5SGh4bY029099; Thu, 28 Jun 2018 16:43:04 GMT
To: Kent Watsen <kwatsen@juniper.net>, Qin Wu <bill.wu@huawei.com>, "netmod@ietf.org" <netmod@ietf.org>
References: <B8F9A780D330094D99AF023C5877DABA9AEB4274@nkgeml513-mbx.china.huawei.com> <194df0e3-038d-d0cc-ea45-f5448fc10562@cisco.com> <70F6E49F-C83F-4C38-92CB-860631B4C050@juniper.net>
From: Robert Wilton <rwilton@cisco.com>
Message-ID: <a427f30c-1011-78a8-7f08-a625603739ca@cisco.com>
Date: Thu, 28 Jun 2018 17:43:04 +0100
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.8.0
MIME-Version: 1.0
In-Reply-To: <70F6E49F-C83F-4C38-92CB-860631B4C050@juniper.net>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Content-Language: en-US
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/r9jNjdvkHcHnLTHckB6VBseRjwQ>
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 16:43:10 -0000

Hi Kent,


On 28/06/2018 01:53, Kent Watsen wrote:
> 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".
OK, thanks.
>
>
>
>> 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 ;)
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
> 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.   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.
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)
           |     |  +--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


>
>> Rob
> Kent // contributor
>
>
>