Anne van Kesteren | 23 May 14:45 2012
Picon

Howto spec

Hi,

I have made some updates to the "howto spec" wiki page outlining how
you should go about writing a specification, with some emphasis on
specifications for APIs.

http://wiki.whatwg.org/wiki/Howto_spec

In particular the "Patterns" and "Legacy DOM-style" sections are
probably of interest. I would love to have feedback to see what else
people would like to see explained or how what is explained thus far
can be done better.

Thanks,

--

-- 
Anne — Opera Software
http://annevankesteren.nl/
http://www.opera.com/

Dimitri Glazkov | 23 May 17:55 2012

Re: Howto spec

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?

:DG<

On Wed, May 23, 2012 at 5:45 AM, Anne van Kesteren <annevk <at> annevk.nl> wrote:
> Hi,
>
> I have made some updates to the "howto spec" wiki page outlining how
> you should go about writing a specification, with some emphasis on
> specifications for APIs.
>
> http://wiki.whatwg.org/wiki/Howto_spec
>
> In particular the "Patterns" and "Legacy DOM-style" sections are
> probably of interest. I would love to have feedback to see what else
> people would like to see explained or how what is explained thus far
> can be done better.
>
> Thanks,
>
>
> --
> Anne — Opera Software
> http://annevankesteren.nl/
> http://www.opera.com/
(Continue reading)

Glenn Adams | 23 May 19:29 2012

Re: Howto spec


On Wed, May 23, 2012 at 9:55 AM, Dimitri Glazkov <dglazkov <at> 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
Glenn Adams | 23 May 19:48 2012

Re: Howto spec

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


On Wed, May 23, 2012 at 9:55 AM, Dimitri Glazkov <dglazkov <at> 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

Anne van Kesteren | 23 May 20:30 2012
Picon

Re: Howto spec

On Wed, May 23, 2012 at 5:55 PM, Dimitri Glazkov <dglazkov <at> chromium.org> wrote:
> 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?

It's a tradeoff:

ReSpec.js pro:

* No setup costs

ReSpec.js con:

* Loads slower because of script. You get a flash of unstyled content.
User experience suffers.
* Legacy DOM-style of defining methods/attributes appears to be the default.

Anolis pro:

* Cross-specification cross-references

Anolis con:

* Harder (requires Python)

In the end it comes down to what the editor wants; I think Anolis is
better because the end user experience is better.

--

-- 
Anne — Opera Software
http://annevankesteren.nl/
http://www.opera.com/

Robin Berjon | 24 May 10:39 2012

Re: Howto spec

On May 23, 2012, at 20:30 , Anne van Kesteren wrote:
> On Wed, May 23, 2012 at 5:55 PM, Dimitri Glazkov <dglazkov <at> chromium.org> wrote:
>> 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?
> 
> It's a tradeoff:
> 
> ReSpec.js pro:
> 
> * No setup costs
> 
> ReSpec.js con:
> 
> * Loads slower because of script. You get a flash of unstyled content.
> User experience suffers.

Right. ReSpec is optimised for editors more than for users, at the cost of all the processing taking place at
runtime. The performance is made worse by the fact that a 300K biblio database (yay!) is loaded over the
wire. The FOUC is much worsened by the fact that an older browser (I forget which, maybe FX3?) had abysmal
performance when many text nodes were being manipulated, the fix for which was to set display: none on body
before running and reverting it afterwards (re-yay!). Both of those issues are going away very soon though.

If you want smoother UX you can generate a static output. This is currently harder than it should be; if
there's interest I can hack something out.

Overall there's no competition though, I doubt that there can be one tool for everyone's tastes. I also
think that it's good to have a Web-based tool and a more traditional Python one, it helps us keep in mind what
we need to improve with the Web.

--

-- 
Robin Berjon - http://berjon.com/ -  <at> robinberjon

Glenn Adams | 23 May 19:09 2012

Re: Howto spec


On Wed, May 23, 2012 at 6:45 AM, Anne van Kesteren <annevk <at> annevk.nl> wrote:
Hi,

