ReSpec.js

A Fresh Specification-Writing Tool

Robin Berjon

Vodafone

Why a new spec-writing tool?

Really, man, why?

• Not because the others are bad
• Wanted something that matched a more "web development" style
• Already had one (ReSpec Perl) which needed freshening up
• Had an itch to scratch
• Wanted to help editors in the DAP WG (a dozen specs) focus on Just Friendly Doing It, rather than all the paraphernalia

What's good about it?

it's my baby

How a web developer creates a document

or "How sausages are made"

How most spec-writing tools work

Too much information about sausages

How ReSpec.js approaches this issue

Make Your Editors 33% more efficient!!!!!1

How does it work?

all pretty on the inside

• A bare-bones HTML5 document
• With some Javascript magic
• Renders like the real thing, without caring about PubRules
• Save to a PubRules-compliant output when you need to (just for official publication)

But, so, what does it do?

Simple configuration generates oodles of HTML

I love the word "oodles"

          var respecConfig = {
              specStatus:           "RSCND",
              shortName:            "sexy-spec",
              previousPublishDate:  "1977-03-15",
              previousMaturity:  "REC",
              edDraftURI:           "http://dev.w3.org/2006/waf/widget-access/",
              extraCSS:             ["../../../2009/dap/ReSpec.js/css/respec.css"],
              editors:  [
                  { name: "Robin Berjon", url: "http://berjon.com/",
                    company: "Vodafone", companyURL: "http://vodafone.com/" },
              ],
              wg:           "Best Ever WG",
              wgURI:        "http://www.w3.org/dated/uris/are/evil/",
              wgPublicList: "public-coolness",
              wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/42/status",
          };
        

Pretty much writes the spec for you

Less boilerplate, more time for beer

Sections and ToC

structured so you don't have to be

• Fairly standard stuff
• Uses <section> for clear sections
• Will rename <h1>-<h6> to be at the correct depth level
• Handles appendices (numbered separately), automatic ID, labelling as "non-normative"

RFC 2119 is not OPTIONAL

the next version has EXTERMINATE

• Will automatically find, markup, and style any RFC 2119 keyword in caps
• Handles <dfn> (including <abbr> and even <acronym>) and references to them using minimal markup

References

Pointing fingers

• Marked simply with [[DAHUT]] and [[!DAHUT]]
• Auto-generates informative and normative reference sections
• Uses a centralised JSON DB pilfered from Bert's bibtex

Nice Little Extras

Sugar and Unicorns

• Issues, notes, examples have distinctive styles
• Examples can have automatic syntax highlighting (supported for: CSS, HTML, JS+DOM, XML)
• More syntax highlighting can easily be added with SHJS

WebIDL Support

for thems API geeks

• You start with something simple, just a single line

interface Unicorn: Cryptid, Mammal {
    Dahut convertToDahut(in boolean chirality) raises IsInvisibleException;
}
        

WebIDL Support (bis)

it's addictive

But then you start wanting more...

• Linking methods and attributes to the prose
• Cross-reference return an parameter types to their interfaces
• Producing pretty tabular outlines of what parameters mean
• Producing pretty tabular descriptions of which exceptions with what codes can be thrown
• Maybe validating the WebIDL
• Automagically generating browser tests based on the WebIDL
• ...

Limitations

just to pretend I'm unbiased

• Doesn't work in older browsers
• Saving can be a bit cumbersome at the moment
• First load can be slow due to references DB being downloaded
• Not all of WebIDL supported yet (but much is)
• Documentation can be a couple weeks behind features
• Occasional bugs

Ongoing & Future Work

more magic, more of the time

• Offline support, widgetisation
• Automatic normative assertion extraction
• WebIDL test generator
• Saving using DAP FileSystem API
• General improvements to existing features

Where to get it

sorry about the dated URI

• http://dev.w3.org/2009/dap/ReSpec.js/documentation.html
• http://dev.w3.org/2009/dap/ReSpec.js/test-spec/index.html
• http://dev.w3.org/2009/dap/ReSpec.js/test-spec/webidl.html
• http://dev.w3.org/2009/dap/ReSpec.js/template.html

Where it's used

satisfied customers

• Most of http://dev.w3.org/2009/dap/
• http://www.w3.org/TR/dap-api-reqs/
• http://www.w3.org/TR/widgets-uri/
• And more in the pipeline

Thanks!