ReSpec is a small, unobtrusive tool that makes writing specifications easier. Or at least, somewhat less painful. It cannot do anything to quell the barrage of disputatious feedback that you are being slammed with, nor can it find you implementers ever-so-slightly less hopelessly hapless at reading your brilliant prose. It has no means to fix the bizarre process fixations of your group's chair, and sadly it cannot replace RFC 2119 with the more accurate RFC 6919. It will not stop those obstreperous people presently carrying pitchforks to your secret lair over that feature you pushed over to v2.
What is can do however, is make the toil of writing a specification 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.
The layout of this documentation is fairly straightforward. This page provides high-level information about ReSpec, as well as pointers for support and the such.
The User's Guide is a long, tutorial-like text about what one can do with ReSpec and how to use it. Some small advanced details may be missing, but overall if you read it from beginning to end you will be allowed to join meetings of jet-setting ReSpec experts.
The Reference section contains the description of every single configuration option, attribute, class, element, and event used in ReSpec. It is somewhat dry but aims at being objective. Six stars and three thumbs up for bedtime reading.
Finally, the Developer's Guide provides information for people who wish to start hacking on ReSpec itself.
The fundamental ideas that underlie ReSpec are:
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.
The official support channel for ReSpec is email@example.com. The archives are available at http://lists.w3.org/Archives/Public/spec-prod/. You can subscribe by sending email to firstname.lastname@example.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).
The following organisations deserve thanks for their direct support of ReSpec.
Expway, for giving me the leeway and time to work on the original Perl version of ReSpec over a decade ago. While that code has since been discontinued, it was nevertheless very helpful in establishing the principles that made the current version possible.
Vodafone for being kind enough to support a huge part of the initial work on ReSpec v1. This project would not exist without their support for web standards, and for the creation of tools that make building open standards easier.
The W3C for giving me the time to work on many refinements to ReSpec v3, notably this documentation which was put together during the W3C "Geek Week".
The following people have contributed to the project: Tobie Langel, Marcos Càceres, Greg Kellogg, Frederick Hirsch, Shane McCarron, Markus Lanthaler, Roy Fielding, Yves Lafon, Anssi Kostiainen, Cyril Concolato, Dominique Hazael-Massieux, Silvia Pfeiffer, Rich Tibbet, Dirk Schulze, Steven Speiche, Mounir Lamouri, Travis Leithead, Peter Linss, Mike Smith, Jacob Rossi, Chris Wilson, Bryan Sullivan, Adam Retter, Max Froumentin.
I stole a fair bit from Bert Bos and Geoffrey Sneddon.
Many deep thanks to all! If I've forgotten you, holler; it's an oversight due to the sorry overall state of my brain.