Subject: [Gen-art] Genart last call review of draft-ietf-cbor-array-tags-07

From: Elwyn Davies via Datatracker <[email-masked]>
Date: Fri, 06 Sep 2019 12:33:39 -0700

Reviewer: Elwyn Davies
Review result: Ready with Nits

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<https://trac.ietf.org/trac/gen/wiki/GenArtfaq>.

Document: draft-ietf-cbor-array-tags-07
Reviewer: Elwyn Davies
Review Date: 2019-09-06
IETF LC End Date: 2019-09-05
IESG Telechat date: Not scheduled for a telechat

Summary:
Ready with a couple of nits.  Apologies for slightly late delivery.

Major issues:
None

Minor issues:
None

Nits/editorial comments:
s1, para 2: s/have received/has received/

s1, para 3: s/This also can/This can also/

s1.1, last para: s/whether that/as to whether that/

s2.1, 2nd para after Table 2 (top of page 5):
OLD:
     It can be computed
     inversely to the previous formula from the length of the byte string
     in bytes: "bytelength >> (f + ll)".
NEW:
     It can be computed from the length of the byte string comprising the
     representation of the array by inverting the previous formula: "bytelength
     >> (f + ll)".
ENDS

s2.1: The terms endianness, big endian and litle endian are jargon, if pretty
well known jargon, but I don't know if they are considered to be adequately
well understood to avoid the need for a reference or  an explanation of what is
meant.

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 25 Sep 2019 16:55:09 +0200

Hi Elwyn,

thank you for these comments.
These are now addressed in the editor’s copy on github, specifically in
https://github.com/cbor-wg/array-tags/commit/f63c0301c481ab773c16b96a9b0eb63456554049
Details below.

> On Sep 6, 2019, at 21:33, Elwyn Davies via Datatracker <[email-masked]> wrote:
> 
> Reviewer: Elwyn Davies

I put these in (oops, missed one, now in https://github.com/cbor-wg/array-tags/commit/4490e8b6f9f157779783f645c2c4ee6f9e749f74 ).

>      representation of the array by inverting the previous formula: "bytelength

This misses the “in bytes”, which may be obvious to many, but should be said.
Now:

It can be
computed from the length, in bytes, of the byte string comprising the
representation of the array by inverting the previous formula:
`bytelength >> (f + ll)`.

> well understood to avoid the need for a reference or  an explanation of what is

Very good point; we sometimes get too mired in our jargon.

Now at the end of the terminology section:

The terms "big endian" and "little endian" are used to indicate a most
significant byte first (MSB first) representation of integers, and a
least significant byte first (LSB first) representation, respectively.

I think we can tolerate the one occurrence of “endianness” before that, as that is just in a list of examples.

Grüße, Carsten