Re: [Cbor] John Scudder's No Objection on draft-ietf-cbor-file-magic-11: (with COMMENT)

[Carsten Bormann <[e-mail]>]

Hi John,

thank you for this review.

Michael already pointed out that some of your comments have been addressed in our collection of proposed changes in response to previously submitted IESG comments:

https://github.com/cbor-wg/cbor-magic-number/pull/21

I also have made a small new commit at

https://github.com/cbor-wg/cbor-magic-number/pull/21/commits/cf1f41a
with items that were not yet covered.

Grüße, Carsten


> The document, along with other ballot positions, can be found here:
> https://datatracker.ietf.org/doc/draft-ietf-cbor-file-magic/
> 
> 
> 
> ----------------------------------------------------------------------
> COMMENT:
> ----------------------------------------------------------------------
> 
> Thanks for this document. It seems useful, and the core specification
> part in Section 2 is clear and understandable.

Thank you.

> That said, it could be even friendlier to someone approaching it as a
> CBOR n00b. I don't think that's a major concern, because I can’t
> imagine why someone other than a hapless IESG member would approach this
> document cold, without some reasonable background in CBOR. Still, if you
> want an example of what I'm talking about, the casual "so that there are
> no leading zeroes" in Section 2.1, with no whys or wherefores, felt a
> bit like a scavenger hunt.

This was meant to become clear from the next sentence; I now have clarified this sentence a bit.

> I also agree with a number of Lars's comments (in particular, what's a...
> disk? Some technology from the 1900s?). Also Zahed's suggestion to move
> Section 3 to an appendix.

Already addressed, except for moving Section 3 to an appendix — doing that surgery would disturb the diffs right now, but I’ll keep it on the list of potential final changes.

> Finally, while I am quibbling about style, I thought the trips down
> memory lane and visits to sites of software grievances of Christmas
> Past in Sections 1 and 3 slowed down the read without adding insight.

I think we already have cleaned this up a bit.
More generally speaking maybe my teaching background shows through too much when I say that this kind of background information can be very useful to a new reader.  (Can be — but if a reader knows all this, they can skim this quickly.)

I take this input as an encouragement to make more use of structuring in future specifications, e.g. moving small pieces of material like this into <aside> blocks.

> Finally, I do have one specific comment on where the text is unclear in
> Section 2.2:
> 
>   A CBOR Protocol specification may specify the use of two tags only
>   for specific cases.  For instance, it might use them when storing the
>   representation in a local file or for Web access, but not when using
>   them in protocol messages that already provide the necessary context.
> 
> The first sentence reads like a prohibition on specification of two tags
> for general cases. (I don't know what that would mean, it's just a
> straightforward way to parse it. "May" combined with "only" is
> the difficult bit I think.) If your meaning is what I think it is,
> substituting "might" for "may" would fix it.

This paragraph really is a continuation of the previous paragraph, which has been clarified based on the previous comments.
So I merged the two paragraphs in the new commit.
(Michael may have ideas how to further improve this.)

> But in the final analysis, the fact that all I've got is quibbles is
> evidence of a job well done, thank you. :-)

Thank you!