Re: Automatic conversion to WebIDL contiguous mode

On 2015-12-10 17:22, Dominique Hazael-Massieux wrote:
> Hi,
>
> 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:
> https://lists.w3.org/Archives/Public/public-webrtc-editors/2015Apr/0012.html
>
> 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.

Can we split this work or does it complicate things? I can do some 
sections if needed.

> 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).

I think now is a perfect time to do this. We only have 11 open PRs and 
out of those, all but two have diffs that fit on one screen. Regarding 
the other two, one is mine (can be fixed) and the other is only touching 
make/config files (Martin's).

> 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

I'm for.

> * 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 think there are too many sub-sections generated. For 
example for members and attributes of every single interface. The table 
of contents gets a bit messy and less useful. I noted that the 
webrtc-contiguous.html you attached had a substantially shorter TOC 
which I like. Could we talk about this on the next editor's call perhaps?

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

I think so too. Thanks for pushing us a bit on this Dom. :)

/Adam

Received on Friday, 8 January 2016 09:41:14 UTC