ReSpec 2 changes

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

ReSpec 2 changes

Robin Berjon-2
Hi all!

I've been making quite a few changes to ReSpec v2 recently (as those who get the commit emails will have noticed). The good news is that I think we're close to a beta. The bad news is that if you had thrown caution to the wind and were already using v2, these changes will break your code (sorry, but alpha really means alpha).

The first change concerns the plugin system, and a new feature called profiles. ReSpec v2 is essentially a lot of little plugins that process the document in order, each making its own small changes, very much like a Unix shell with lots of pipes (which was indeed the inspiration). Previously you had to list all the plugins you wanted in order, but that was annoying since for a given document type (say, a W3C specification) you pretty much always want the same. To extend the metaphor, profiles are like shell scripts, they capture the list and order of plugins to run. Right now there's just one — w3c-common — but there are more on the way.

That's not all profiles can do. They also alleviate the loading-from-local-disk problem. As browser tighten up their security, it becomes decreasingly possible to load resources from file:. This is an annoyance because we don't want to force users to have to set up a Web server — ReSpec should just be a vanilla HTML document into which you add a script — but we wanted to be able to have dependencies such as templates. Thanks to RequireJS, profiles can be compiled, a process that not only makes everything neat and small but also folds in resources in such a way as to make them readily available. End users won't have to compile anything of course, that's for ReSpec developers (it also makes it easier for us to make "releases" so that all the documents in W3C that use ReSpec don't break at once whenever someone commits something stupid, as is currently the case with v1).

The plugins that used external resources have been updated to make use of this facility. The exception is core/data-include (since its resources are dynamic). That means that it will probably only be usable in limited circumstances or when developing from a web server. That's probably okay though since I don't believe that it is used much (I've never used it myself, Shane might have a different idea though :).

Note that this change means that v2 now works in Firefox, Opera, Safari, and Chrome (I haven't tested IE yet because I'm too lazy to watch Windows load in the VM, but I'll get around to it).

Developers who don't want to waste their time compiling profiles every time they make a change during development can use a trick similar to the one in profiles/w3c-common-loader which loads the compiled profile when your document is from file: and the individual plugins and resources separately when in http:. Also, look at build/build-w3c-common.sh for the command that's needed to build a profile.

Another breaking change is that I've reverted the configuration to rely on a global object as in v1. It's simpler, and it works better with profiles. The test document that shows how it works is in test-spec/webidl.html.

The way bibliographical references are done has changed as well. They are now defined and loaded as RequireJS modules. This is cleaner, simpler, and works a lot better than the previous approach. It also opens the door to a more distributed way of handling references (for details follow the hand-waving). We need to think more about that though.

Things to do before beta include:

  - a tiny amount of things to port from v1 (in case you haven't seen Gregg ported WebIDL which was the big one)
  - at least some skeletal documentation, I hope to get on to that next
  - more tests, even if not complete
  - checking that it's not completely broken on IE

Thoughts, feedback, etc. welcome!

--
Robin Berjon - http://berjon.com/




Reply | Threaded
Open this post in threaded view
|

Re: ReSpec 2 changes

Doug Schepers-3
Hi, Robin-

Thanks for the update.  I'm using v1 for the new Web Events drafts, but
look forward to v2.

May I suggest that you add top links for Editor's Draft and Public
Comments, as well?

Here's an example (though not using ReSpec):
   http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html


Regards-
-Doug Schepers
W3C Team Contact, SVG, WebApps, and Web Events WGs


Robin Berjon wrote (on 1/20/11 10:39 AM):

> Hi all!
>
> I've been making quite a few changes to ReSpec v2 recently (as those
> who get the commit emails will have noticed). The good news is that I
> think we're close to a beta. The bad news is that if you had thrown
> caution to the wind and were already using v2, these changes will
> break your code (sorry, but alpha really means alpha).
>
> The first change concerns the plugin system, and a new feature called
> profiles. ReSpec v2 is essentially a lot of little plugins that
> process the document in order, each making its own small changes,
> very much like a Unix shell with lots of pipes (which was indeed the
> inspiration). Previously you had to list all the plugins you wanted
> in order, but that was annoying since for a given document type (say,
> a W3C specification) you pretty much always want the same. To extend
> the metaphor, profiles are like shell scripts, they capture the list
> and order of plugins to run. Right now there's just one — w3c-common
> — but there are more on the way.
>
> That's not all profiles can do. They also alleviate the
> loading-from-local-disk problem. As browser tighten up their
> security, it becomes decreasingly possible to load resources from
> file:. This is an annoyance because we don't want to force users to
> have to set up a Web server — ReSpec should just be a vanilla HTML
> document into which you add a script — but we wanted to be able to
> have dependencies such as templates. Thanks to RequireJS, profiles
> can be compiled, a process that not only makes everything neat and
> small but also folds in resources in such a way as to make them
> readily available. End users won't have to compile anything of
> course, that's for ReSpec developers (it also makes it easier for us
> to make "releases" so that all the documents in W3C that use ReSpec
> don't break at once whenever someone commits something stupid, as is
> currently the case with v1).
>
> The plugins that used external resources have been updated to make
> use of this facility. The exception is core/data-include (since its
> resources are dynamic). That means that it will probably only be
> usable in limited circumstances or when developing from a web server.
> That's probably okay though since I don't believe that it is used
> much (I've never used it myself, Shane might have a different idea
> though :).
>
> Note that this change means that v2 now works in Firefox, Opera,
> Safari, and Chrome (I haven't tested IE yet because I'm too lazy to
> watch Windows load in the VM, but I'll get around to it).
>
> Developers who don't want to waste their time compiling profiles
> every time they make a change during development can use a trick
> similar to the one in profiles/w3c-common-loader which loads the
> compiled profile when your document is from file: and the individual
> plugins and resources separately when in http:. Also, look at
> build/build-w3c-common.sh for the command that's needed to build a
> profile.
>
> Another breaking change is that I've reverted the configuration to
> rely on a global object as in v1. It's simpler, and it works better
> with profiles. The test document that shows how it works is in
> test-spec/webidl.html.
>
> The way bibliographical references are done has changed as well. They
> are now defined and loaded as RequireJS modules. This is cleaner,
> simpler, and works a lot better than the previous approach. It also
> opens the door to a more distributed way of handling references (for
> details follow the hand-waving). We need to think more about that
> though.
>
> Things to do before beta include:
>
> - a tiny amount of things to port from v1 (in case you haven't seen
> Gregg ported WebIDL which was the big one) - at least some skeletal
> documentation, I hope to get on to that next - more tests, even if
> not complete - checking that it's not completely broken on IE
>
> Thoughts, feedback, etc. welcome!
>

--

Reply | Threaded
Open this post in threaded view
|

Re: ReSpec 2 changes

Shane McCarron
Is this some new convention that is being encouraged by pubs?  I
wouldn't want to codify anything that would fall afoul of 'pubrules'.

On 1/20/2011 3:43 PM, Doug Schepers wrote:

> Hi, Robin-
>
> Thanks for the update.  I'm using v1 for the new Web Events drafts,
> but look forward to v2.
>
> May I suggest that you add top links for Editor's Draft and Public
> Comments, as well?
>
> Here's an example (though not using ReSpec):
>   http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html
>
>
> Regards-
> -Doug Schepers
> W3C Team Contact, SVG, WebApps, and Web Events WGs
>
>
> Robin Berjon wrote (on 1/20/11 10:39 AM):
>> Hi all!
>>
>> I've been making quite a few changes to ReSpec v2 recently (as those
>> who get the commit emails will have noticed). The good news is that I
>> think we're close to a beta. The bad news is that if you had thrown
>> caution to the wind and were already using v2, these changes will
>> break your code (sorry, but alpha really means alpha).
>>
>> The first change concerns the plugin system, and a new feature called
>> profiles. ReSpec v2 is essentially a lot of little plugins that
>> process the document in order, each making its own small changes,
>> very much like a Unix shell with lots of pipes (which was indeed the
>> inspiration). Previously you had to list all the plugins you wanted
>> in order, but that was annoying since for a given document type (say,
>> a W3C specification) you pretty much always want the same. To extend
>> the metaphor, profiles are like shell scripts, they capture the list
>> and order of plugins to run. Right now there's just one — w3c-common
>> — but there are more on the way.
>>
>> That's not all profiles can do. They also alleviate the
>> loading-from-local-disk problem. As browser tighten up their
>> security, it becomes decreasingly possible to load resources from
>> file:. This is an annoyance because we don't want to force users to
>> have to set up a Web server — ReSpec should just be a vanilla HTML
>> document into which you add a script — but we wanted to be able to
>> have dependencies such as templates. Thanks to RequireJS, profiles
>> can be compiled, a process that not only makes everything neat and
>> small but also folds in resources in such a way as to make them
>> readily available. End users won't have to compile anything of
>> course, that's for ReSpec developers (it also makes it easier for us
>> to make "releases" so that all the documents in W3C that use ReSpec
>> don't break at once whenever someone commits something stupid, as is
>> currently the case with v1).
>>
>> The plugins that used external resources have been updated to make
>> use of this facility. The exception is core/data-include (since its
>> resources are dynamic). That means that it will probably only be
>> usable in limited circumstances or when developing from a web server.
>> That's probably okay though since I don't believe that it is used
>> much (I've never used it myself, Shane might have a different idea
>> though :).
>>
>> Note that this change means that v2 now works in Firefox, Opera,
>> Safari, and Chrome (I haven't tested IE yet because I'm too lazy to
>> watch Windows load in the VM, but I'll get around to it).
>>
>> Developers who don't want to waste their time compiling profiles
>> every time they make a change during development can use a trick
>> similar to the one in profiles/w3c-common-loader which loads the
>> compiled profile when your document is from file: and the individual
>> plugins and resources separately when in http:. Also, look at
>> build/build-w3c-common.sh for the command that's needed to build a
>> profile.
>>
>> Another breaking change is that I've reverted the configuration to
>> rely on a global object as in v1. It's simpler, and it works better
>> with profiles. The test document that shows how it works is in
>> test-spec/webidl.html.
>>
>> The way bibliographical references are done has changed as well. They
>> are now defined and loaded as RequireJS modules. This is cleaner,
>> simpler, and works a lot better than the previous approach. It also
>> opens the door to a more distributed way of handling references (for
>> details follow the hand-waving). We need to think more about that
>> though.
>>
>> Things to do before beta include:
>>
>> - a tiny amount of things to port from v1 (in case you haven't seen
>> Gregg ported WebIDL which was the big one) - at least some skeletal
>> documentation, I hope to get on to that next - more tests, even if
>> not complete - checking that it's not completely broken on IE
>>
>> Thoughts, feedback, etc. welcome!
>>
>

--
Shane P. McCarron                          Phone: +1 763 786-8160 x120
Managing Director                            Fax: +1 763 786-8180
ApTest Minnesota                            Inet: [hidden email]



Reply | Threaded
Open this post in threaded view
|

Re: ReSpec 2 changes

Robin Berjon-2
In reply to this post by Doug Schepers-3
Hi Doug,

On Jan 20, 2011, at 22:43 , Doug Schepers wrote:
> May I suggest that you add top links for Editor's Draft and Public Comments, as well?
>
> Here's an example (though not using ReSpec):
>  http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html

Editor's draft has been supported since day one, see any spec in http://dev.w3.org/2009/dap/. I agree that public comments is a really good idea (much better than hiding it in the SotD). I'll add it when I get a round tuit.

--
Robin Berjon - http://berjon.com/




Reply | Threaded
Open this post in threaded view
|

Re: ReSpec 2 changes

Doug Schepers-3
In reply to this post by Shane McCarron
Hi, Shane-

Shane McCarron wrote (on 1/20/11 4:46 PM):
> Is this some new convention that is being encouraged by pubs?  I
> wouldn't want to codify anything that would fall afoul of 'pubrules'.

It is neither encouraged nor discouraged.  It is allowed by pubrules,
and many people find it useful.


Regards-
-Doug Schepers
W3C Team Contact, SVG, WebApps, and Web Events WGs


> On 1/20/2011 3:43 PM, Doug Schepers wrote:
>> Hi, Robin-
>>
>> Thanks for the update. I'm using v1 for the new Web Events drafts, but
>> look forward to v2.
>>
>> May I suggest that you add top links for Editor's Draft and Public
>> Comments, as well?
>>
>> Here's an example (though not using ReSpec):
>> http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html
>>
>>
>> Regards-
>> -Doug Schepers
>> W3C Team Contact, SVG, WebApps, and Web Events WGs
>>

Reply | Threaded
Open this post in threaded view
|

Re: ReSpec 2 changes

Doug Schepers-3
In reply to this post by Robin Berjon-2
Hi, Robin-

Robin Berjon wrote (on 1/21/11 5:32 AM):
>
> On Jan 20, 2011, at 22:43 , Doug Schepers wrote:
>> May I suggest that you add top links for Editor's Draft and Public
>> Comments, as well?
>>
>> Here's an example (though not using ReSpec):
>> http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html
>
> Editor's draft has been supported since day one,

Okay, I see it now.  I expected it to be in a more prominent position,
towards the end of the list... I think a lot of people might miss it if
it's stuck in the middle like that.  Still, it's good to see it's there.


>see any spec in
> http://dev.w3.org/2009/dap/. I agree that public comments is a really
> good idea (much better than hiding it in the SotD). I'll add it when
> I get a round tuit.

Great, thanks!

Regards-
-Doug Schepers
W3C Team Contact, SVG, WebApps, and Web Events WGs

Reply | Threaded
Open this post in threaded view
|

Re: ReSpec 2 changes

Robin Berjon-2
Hi Doug,

On Jan 27, 2011, at 01:48 , Doug Schepers wrote:
> Robin Berjon wrote (on 1/21/11 5:32 AM):
>> Editor's draft has been supported since day one,
>
> Okay, I see it now.  I expected it to be in a more prominent position, towards the end of the list... I think a lot of people might miss it if it's stuck in the middle like that.  Still, it's good to see it's there.

I don't have time to hack on this right this second, but if you want to experiment with different positions to see what works best you're more than welcome to. In v1 search for "edDraftURI" and move around the if block that contains it in respec.js, in v2 it's similar but using templates in w3c/templates/headers.html.

--
Robin Berjon - http://berjon.com/