Re: Automatic conversion to WebIDL contiguous mode

I'm much in favor of switching. I'd like to understand what the pain
points are likely to be (if any); what Dom is describing sounds like a
miracle (if the only effect is a shorter ToC, let's Just Do It).

Den 08. jan. 2016 10:40, skrev Adam Bergkvist:
> 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 11:13:15 UTC