Import change in how the WebRTC API gets marked up

(cc public-media-capture since the topic is also relevant to specs in
the Media Capture Task Force)

Hi,

As many of you know, the WebRTC 1.0 API is developed using ReSpec, a
JavaScript library that takes care of a lot of the required formatting
for complying with W3C publication rules.

We have been so far using the ReSpec convention to write WebIDL in the
form of <dl><dt><dd>:
<dl title="interface Foo">
 <dt>attribute DOMString bar</dt>
 <dd>bar means quuz</dd>
</dl>

This approach, while it helped generate a lot of markup automatically,
has had several drawbacks:
- it uses a different syntax from WebIDL proper, so to edit the spec you
have to learn both WebIDL and this specific syntax
- it constraints very strongly how the spec is structured — each piece
of IDL infoset is defines on its own (where sometimes grouping several
at once would make more sense), it requires defining every piece of IDL
(when sometimes defining e.g. a dictionary member is redundant with the
interface the dictionary serves to initializes), etc

As a result, this mode of WebIDL editing has been deprecated in ReSpec,
and replaced by the so-called "WebIDL contiguous" mode, where one
defines WebIDL fragment using WebIDL proper:
   <pre class="idl">
     interface Foo {
       attribute DOMString bar;
     };
   </pre>
and can then make automatic references to the various pieces of IDL
infoset using e.g. <a data-for="Foo">bar</a>. This is documented and
illustrated at more length in
  https://www.w3.org/respec/examples/webidl-contiguous.html

In coordination with the Chairs and editors, I have converted our
existing WebRTC 1.0 draft to the WebIDL contiguous mode:

https://github.com/w3c/webrtc-pc/commit/5c0ffe57b4d0a6a79ba6374f0c9ad59600087c1f

This means that starting from now, anyone sending pull request on the
spec will have to do so using this WebIDL contiguous mode.

Also, any of the existing 8 pull requests will likely need a rebase (or
possibly more easily a rewrite), given how much of a breaking change the
conversion has been:
https://github.com/w3c/webrtc-pc/pulls

I'm already in discussion with the editors of the WebRTC Statistics API
to apply my semi-automated conversion script to their spec as well.

If editors of the other specifications of the group would be interested
in doing that conversion, please get in touch with me — I think we will
want sooner or later to convert all specs, but the timing of that
conversion is probably best evaluated by editors themselves. In
particular, it is best done when there are few or no open pull requests.

Dom

Received on Friday, 13 May 2016 07:37:38 UTC