ReSpec 2 changes

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/

Received on Thursday, 20 January 2011 15:39:38 UTC