Automatic conversion to WebIDL contiguous mode


Back in April, I brought up the topic of switching from using the 
current WebIDL "oldschool" mode in ReSpec to use the more modern 
"contiguous" mode:

While there was support for this, the resources needed to do the 
conversion seemed out of reach given all the other work that needs to 
happen on our specs.

Meanwhile, WebIDL oldschool is getting closer and closer to be 
deprecated (at least in the sense of no longer officially maintained, 
and potentially to warn about its usage in the ReSpec console).

I have thus looked at that problem space again, and have figured that we 
could use ReSpec to automate most of the conversion step; I've thus 
built a ReSpec profile [1] whose only role is to take a vanilla ReSpec 
document with oldschool WebIDL and (more or less) only applies the IDL 
processing to it, thus generating a document with content compatible to 
WebIDL contiguous mode.

The result of that automatic transformation is attached. While there 
will be some post-processing work needed to fix some of the anchors and 
the auto-links, the gist of the work gets done automatically.

Based on that, I think that when our list of substantive pull requests 
(i.e. the ones that would be hard or painful to rebase) empties, I would 
propose to run that conversion and replace our current webrtc.html with 
the result of that conversion (after the post processing alluded above, 
as well as some linewrapping/indenting).

Before that, I would like:
* to get confirmation we want to do this; one impact of the change of 
mode is that adding (or removing) WebIDL items require more markup work

* to understand if there are any automatic changes I should contemplate 
in that conversion; automatic changes might include getting rid of the 
some of the automatic headers (e.g. Dictionary Foo members), or more 
generally, adapting all the human-readable stuff currently generated by 
WebIDL oldschool.

I personally feel that we'll be able to make the document much more 
readable & better structured once we move away from WebIDL oldschool.



Received on Thursday, 10 December 2015 16:22:40 UTC