I have made some updates to the "howto spec" wiki page outlining how
you should go about writing a specification, with some emphasis on
specifications for APIs.

http://wiki.whatwg.org/wiki/Howto_spec

In particular the "Patterns" and "Legacy DOM-style" sections are
probably of interest. I would love to have feedback to see what else
people would like to see explained or how what is explained thus far
can be done better.

I would like to see more explanation of some statements under the "Legacy DOM-style" section, particularly:
  • what is the "particular style of defining methods and attributes" that is to be discouraged?
  • how does ReSpec.js use or promote the discouraged particulars?
Anne van Kesteren | 23 May 20:40 2012
Picon

Re: Howto spec

On Wed, May 23, 2012 at 7:09 PM, Glenn Adams <glenn <at> skynav.com> wrote:
> I would like to see more explanation of some statements under the "Legacy
> DOM-style" section, particularly:
>
> what is the "particular style of defining methods and attributes" that is to
> be discouraged?

Added "the separation of method definition from arguments, exceptions,
and return value".

> how does ReSpec.js use or promote the discouraged particulars?

Most specifications (if not all) using ReSpec.js have this problem. I
believe that is because it is the default setup.

--

-- 
Anne — Opera Software
http://annevankesteren.nl/
http://www.opera.com/

Robin Berjon | 24 May 10:27 2012

Re: Howto spec

On May 23, 2012, at 20:40 , Anne van Kesteren wrote:
>> how does ReSpec.js use or promote the discouraged particulars?
> 
> Most specifications (if not all) using ReSpec.js have this problem. I
> believe that is because it is the default setup.

Yup, it's just the default setup. As I've said before, I'm certainly very open to adding alternative ways of
doing it. Anyone interested in working on this can just ping me.

--

-- 
Robin Berjon - http://berjon.com/ -  <at> robinberjon

Robin Berjon | 24 May 10:44 2012

Re: Howto spec

On May 23, 2012, at 14:45 , Anne van Kesteren wrote:
> I have made some updates to the "howto spec" wiki page outlining how
> you should go about writing a specification, with some emphasis on
> specifications for APIs.
> 
> http://wiki.whatwg.org/wiki/Howto_spec
> 
> In particular the "Patterns" and "Legacy DOM-style" sections are
> probably of interest. I would love to have feedback to see what else
> people would like to see explained or how what is explained thus far
> can be done better.

Thanks Anne, this is good stuff. I wonder if maybe there would be value in merging some of that with
http://scriptlib-cg.github.com/api-design-cookbook/. It's just a rough draft now but I'm slated to
update it a fair bit over the next three months or so.

It's currently under the scriptlib's repo, but since that doesn't seem to be taking off we can put it elsewhere.

--

-- 
Robin Berjon - http://berjon.com/ -  <at> robinberjon

Charles McCathieNevile | 24 May 14:02 2012
Picon

Re: Howto spec

There is a list called spec-prod <at> w3.org which is about things to do with  
making specs. I.e. for editors, in particular. I forwarded some stuff from  
this thread there - there are other preprocessing systems around,  
including XML toolsets. I think this stuff used to be documented  
somewhere, and it might be worth trying to find that and make it look like  
it comes from the 21st century...

cheers

On Wed, 23 May 2012 14:45:05 +0200, Anne van Kesteren <annevk <at> annevk.nl>  
wrote:

> Hi,
>
> I have made some updates to the "howto spec" wiki page outlining how
> you should go about writing a specification, with some emphasis on
> specifications for APIs.
>
> http://wiki.whatwg.org/wiki/Howto_spec
>
> In particular the "Patterns" and "Legacy DOM-style" sections are
> probably of interest. I would love to have feedback to see what else
> people would like to see explained or how what is explained thus far
> can be done better.
>
> Thanks,
>
>

--

-- 
Charles 'chaals' McCathieNevile  Opera Software, Standards Group
     je parle français -- hablo español -- jeg kan noen norsk
http://my.opera.com/chaals       Try Opera: http://www.opera.com


Gmane