Re: Howto spec

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