Re: Overview of Spec editing frameworks?

Hi Marc,

On May 26, 2010, at 14:00 , Marc Schroeder wrote:
> apologies for this beginner's question.

Don't apologise, that's what this list is for :)

> I am all in favor of distilling things to their essence, and an XML-to-surface type of spec writing process would seem to fit that well. Now I am looking for documentation on this, and find the Grammars section of the Editors' home page [2], which points to XMLSpec; on this mailing list I find mention of other frameworks including ReSpec and ReSpec 2, which I don't find mentioned on that page...
> 
> .... could anyone briefly point me to the available approaches, recommended best practice(s) etc.?

The recommended best practice is to use whichever tool you are the most comfortable and efficient with. I think that using a tool (as opposed to doing everything by hand) is also recommended, at least if you want to keep your sanity when you need to meet pubrules (and even just when you need to move sections around and keep the numbering and ToC in synch...).

As David said, it's largely a question of taste. If like me you get confused when you need to tab between three windows (editor - terminal - browser) and if you like simple shortcuts that DWIM (e.g. you have a Perl background) then ReSpec is probably for you. I wouldn't characterise this as an XML vs HTML thing, the original ReSpec was all XML, and when I rewrote it to run in the browser I translated the same semantics to HTML, just making them shorter to type. The syntax is essentially a sort-of polyglot (X)HTML5 document with certain processing rules layered on top.

On the other hand if you maybe want to integrate with an existing build framework that you're familiar with, if you want to output to formats other than HTML, or if you want processing that works (easily) outside of the browser then you really should not use ReSpec. If you like DocBook you'll like XMLSpec. Another option that is XHTML+XSLT-based is the WebIDL.xsl (http://dev.w3.org/2006/webapi/WebIDL/WebIDL.xsl) which takes an approach similar to ReSpec of combining the simplest possible XHTML with a set of extra options to help generation in the header, but implemented in XSLT. It is used by WebIDL and the File API (that I know of). You can see an example at http://dev.w3.org/2006/webapi/FileAPI/Overview-FA.xml.

There's also Anolis and the CSS Specification Generator, but I'll let others speak to those ones.

You mention v2 and David pointed you to it, but I wouldn't use that just yet (unless you like experimental stuff). It's still a moving target which I reserve the right to break, and it's not fully documented.

You can find v1 at http://dev.w3.org/2009/dap/ReSpec.js/. It is documented in http://dev.w3.org/2009/dap/ReSpec.js/documentation.html. All of DAP's specifications use ReSpec (http://dev.w3.org/2009/dap/), as well as several from WebApps, RDFa, and XML Security (that I know of). It's also being reused in OASIS and CME.

> Also, is there a recommended way of converting the current XHTML version into XML-based spec? Is rewriting everything by hand the only option?

If you have enough semantics in the original XHTML then some XSLT could do the job.

For conversion to ReSpec, assuming the version in TR is your source you'd mostly be removing stuff. Remove all the header, ToC, SotD, remove the section numbering, remove the references section. Then wrap each section in <section> elements for proper nesting, turn reference links into [[REF]] syntax, and add the JS parameters in the head. You should get pretty much the same specification out, with a shorter source.

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

Received on Wednesday, 26 May 2010 15:52:54 UTC