Re: Howto spec

On Wed, May 23, 2012 at 11:29 AM, Glenn Adams <glenn@skynav.com> wrote:

>
> On Wed, May 23, 2012 at 9:55 AM, Dimitri Glazkov <dglazkov@chromium.org>wrote:
>
>> This is neat! I especially appreciated the Method/Attribute patterns.
>> I will use this.
>>
>> Should I be concerned about what seems to be a lively competition
>> between ReSpec and Anolis. Do we need this tussle? Can we not just
>> decide which tool to use?
>
>
> editor tools are at the editors' prerogative, so we should not mandate
> specific tools i think
>
> in fact, i am not completely happy with either respec or anolis, and have
> put together something of a hybrid i'm using on cssom*;  in particular,
> what i'm doing is:
>
>    - writing all IDL and related documentation in WebIDL format, with
>    each top-level definition in a distinct file, while using 'Documentation'
>    extended attributes in the WebIDL files that contains both substitution
>    patterns and markup, rather akin to javadoc but with different substitution
>    keywords that better pertain to the WebIDL usage context;
>    - use a driver file with CPP includes, then running (gnu) CPP to
>    create a single IDL resource for the subsequent processing
>    - use robin's WebIDLParser.js [1] (via node.js) to validate and dump
>    JSON representation of IDL
>    - use Aria Stewart's (aredridel) HTML5.js parser [2] (via node.js) to
>    parse then serialize with substitution replacement based on the JSON IDL,
>    e.g., <!--widl(MediaList)--> is replaced with an HTML5 representation of
>    the MediaList IDL, <!--widl-intro(MediaList)-->,
>    <!--widl-attrs(MediaList)-->, <!--widl-methods(MediaList)-->, etc., get the
>    associated documentation
>    - finally use anolis to perform other substitutions, toc generation,
>    etc.
>
> the reason I'm doing this is because i prefer embedding documentation in
> IDL sources than embedding IDL in HTML sources; i also want to do all
> processing at authoring time, and not at load time via the ReSpec approach
>
> once i'm satisfied with this approach, i'll post it and document with a
> wiki in case some other editor wishes to use this method; but, again, i
> think which approach is used should be left to specific editors, since it
> affects their productivity
>
> cheers, glenn
>

relevant links

[1] https://github.com/darobin/webidl.js
[2] https://github.com/aredridel/html5