Re: EBML specification component for review - About this Document

> On May 1, 2015, at 6:05 AM, Moritz Bunkus <[email protected]> wrote:
> 
> Hey,
> 
>> 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.
> 
> This reminds me: what is our goal? Currently we have two documents. For
> me the goal is to come out of this process with only one document
> superseding the older two. While RFCs may not be the easiest things to
> read for human beings they are the de-facto standard for technical
> specification in the internet.

We have two, but I think one (the spec now in github pages) can be updated and the RFC draft deprecated.

> Therefore I think our goal should be: create an EBML RFC, remove the two
> older documents.

For transparency, I suggest marking the older drafts clearer as superseded by a new spec, but not to outright remove them.

> So »moving to the EBML spec« is not something I would suggest in general
> anyway – unless the EBML spec is the one document we want to bring into
> proper RFC shape.

I think that's the goal. Though I'm talking about making a new RFC spec from http://matroska-org.github.io/libebml/ not from the RFC draft. Though we're presently evaluating what from the RFC draft should be considered in that process.

> Just to be clear what we are talking about.
> 
>> 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.
> 
> Doesn't matter if our goal is an RFC. If it is then the RFC2119
> boilerplate is necessary.

I send a patch.

>> 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.
> 
> I agree.
> 
>> 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.
> 
> This is exactly what I'm talking about above. We should be clear about
> this before we continue any further.
> 
> I disagree that we should have two documents. Two documents always means
> manual synchronization between the two which is error-prone. Also there
> are formats out there specified solely by RFCs, e.g. the specs around
> Xiph's Opus codec[1].

Agreed. I'd consider the RFC as the priority and would lead later development of human-readable documentation about the RFC. IF the RFC is standardized we can help write documentation about the RFC. For instance Opus has the RFC but then a great website about it http://opus-codec.org/.

>> 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.
> 
> In this case I cannot think of a way of generating such widely distinct
> formats from a single source of information. At least not for all parts
> of the specification.
> 
> It may be possible for the Matroska side of things, but for EBML at
> least I'd rather stick with a single RFC document, get some experience
> with the process and re-visit this question when we start working on the
> Matroska specs.

Agreed.
Dave
_______________________________________________
Matroska-devel mailing list
[email protected]
http://lists.matroska.org/cgi-bin/mailman/listinfo/matroska-devel
Read Matroska-Devel on GMane: http://dir.gmane.org/gmane.comp.multimedia.matroska.devel