Redundancies, duplications, and general spec health

[marcoscaceres]

The spec needs a significant cleanup. I know the spec is really old, but it seems to be using specification patterns we (W3C and WHATWG) abandoned about a decade ago.

The terminology in the spec is also all over the place. It confuses objects, interfaces, etc.

Task queuing is also not done correctly throughout.

The unmaintained markup in the spec makes it extremely difficult for folks to contribute.

It would be good if, like any software project, we put in place coding standards and use tooling (e.g., HTML Tidy or Prettier) to keep the markup sane. This can be done automatically on merge, as is done elsewhere at the W3C.

[marcoscaceres]

Additionally, the sectioning of this spec could be done better. The method/attributes should actually be headings, not using <dl><dt><dd> patterns.

The duplicative summary tables that replicate what the IDL does should go away too (they are a vestige from some ancient Respec version). They add limited value and duplicate what is already clearly stated in the WebIDL (and become a maintenance burden because they need to be kept in sync with the IDL).

[wolenetz]

Additionally, we should consider reworking the https://en.wikipedia.org/wiki/COMEFROM spaghetti of recent * text that was originally added to make the MSE-in-Workers spec change more self-contained.

Examples:

• recent element error
• recent duration and recent live seekable range (I noted these when reviewing related spec PR today: Editorial: remove redundant tables #327 (comment))
• recent intersection ranges
  There could be others that I missed in my brief search now.

Thanks to @padenot for reminding me about the COMEFROM antipattern/joke :)

[wolenetz]

MSE took from HTMLMediaElement long ago the methodology for this, and it certainly needs updating. HTMLMediaElement still has occurrences of the synchronous set before queue task to fire the event. For example:

[wolenetz]

Many MSE event handler on.... attributes need more precise specification per #329 (comment) :

Event handlers are specified like this:

An event handler IDL attribute whose event handler event type is bufferedchanged.

If we don't do that, it can cause issues, as seen in Web MIDI, in which you can use addEventListener but can hook up a function to the on.... attribute.

[wolenetz]

TimeRanges arithmetic (e.g. ranges X = ranges Y - Z) needs definition as used in ManagedMediaSource's PR for ManagedSourceBuffer Buffered Change algorithm. I'm uncertain if the plan is to fix that as part of the current PR (#329) or in a separate follow-up PR at this point, to help ensure that work is tracked.

Note that TimeRanges union and intersection have been used since before v1 REC without precise definition of their arithmetic, though perhaps that also needs fixing.

[wolenetz]

RFC2119 words in non-normative portions of the spec like "Note:..." need replacement to avoid confusion or appearance of those portions seeming to be normative instead. (Per #329 (comment))

[chrisn]

If "This section is non-normative" appears in a section, does it apply also that section's subsections? If it does (and I'd assume it does), in addition to the Notes we'll also need to look at the terms defined in https://www.w3.org/TR/media-source-2/#definitions