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

Kent Watsen <kwatsen@juniper.net> Thu, 28 June 2018 00:53 UTC

Return-Path: <kwatsen@juniper.net>
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 18467130E5C for <netmod@ietfa.amsl.com>; Wed, 27 Jun 2018 17:53:49 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.7
X-Spam-Level:
X-Spam-Status: No, score=-2.7 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_LOW=-0.7, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=unavailable autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=juniper.net
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 oZCG-bl5cXKY for <netmod@ietfa.amsl.com>; Wed, 27 Jun 2018 17:53:47 -0700 (PDT)
Received: from mx0b-00273201.pphosted.com (mx0b-00273201.pphosted.com [67.231.152.164]) (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 CD703130E57 for <netmod@ietf.org>; Wed, 27 Jun 2018 17:53:47 -0700 (PDT)
Received: from pps.filterd (m0108163.ppops.net [127.0.0.1]) by mx0b-00273201.pphosted.com (8.16.0.22/8.16.0.22) with SMTP id w5S0k6hG006009; Wed, 27 Jun 2018 17:53:41 -0700
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=juniper.net; h=from : to : subject : date : message-id : references : in-reply-to : content-type : content-id : content-transfer-encoding : mime-version; s=PPS1017; bh=FLRPPBuh+iwo3qSDK3MYGoYil8e2g5+yJKOXgwemhog=; b=1/qX4R0a0Eny9SMZ5FOrk4zPUuH9pXMZq2Aajp8HubtM4SVgNNIYZd9poJ99cjL20jFr mYKg/PN6qkQ/xNRg2C8y76XPRRtSucnMN48lfw7CM4gV/RiAQDxiuf+ZJrQXxuMZCIT9 bRDFSBO8NjutFS6bmQl2IVvNQxazWpVxnvOwP1VD7/StDGvInX/KNrpu+q7rxjqZf9uo kqliscQVoNyQIr52S1+cHHtJsaXw/Ign9QACX10yzgoUpoeSZseeMUnPIDB+dPWOCMPf bNBT8m3UVf/4lIQ8FAolDiYzvc3z+ICVI6HWyOEcl2CF4XcsWjg8njiYPLkx7w+4Jkmt Jw==
Received: from nam02-sn1-obe.outbound.protection.outlook.com (mail-sn1nam02lp0020.outbound.protection.outlook.com [216.32.180.20]) by mx0b-00273201.pphosted.com with ESMTP id 2jvn7y00y1-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-SHA384 bits=256 verify=NOT); Wed, 27 Jun 2018 17:53:40 -0700
Received: from BYAPR05MB4230.namprd05.prod.outlook.com (52.135.200.153) by BYAPR05MB4133.namprd05.prod.outlook.com (52.135.199.154) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.906.15; Thu, 28 Jun 2018 00:53:39 +0000
Received: from BYAPR05MB4230.namprd05.prod.outlook.com ([fe80::959d:9fbe:90e4:3cc]) by BYAPR05MB4230.namprd05.prod.outlook.com ([fe80::959d:9fbe:90e4:3cc%4]) with mapi id 15.20.0906.018; Thu, 28 Jun 2018 00:53:39 +0000
From: Kent Watsen <kwatsen@juniper.net>
To: Robert Wilton <rwilton=40cisco.com@dmarc.ietf.org>, Qin Wu <bill.wu@huawei.com>, "netmod@ietf.org" <netmod@ietf.org>
Thread-Topic: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04
Thread-Index: AQHUCpK0us9UwwoDtU2EaBoFZiTowKRz8ZSAgACrHgA=
Date: Thu, 28 Jun 2018 00:53:39 +0000
Message-ID: <70F6E49F-C83F-4C38-92CB-860631B4C050@juniper.net>
References: <B8F9A780D330094D99AF023C5877DABA9AEB4274@nkgeml513-mbx.china.huawei.com> <194df0e3-038d-d0cc-ea45-f5448fc10562@cisco.com>
In-Reply-To: <194df0e3-038d-d0cc-ea45-f5448fc10562@cisco.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
user-agent: Microsoft-MacOutlook/f.20.0.170309
x-originating-ip: [66.129.241.10]
x-ms-publictraffictype: Email
x-microsoft-exchange-diagnostics: 1; BYAPR05MB4133; 7:A7HPvHp4EgxUzFxn6iXhEjhwQYbhCkUV5o/OZxivX8J5MgH5rPyjwZ5ge/LMF0uc4hCeO2CE6S5bG3Vc1HvlVfoU5pWhI8124ET4On7niJs9bHNB1jJlKtkhbIziBud0hIpilFoVOQz+we00P7m+BgJt0BjS+Va4bWiCeIeMzmPwRJ1oUWl3WNeertOQ5Z3DflGYKg3rM7ZR2P8ZCUhV+8OrRb+4vtWIc+ruJpSNN3pQxtHNxorGWe8m648PN60d
x-ms-exchange-antispam-srfa-diagnostics: SOS;
x-ms-office365-filtering-correlation-id: 38b53cb6-f951-4bf7-f3d7-08d5dc919650
x-ms-office365-filtering-ht: Tenant
x-microsoft-antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652034)(8989117)(4534165)(4627221)(201703031133081)(201702281549075)(8990107)(5600026)(711020)(48565401081)(2017052603328)(7153060)(7193020); SRVR:BYAPR05MB4133;
x-ms-traffictypediagnostic: BYAPR05MB4133:
x-microsoft-antispam-prvs: <BYAPR05MB4133E75DDD1ECEEC2D6DC78AA54F0@BYAPR05MB4133.namprd05.prod.outlook.com>
x-exchange-antispam-report-test: UriScan:;
x-ms-exchange-senderadcheck: 1
x-exchange-antispam-report-cfa-test: BCL:0; PCL:0; RULEID:(8211001083)(6040522)(2401047)(5005006)(8121501046)(3002001)(3231254)(944501410)(52105095)(10201501046)(93006095)(93001095)(6055026)(149027)(150027)(6041310)(20161123558120)(20161123560045)(20161123562045)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(20161123564045)(6072148)(201708071742011)(7699016); SRVR:BYAPR05MB4133; BCL:0; PCL:0; RULEID:; SRVR:BYAPR05MB4133;
x-forefront-prvs: 0717E25089
x-forefront-antispam-report: SFV:NSPM; SFS:(10019020)(346002)(136003)(376002)(366004)(39860400002)(396003)(189003)(199004)(51444003)(53936002)(86362001)(316002)(966005)(6486002)(81166006)(36756003)(81156014)(8676002)(105586002)(6246003)(14454004)(25786009)(106356001)(58126008)(478600001)(68736007)(6116002)(3846002)(256004)(6306002)(5250100002)(5660300001)(6436002)(8936002)(83716003)(6512007)(33656002)(2616005)(66066001)(7736002)(229853002)(305945005)(186003)(2906002)(2900100001)(102836004)(76176011)(11346002)(97736004)(446003)(6506007)(6346003)(26005)(2501003)(82746002)(476003)(110136005)(99286004)(486006); DIR:OUT; SFP:1102; SCL:1; SRVR:BYAPR05MB4133; H:BYAPR05MB4230.namprd05.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; MX:1; A:1;
received-spf: None (protection.outlook.com: juniper.net does not designate permitted sender hosts)
x-microsoft-antispam-message-info: 9+GA0JmryPA0ug1A6mMF3nj67GO6gpqRZoJ0c9b3ZXq+BMvcrKaXPiCye5ubwAfopKVshTy2rCnkBJXrGrdYiHU2joSxfPyRJxBnflkmK1jsg9j593yFOgLWQjf7FMFKeBEKNfC74PyqaACEMcLLobRyGGqCTc66Glhv8V6Tr9FHf34aoq7bWyXm6iZMCwiAtxkOsOQFNtof3+Aqqr9og5posPyjIP2/FVDm9T/MQhsLbulQdfHK6Xi1xYDKNcQJ1dvCy99Cn/7QEDekhVWdHp/e6GUa2FMJypilHxOIo2VCiXgTCptzXUdasyPDeZwtiTmmiUOi/yi3Edd84fhI2U8i2ycQ40lrj74SrAcpCNs=
spamdiagnosticoutput: 1:99
spamdiagnosticmetadata: NSPM
Content-Type: text/plain; charset="utf-8"
Content-ID: <6AA15AB4E3D08D4E8F359CB3951F7F36@namprd05.prod.outlook.com>
Content-Transfer-Encoding: base64
MIME-Version: 1.0
X-OriginatorOrg: juniper.net
X-MS-Exchange-CrossTenant-Network-Message-Id: 38b53cb6-f951-4bf7-f3d7-08d5dc919650
X-MS-Exchange-CrossTenant-originalarrivaltime: 28 Jun 2018 00:53:39.1738 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: bea78b3c-4cdb-4130-854a-1d193232e5f4
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BYAPR05MB4133
X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2018-06-27_07:, , signatures=0
X-Proofpoint-Spam-Details: rule=outbound_spam_notspam policy=outbound_spam score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1806210000 definitions=main-1806280007
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/HK6c0GQ40PLshVTl-K_5zUOsrSo>
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 00:53:49 -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,

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


> Rob

Kent // contributor