[Matroska-devel] EBML specification component for review - About this Document

Dave Rice dave at dericed.com
Thu Apr 30 06:20:33 CEST 2015

> On Apr 28, 2015, at 10:17 PM, Erik Piil <piil.erik at GMAIL.COM> wrote:
> This discussion relates to the "About this Document" portion of the earlier EBML RFC Draft for revision/incorporation into the final EBML specification. 
> From the RFC Draft:
> About this Document
> This document is currently in its draft stage and is subject to changes. The contents should not be relied upon for implementational purposes.  

Although the RFC draft was in draft stage, the EBML specification at matroska-org.github.io/libebml/ isn’t. I suggest not moving this to the EBML spec.

> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. 

RFC2119 is decent boilerplate for this type of specification. Though the use of these terms in the EBML specification is fairly low: 1 shall, 1 should, and 2 may.

In all cases the RFC2119 meaning seems appropriate. For instance for "All level 1 elements should include a CRC-32” should in RFC2119 terms means RECOMMENDED which sounds about right since it’s rare that I see EBML with CRCs in this way, but it ‘should’ happen.

> The definitions in this document uses ABNF [ABNF]. Note that string terminals are case insensitive in ABNF. The interpretation of binary values has been slightly altered so that every bit must be explicitly printed, e.g. %b0 is one zero bit while %b000 represents three zero bits. The following (re)definitions are used throughout this document: 
> BIT  = %b1 / %b0
> WSP  = SP / HTAB / CR / LF

This section on ABNF expression appears in the RFC draft and the resulting expressions are used recurrently in the draft, but the EBML specs don’t include this. In part these seems to be because what the RFC draft expresses in ABNF is expressed in the EBML spec via an HTML table. For the purposes of submitting an EBML spec to the IETF I can see why Martin rewrote much of this in ABNF to meet the usual RFC formatting, but for reviewing the specification I prefer the table view of the EBML spec. Perhaps there does need to be two concurrent versions of the spec, one formal for IETF and one for pretty web display.

Any preference for how to deal with this? I like the specdata.xml approach where one document is used to generate outputs for different purposes.

For this one, here’s a proposal:
I can draft a patch to add the RFC2119 boilerplate to the specification.
I can start an issue to review the spec for other opportunities to use terminology from the RFC2119 definition in order to add clarity.
Start an issue to move the EBML elements into an xml form (like specdata.xml) and generate a process to convert it to the html of the spec page and the ABNF form for the RFC.

Dave Rice
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.matroska.org/pipermail/matroska-devel/attachments/20150430/ee245a24/attachment.html>

More information about the Matroska-devel mailing list