W3C home > Mailing lists > Public > public-html-media@w3.org > January 2013

[MSE] Spec writing guidance for splicing bugs

From: Aaron Colwell <acolwell@google.com>
Date: Thu, 31 Jan 2013 11:34:21 -0800
Message-ID: <CAA0c1bCKyeYWn+4YcQqOUQF-86w7smYCFOAeepCPmDay7T94Yw@mail.gmail.com>
To: "<public-html-media@w3.org>" <public-html-media@w3.org>
Hi,

I've started looking into addressing the various splicing related MSE bugs
and I would like to get some advice on spec writing best practices.

As some may recall, early versions of the MSE spec had text descriptions of
various behaviors and then algorithmic descriptions that basically covered
the same territory. Many of Philip's original comments had to do with
inconsistencies between these two descriptions and it was made clear that
just having the algorithms describe the behaviors in a normative form was
preferable. This made the spec much easier for me to maintain and I believe
it made the behavior descriptions much more precise. The side effect of
this though is that some high level behaviors many not be clear from the
low level algorithm descriptions.

For example, part of Bug
19784<https://www.w3.org/Bugs/Public/show_bug.cgi?id=19784> strives
to clarify how a splice with multiplexed content works. There has been a
little discussion around an image that describes the intended behavior.
Except for the cross-fade behavior and a missing coded frame removal step,
the coded frame processing
algorithm<https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#sourcebuffer-coded-frame-processing>
covers
how timestampOffset is applied and causes splices to be resolved on a per
track basis. This may not be as obvious as the image in the bug indicates,
but it is there.

So here are my questions:
- What is an acceptable amount of duplication/alternate explanations I
should have in the spec text?
- Who is the MSE spec's primary audience? Implementers or content creators?
Obviously since Philip, Adrian, and myself are implementers, I've been
focusing on being precise about the algorithmic aspects and less focused on
easy to understand higher-level pros descriptions of certain behavior.
- If alternate explanations are common/expected, will people please provide
some good examples in other specs that I can draw inspiration from?
- Are there other examples of how to clearly mark non-normative sections?
If there are to be alternate explanations that aren't considered normative,
I'd prefer them not having to be in a giant green box. :)


Thanks for your help,
Aaron
Received on Thursday, 31 January 2013 19:34:48 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 31 January 2013 19:34:49 GMT