ReSpec is a tool that makes writing specifications easier. Specifications tend to follow all manners of formalism, and in some cases will follow a strict set of conventions (e.g. W3C's "PubRules"). As an editor, you focus on actual features and correctness, ReSpec handle the likes of styling, referential integrity, bibliographical data, and a whole set of other dragons.

Concepts

The fundamental ideas that underlie ReSpec are:

It's Just HTML
You just edit HTML, with some extra convention but nothing extra. All the decoration is performed by the script, informed by some very basic configuration. There is a simple template that you can use to get started.
No Tool
You never have to run a tool outside of your editor and browser. While the specification is being developed that's all that's needed. When a snapshot is needed for publication, all it takes is saving the generated DOM to a file (the script is very careful to cleanly remove itself and its dependencies so that you should normally get a document that's immediately PubRules-OK). Moving from an Edit-Run Tool-Browser cycle to an Edit-Browser cycle can obviously be shown to make editors 33% more efficient.
DRY
Specifications often require repetitive structure (e.g. the header boilerplate, table of contents), repetitive markup (e.g. cross-linking to definitions, identifying conformance requirements), repeated information (e.g. an interface definition and its unfolded description), and many other things that make the process slow, painful, and error-prone. ReSpec makes every attempt to either generate that information for you based only on what varies from document to document, and to avoid repeating information inside of a document by reusing information automatically as much as possible.
DWIM (Do What I Mean)
There are many things in specifications that are somewhat obvious, but which you have to take care of anyway. RFC 2119 statements need to be marked up for instance, or references to definitions need linking. These are all handled for you trivially, so that you can focus on breaking the web and forget about the annoying details.
(Almost) All In The Browser
Typical technical writing tools will work in three steps: 1) make changes to the document, 2) run some arcane processing tool that will turn it into a format that can be displayed, 3) refresh the display to see if the change looks right — then rinse and repeat. ReSpec gets rid of the second step by making all the processing happen in the browser, which is also the tool you use for step 3. By skipping one stage out of three, it will make you 33% more efficient as an editor. The only case in which you will need to play with a processing tool is when you need to publish a snapshot of your specification as static HTML. This part is somewhat less trivial than the iterative use of ReSpec while editing, but it should be rare enough (typically once every few months) that it should pose no major issue.

There are many good existing tools that can be used to produce W3C specifications. A non-exhaustive list includes:

But I was dissatisfied with all of them, including the one I wrote. The primary reason for that was that they all require one to run a tool in between editing and reloading the browser — an extra step that at the end of a long day's work editing is one step too many. Beyond that there are some smaller issues that I personally have with each, but it is largely a matter of taste.

The first version of ReSpec was shipped in August 2009. Since then, it has become the most popular tool for specification editing at W3C. It benefits from a lively community of users that provide support to one another and contribute patches regularly. Now at version 3, it is a robust, full-featured tool surrounded by kind people.

Getting Support

The official support channel for ReSpec is spec-prod@w3.org. The archives are available at http://lists.w3.org/Archives/Public/spec-prod/. You can subscribe by sending email to spec-prod-request@w3.org with "subscribe" as the subject line.

Please use that instead of emailing me (Robin) directly as the chances are that questions or enhancement ideas will be shared by others. Thanks!

The source code for ReSpec is maintained in its GitHub repository. Feel free to fork and improve it! If you find a bug, you can consult the list of known issues and file a new issue if needed.

In the extremely unlikely event that you would find a problem with this documentation, you can find the repository on GitHub. That is also the place where issues are handled (and discussion is also on spec-prod).

This chapter lists all the items (JS configuration, elements, attributes, classes) that can form the ReSpec language.

Configuration Options

Elements

Attributes

Classes

Acknowledgments

A list of contributors can be found on GitHub.

Thanks to Expway, Vodafone, W3C, and Mozilla, for their direct support of this project.

Based on Bert Bos' CSS pre-processor and Geoffrey Sneddon's Anolis.