RE: ReSpec: are you using old school webIDL?

> De : Dominique Hazael-Massieux [mailto:dom@w3.org]
> Envoyé : vendredi 9 décembre 2016 08:46
> 
> On 08/12/2016 17:56, Philippe Le Hégaret wrote:
> >
> >
> > On 11/28/2016 12:41 AM, Marcos Caceres wrote:
> >> Hi ReSpec users,
> >> I'm trying to get a sense of who is still using old school WebIDL.
> >> Could you please email me if you are?
> >>
> >> As it's been deprecated for a few years, and it's now conflicting with
> >> things, I'd like to remove it for xmas. I'm happy to help people
> >> migrate over to new school WebIDL:
> >>
> >> https://github.com/w3c/respec/wiki/WebIDL-Guide
> >
> > * https://w3c.github.io/navigation-timing/
> > * https://w3c.github.io/resource-hints/
> >
> > Those two are lagging behind other webperf specs. It's not hard work to
> > convert but it will take 3 to 4 hours to do so manually :(
> 
> As a reminder, I have a script that can help convert ReSpec old-school
> to contiguous:
>   https://lists.w3.org/Archives/Public/spec-prod/2016AprJun/0064.html
> 
> (copying François who is the last person I know who used it in case he
> has more insights on how usable it still is)

It still works. How-to instructions could perhaps be improved. On top of my head, this is what I think I did:

1. Clone repo to local and switch to appropriate branch:
  git clone https://github.com/dontcallmedom/respec.git
  cd respec
  git checkout oldschool2contiguous

2. Copy the spec to convert to the "respec" folder

3. In the spec to convert, replace the ReSpec <script> tag with <script src="/js/profile-webidlconvert.js"></script>

3. Run a local HTTP server to serve the files, rooted on the "respec" folder.

4. Load the spec in a browser

5. "Save snapshot" to get the updated source

6. Tidy the updated source as needed

7. Check the updated source and manually fix the structure as needed. In my case, I converted the wrapping <div> that surround WebIDL blocks into <section> for attributes/methods sections to appear in the TOC for instance. I suppose the conversion may lead to broken fragment references as well which should be easy to fix. Also, the <script> tag needs to be rolled back to the usual ReSpec address.

One thing that could be worth pointing out: the conversion preserves the formatting of the spec, in particular the <dl> lists for attributes and methods. After conversion, these lists need to be maintained manually. This is error prone because the type of attributes and method parameters, which appears in the IDL is also repeated in these lists, and will no longer be automatically updated when the IDL is. The editor might want to simplify the structure to ease maintenance on a longer term basis.

Francois.

Received on Friday, 9 December 2016 09:12:19 UTC