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.
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
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.
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.
The official support channel for ReSpec is firstname.lastname@example.org. The archives are
available at http://lists.w3.org/Archives/Public/spec-prod/.
You can subscribe by sending email to email@example.com
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
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
This chapter lists all the items (JS configuration, elements,
attributes, classes) that can form the ReSpec language.
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.