Re: [Cbor] 🔔 WGLC with request for reviews on cbor-cddl-control-03

Carsten Bormann <cabo@tzi.org> Sat, 17 July 2021 19:02 UTC

Return-Path: <cabo@tzi.org>
X-Original-To: cbor@ietfa.amsl.com
Delivered-To: cbor@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 1420F3A1C7A; Sat, 17 Jul 2021 12:02:46 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.899
X-Spam-Level:
X-Spam-Status: No, score=-1.899 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=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 mh4BOefdHSIT; Sat, 17 Jul 2021 12:02:41 -0700 (PDT)
Received: from gabriel-smtp.zfn.uni-bremen.de (smtp.uni-bremen.de [134.102.50.15]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id D58903A1C70; Sat, 17 Jul 2021 12:02:40 -0700 (PDT)
Received: from [192.168.217.118] (p548dcc89.dip0.t-ipconnect.de [84.141.204.137]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by gabriel-smtp.zfn.uni-bremen.de (Postfix) with ESMTPSA id 4GRyCy1lbrz2xLl; Sat, 17 Jul 2021 21:02:38 +0200 (CEST)
Content-Type: text/plain; charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.120.23.2.7\))
From: Carsten Bormann <cabo@tzi.org>
In-Reply-To: <1f4347d8-ea86-967e-57a6-6d4bb946d95c@sit.fraunhofer.de>
Date: Sat, 17 Jul 2021 21:02:37 +0200
Cc: =?utf-8?Q?Christian_Ams=C3=BCss?= <christian@amsuess.com>, cbor@ietf.org, draft-ietf-cbor-cddl-control@ietf.org
X-Mao-Original-Outgoing-Id: 648241357.745918-62b2eb543e4131a2ecefca07aca6f4e6
Content-Transfer-Encoding: quoted-printable
Message-Id: <4C823228-9903-4DB8-9F82-6BD26188328B@tzi.org>
References: <162257177227.3108.15057636687346300680@ietfa.amsl.com> <YLZ9s74sRa+ivAEe@hephaistos.amsuess.com> <1f4347d8-ea86-967e-57a6-6d4bb946d95c@sit.fraunhofer.de>
To: Henk Birkholz <henk.birkholz@sit.fraunhofer.de>
X-Mailer: Apple Mail (2.3608.120.23.2.7)
Archived-At: <https://mailarchive.ietf.org/arch/msg/cbor/AVX0JH05as-yFXokRE-phZKgvYY>
Subject: Re: [Cbor] =?utf-8?q?=F0=9F=94=94_WGLC_with_request_for_reviews_on_c?= =?utf-8?q?bor-cddl-control-03?=
X-BeenThere: cbor@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: "Concise Binary Object Representation \(CBOR\)" <cbor.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/cbor>, <mailto:cbor-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/cbor/>
List-Post: <mailto:cbor@ietf.org>
List-Help: <mailto:cbor-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/cbor>, <mailto:cbor-request@ietf.org?subject=subscribe>
X-List-Received-Date: Sat, 17 Jul 2021 19:02:46 -0000

Hi Henk,

Thank you for this review.

I’m preparing an updated version of cddl-control for post-WGLC processing.

> The document is structured well and comes with excellent readability. The table up-front provides a concise overview and is providing the basis for the following expositional text and IANA Considerations. Table 1 also indicates two variants of ABNF encoding that is supported. That simply could have been included in earlier text as .det is also listed next to .cat, but that is not a really a problem for the reader.

Table 1 is pretty early (like after the second sentence); is there another “earlier text” that should say this?
Section 3 does introduce both .abnf/.abnfb.

>  .det is an okay name. I would have also really been okay with .dedcat.

(There is a little note there why .det was ultimately chosen…)

> .det already prepares the reader for the embedded ABNF control .abnf. As some of the implication for implementers are not trivial, this section provides a chunk load of context info and details the issues. .abnfb is a bit hidden in the section, but as it is listed in the table up-front that is effectively not a problem.

Right, the flow of the exposition means that .abnfb is only introduced in earnest in the first bullet point.  Introducing more of its details earlier could increase confusion, so I kept the intro short.

> NIT: It is highlighted in Section 2.3 how .det is useful to .abnfb, yet in Section 3 the context in the itemized list only illustrates .cat in the expositional text. The example shows how this all comes together, though, using quite intuitive type names. Maybe quickly reiterate the purpose of .det here in the text before the example so implementers that are looking that up finds all they need in the text itself.

I actually interchanged the use .cat and .det in Figure 4, now that .det is both-handed.  A simpler example that is not employing RFC 5234 boilerplate would just use .det, but I’m not sure that another example really would add much.  I also added .det to the end of the last bullet item.

> Feature is written relatively abstract and was the hardest for me to find intuitive. The examples also take a bit more thinking. Feature is relative abstract by intent. As I would not know how to frame it better, this is a good solution.

Indeed, it is a very general tool, and a specification writer needs to make up their mind how to use it.  draft-ietf-asdf-sdf at least shows one way.

> NIT: To simplify the layout of the map in Figure 5, maybe a consistent use of "=>" instead of mixing ":" and "=>" might be easier for readers? Maybe it is okay to show that they can be mixed here, but might cause more confusion than necessary

They not only “can”, but the line 

  * (text .feature "further-person-extension") => any

really does need the =>
Of course, we could translate all the other
foo:
into
“foo” => 

but that would be a somewhat unnatural use of CDDL.

Specification writers that are at the stage where they need .feature probably should have mastered : vs. => already.

> NIT: I am not a huge fan of "remains to be seen" conjecture in RFC text, but well, it's true, so it is probably useful to readers.

I also think that indicating that there is room for the spec writer’s own thinking is a good direction to take here.

Changes, together with the ones based on my comments (which I’m not going to reply to about how much I agree with them :-) are in

https://github.com/cbor-wg/cddl-control/pull/7
https://cbor-wg.github.io/cddl-control/
(Weird, the latter should be the wglc branch besides the main branch.)

(Don’t forget to `gem update cddl` to play around with the both-handed .det.)

Grüße, Carsten