Subject: [Cellar] Early comment from an early review of draft-ietf-cellar-ebml-09

From: Robert Sparks <[email-masked]>
Date: Wed, 13 Feb 2019 14:25:50 -0600

I have received a genart early review assignment (disguised as a lc 
review assignment) for draft-ietf-cellar-ebml-09.

I have started reading the draft - it will take some time to absorb it 
and provide a review.

I wanted to get one editorial comment in early: the use of double-quotes 
to try to bound/emphasize names of things in this document is 
significantly damaging my ability to read it. They are unnecessary. 
Please just remove them.

    "VINT_MARKER" use one out of every eight bits of the total length of
    the "Variable Size Integer".  Thus a "Variable Size Integer" of 1
    octet length supplies 7 bits for "VINT_DATA", a 2 octet length
    supplies 14 bits for "VINT_DATA", and a 3 octet length supplies 21
    bits for "VINT_DATA".

is much harder to read than

    VINT_MARKER use one out of every eight bits of the total length of
    the Variable Size Integer.  Thus a Variable Size Integer of 1
    octet length supplies 7 bits for VINT_DATA, a 2 octet length
    supplies 14 bits for VINT_DATA, and a 3 octet length supplies 21
    bits for VINT_DATA.

In what I've read so far, I haven't found a place where removing the 
double-quotes would introduce any ambiguity.

RjS

ps. On a trivia/humor note - this draft is currently 2.73% 
double-quotes. The average for the entire RFC series is 0.26% double-quotes.

---

From: Steve Lhomme <[email-masked]>
Date: Sun, 17 Feb 2019 15:04:52 +0100

Hello Robert,

I agree with this. I think this is because we write the specs in
Markdown and then translate to text/HTML. In Markdown we use `` around
the names and it just changes the background. It seems when translated
to text it's transformed into double quotes. I will investigate if
there's a way to change this or either remove the `` altogether.

Thanks a lot

Le mer. 13 févr. 2019 à 21:25, Robert Sparks <[email-masked]> a écrit :
>
> I have received a genart early review assignment (disguised as a lc review assignment) for draft-ietf-cellar-ebml-09.
>
> I have started reading the draft - it will take some time to absorb it and provide a review.
>
> I wanted to get one editorial comment in early: the use of double-quotes to try to bound/emphasize names of things in this document is significantly damaging my ability to read it. They are unnecessary. Please just remove them.
>
> In what I've read so far, I haven't found a place where removing the double-quotes would introduce any ambiguity.
>
> RjS
>
> ps. On a trivia/humor note - this draft is currently 2.73% double-quotes. The average for the entire RFC series is 0.26% double-quotes.
>
> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar

-- 
Steve Lhomme
Matroska association Chairman