ReSpec Editor's Guide
A ReSpec document is a HTML document that brings in the ReSpec script, defines a few configuration variables, and follows a few conventions. A very small example document would be:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Replace me with a real title</title>
<script
src="https://www.w3.org/Tools/respec/respec-w3c"
class="remove"
defer
></script>
<script class="remove">
// All config options at https://respec.org/docs/
var respecConfig = {
specStatus: "ED",
editors: [{ name: "Your Name", url: "https://your-site.com" }],
github: "some-org/mySpec",
shortName: "dahut",
xref: "web-platform",
group: "my-working-group",
};
</script>
</head>
<body>
<section id="abstract">
<p>This is required.</p>
</section>
<section id="sotd">
<p>This is required.</p>
</section>
<section class="informative">
<h2>Introduction</h2>
<p>Some informative introductory text.</p>
<aside class="note" title="A useful note">
<p>I'm a note!</p>
</aside>
</section>
<section>
<h2>A section</h2>
<aside class="example">
<p>This is an example.</p>
<pre class="js">
// Automatic syntax highlighting
function someJavaScript(){}
</pre>
</aside>
<section>
<h3>I'm a sub-section</h3>
<p class="issue" data-number="121">
<!-- Issue can automatically be populated from GitHub -->
</p>
</section>
</section>
<section data-dfn-for="Foo">
<h2>Start your spec!</h2>
<pre class="idl">
[Exposed=Window]
interface Foo {
attribute DOMString bar;
undefined doTheFoo();
};
</pre>
<p>The <dfn>Foo</dfn> interface represents a {{Foo}}.</p>
<p>
The <dfn>doTheFoo()</dfn> method does the foo. Call it by running
{{Foo/doTheFoo()}}.
</p>
<ol class="algorithm">
<li>A |variable:DOMString| can be declared like this.</li>
</ol>
</section>
<section id="conformance">
<p>
This is required for specifications that contain normative material.
</p>
</section>
<section class="appendix">
<h2>Change log</h2>
<p>Recent changes to this specification from GitHub:</p>
<rs-changelog from="some-git-tag"> </rs-changelog>
</section>
</body>
</html>The following code is used to include a ReSpec document:
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer></script>
<script class="remove">
var respecConfig = {
// configuration options
}
</script>ReSpec is regularly updated and this will allow you to automatically benefit from bug and security fixes and enhancements.
ReSpec is configured using a JSON-like object, which is assigned to a respecConfig JavaScript variable:
<script class="remove">
var respecConfig = {
// configuration options
}
</script>ReSpec documents follow of a standard HTML document - as such, all HTML elements are supported. In particular, ReSpec documents will typically make use of the following HTML elements, each serving their expected roles in a document:
-
<title>or<h1 id="title">- The title of your document. -
<section>- a section of document, which must include a<h2>-<h6>. <h2>-<h6>-
<aside>- used for notes, issues, etc. -
<figure>and<figcaption> <table>-
<ul>and<ol>
See the example at the start of this document for typical usage. Some HTML elements get special treatment by ReSpec, as described in the following sections.
The <title> of the document is reused as the title of the specification in the resulting document's h1. That way, they are always in sync and you need not worry about specifying it twice. However, if you need to add additional markup to your title, you can still use a <h1> with id="title".
<h1 id="title">The <code>Foo</code> API</h1>Optionally, you can also specify a subtitle configuration option in the ReSpec config. The subtitle configuration option takes a simple string that will be used as a subtitle for the specification, right under the title. As with the title, you can also specify a subtitle as:
<h2 id="subtitle">Subtitle here</h2>Which is rendered as:
Every specification must have some editors (at least one) and may have some authors (and maybe some former editors/authors also). Editors and authors are specified as Person objects.
Editors are the people in charge of the document. Authors are people who produced substantial contributions, but did not manage the document per se. Most of the time authors are not specified, but that practice varies between groups:
var respecConfig = {
// ...
editors: [
{
name: "Robin Berjon",
url: "https://berjon.com/",
company: "W3C",
companyURL: "https://w3c.org/",
mailto: "[email protected]",
note: "A Really Cool Frood",
},
{
name: "Billie Berthezène-Berjon",
company: "Catwoman",
},
],
authors: [
{
name: "Ada Lovelace",
url: "https://findingada.com/",
company: "Aristocracy",
retiredDate: "1852-11-27",
},
],
// ...
};Is rendered as:
ReSpec-based specifications require you to wrap your content in <section> elements. We provide specific information and examples on how to use <section> elements.
Sections, subsections, appendices, and whatever other structural items are marked up in ReSpec using <section> elements.
<section>
<h2>A section</h2>
<p>Some text.</p>
<section class="informative">
<h3>I'm a sub-section</h3>
<p>Subsetion text.</p>
</section>
</section>Which is rendered as:
As shown, sections are automatically numbered. If you wish a section to have a specific ID, then simply use an id attribute on it. If you don't, ReSpec will generate one for you based on the section title, and will ensure that it is unique.
ReSpec sections understand some specific CSS classes: introductory, informative, and appendix.
If you wish to link to a section and have its number and title automatically appear as part of the link, then you can use the special syntax[[[!#some-id]]].
A table of contents is generated automatically and placed right after the SotD. If you have a deeply nested document structure and find that the ToC is either too long or too deep, you can use the maxTocLevel option to limit how deep it goes.
If for whatever reason you wish to have no table of contents, simply set the configuration option noTOC to true.
Figures are also supported natively, using the <figure> and <figcaption> elements, and exhibit some features similar to sections. They are automatically granted an ID, and the caption is remembered for use elsewhere, as described below.
<figure id="figure">
<img src="figure.svg" alt="W3C Logo" />
<figcaption>The W3C logo</figcaption>
</figure>Which renders as:
Automatic linking to figures works just as it does for sections, with [[[!#some-figure]]].
The "List of Figures" is not generated by default: to add one, include <section id="tof"> anywhere in the document. ReSpec will do its best to guess if it should be an appendix, introductory, or just a regular section.
<section id="tof"></section>Renders as:
Any pre or aside element that has the example CSS class will get the additional example header and style. Content inside pre elements is syntax highlighted. The syntax highlighter does not need to be instructed about which language it is highlighting and will try to do a decent job of guessing.
You can disable syntax highlighting on a pre element by adding a "nohighlight" class.
At times you need to include an external resource directly into your document. This may be because your specifications have additional boilerplate, or (like it's done in this very guide) because you want examples to be both inlined and accessed directly without having to make sure that they are always in sync.
Inclusion of external content in ReSpec is done using the data-include attribute. It is expected to point to a resource, using its relative path from the including document. The content will get included as a child of the element on which the inclusion is performed, replacing its existing content (unless data-include-replace is used, in which case it replaces the element).
In the processing pipeline, inclusion happens right after everything to do with the document's headers, style, and transformations have happened, which means that all the processing to do with structure, inlines, WebIDL, and everything else is applied to the included content as if it had always been part of the source.
At times however one does not wish included content to be processed as if it were intended to be ReSpec content. For instance, content containing HTML may be an example that should not be processed (the examples in this document are included that way). In such cases, you can specify data-include-format='text'. This will include the content as if it were text, and therefore only process it as much as text is expected to be. The only recognized value are "text" and "markdown", nominally you can always set it to "html" but that's the default value.
There is an important caveat to take into account with the data-include functionality. ReSpec is designed so as to make life easier on editors. Because of that, people who do not wish to run a local web server and simply want to edit and refresh the specification they're working on from their local drives, using a file:// URI in the browser, are generally supported in doing so (this involves some trickery behind the scenes since it would normally make it impossible to load some of the content that ReSpec uses — but that's not something you should ever have to know). When using data-include, this is no longer possible. You either have to serve your ReSpec content from a web server or the included content will get blocked by the same-origin policy (which applies to all things file://). There is, unfortunately, no easy way to work around this. Be sure to note however that if you're not using data-include, you never have to worry about this. Though, we will still recommend you to spin-up a local http server to serve static files.
Finally, at times, you may wish to perform a quick and dirty transformation of some of your content included with data-include. You can use data-oninclude for that. The way in which it is done is that you include a globally available Javascript function that takes the ReSpec utils object as its first parameter, a string of the content to be transformed as its second, and a third parameter indicating the relative URL from which content was loaded; then returns the processed value. The value of data-transform is a white space separated list of JavaScript function names. They are applied left to right, as if they were a pipeline.
Many repetitive tasks happen at the level of inline text, and ReSpec helps with those as well. This chapter covers references, along with the SpecRef database, the handling of abbreviations and acronyms, automatic RFC 2119 keyword detection, dfn definitions, and easier in-document linking.
ReSpec specifications are RFC2119 keyword aware (i.e., it knows about "MUST", "SHOULD NOT", etc.).
Adding a <section id="conformance"> tells ReSpec that the specification is dealing with "normative" statements. ReSpec can then warn if RFC2119 keywords are accidentally used in informative/non-normative contexts.
<section>
<h2>Requirements</h2>
<p>A user agent MUST do something.</p>
</section>
<section id="conformance"></section>Renders as:
HTML supports functionality to mark abbreviations and acronyms (using <abbr>), using the title attribute to provide the expanded version. This is something that's nice to do once, but tedious to repeat every time that a given term is used. What ReSpec does is that it allows you to do it just once, and it will detect all other uses of the same in the text and will automatically mark them up in the same way.
<p>The <abbr title="world wide web">WWW</abbr>.</p>
<p>The WWW.</p>To mark some text as code, we need to wrap it in <code> elements. ReSpec lets you wrap text in backticks (`) to mark it as code, which is usually more comfortable.
To define a term, simple wrap it in a <dfn> element.
<dfn>some concept</dfn>Then, to link to it, just do:
<a>some concept</a>
or
[=some concept=]For common nouns, ReSpec can handle pluralization automatically:
<dfn>banana</dfn>
<!- these are the same -->
These [=bananas=] are better than those <a>bananas</a>Sometimes, a defined terms needs additional related terms or synonyms. In those cases, you can use the data-lt attribute on the dfn element:
<dfn
data-lt="the best fruit|yellow delicious">
banana
</dfn>The following all link back to "banana":
<p>[=the best fruit=] or the [=yellow delicious=].</p>Often, you need to link to terms defined in other specifications. ReSpec makes it quite simple with its cross referencing (xref) feature. In short, you specify a list of specifications ReSpec may search a term from, and simply reference the term. For example, to reference "default toJSON steps" from the WebIDL standard:
<script>
var respecConfig = {
xref: ["WebIDL"],
};
</script>
<a>default toJSON steps</a>Frequently, you might also need to specify the type and context of the definition. Specifying all such metadata becomes clumsy quickly (something like <a data-link-type="some-type" data-link-for="some-context">term</a>). This is where ReSpec's shorthands come in picture. There are two important shorthands when it comes to linking to definitions: [= term =] for linking regular concepts, and {{ term }} for linking IDL stuff.
You don't need to remember when to use standard HTML <a> or the shorthands. Shorthand syntax works for referencing external terms as well as locally defined terms. A good compromise is to use shorthands all the time. Lets go through an example where we try to link to link to a few locally defined terms and some external definitions.
<script>
var respecConfig = {
xref: ["webidl", "payment-request"],
};
</script>
<section>
<!--
Here, we reference the "default toJSON steps" concept defined in [[WebIDL]] standard,
and the PaymentRequest interface (WebIDL) defined in [[payment-request]] standard.
-->
<p>[=default toJSON steps=] for the {{PaymentRequest}} interface are ...</p>
<!-- We also define a concept "feline", and an interface "Cat". -->
<p>A <dfn>feline</dfn> has 4 legs and makes sound.</p>
<pre class="idl">
interface Cat {}
</pre>
<!-- ...and we can reference them as: -->
<p>A {{Cat}} is a [=feline=] if it meows.</p>
</section>Read more about linking and other shorthands in the Shorthands Guide.
Specifications typically need to have references to other specifications on which they build to define their own technology. Managing references is a pain, as is linking to them every time that they are mentioned.
ReSpec takes the pain out of this with multiple features that are used together. First, when you need to refer to a given specification in the body of the text, simply do so using [[FOO]], where FOO is the referenced specification's ID. ReSpec uses the context of the reference to work out if the reference is normative or informative. That is, if the reference is in a section marked "informative", or an example, note, or figure, then ReSpec automatically makes the reference non-normative. Otherwise, the reference is treated as normative. ReSpec will replace those with the link the reference and the appropriate markup around it.
If you need a non-normative reference in a normative section, you can use a ? like so:
This is normative and MUST be followed. But, sometimes we need a non-normative
example reference [[?FOO]].You can also link to a specification directly in text by using [[[FOO]]], where FOO is the specification's id. When ReSpec finds the specification in the references database, this gets converted to a link to the specification in the text i.e. <a href="link-to-FOO">FOO Spec Title</a>.
The difference between triple and double brackets syntax is that [[[FOO]]] links directly to the referenced specification, whereas [[FOO]] links to the entry in the "References" section (see below). Normative and informative references work similarly for [[[FOO]]] as they work for [[FOO]], and [[[?FOO]]] can be used to have a non-normative reference in a normative section.
If you ever want to use some text in double brackets that doesn't represent a reference, for example to represent an ECMAScript internal slot, write it as [[\InternalSlot]] (note the leading backslash).
Then, using all the collected references from the document, ReSpec will generate a “References” section with subsections for normative and informative references (when they appear). Naturally, it will also fill in the references themselves, including the relevant bibliographical data, using the conventional markup. (Assuming they appear in our records.).
References are loaded from a shared database that is maintained by a group of volunteers. If you need a reference that is not in the database, then the right thing to do is to submit it for inclusion so that others can benefit from it too. However, if that is not possible then you can make use of the localBiblio configuration option.
The only things you therefore need to know for references are the reference names of the specifications you wish to refer to (as well as to how to add your own to the database). The names are usually rather logical, and most of the time can be guessed. In other cases, you can go look for them in the central bibliographical database that is maintained at specref.org.
There are times when you might need extra links or other important information to appear together with other links at the top of the document.
ReSpec supports adding additional links by specifying an otherLinks property in the configuration. The values for this configuration option are rich and complex, so are detailed in the reference section for otherLinks.
If you wish to add your own additional styles to your document, just use the regular <link> and <style> elements. Be warned however that the W3C styles will always be added after yours, so if you wish to override them you will need to use more specific selectors.
W3C boilerplate is extremely repetitive, but beneath the tedium is a wealth of options and subtle variations that are precisely what makes crafting the boilerplate by hand so hard to get right. This covers options for specification maturity, publication dates, alternatives (editor's drafts, other versions, other formats...), legalese variants, the various W3C specification URLs, the people writing it, information about the working group, and core sections such as Abstract, Status of this Document (SotD), and Conformance.
We will start by using an example of a basic specification very similar to the one used in the previous section.
Specifications typically require having a "short name", which is the name used (amongst other places) in the canonical "https://w3.org/TR/short-name/" URLs. This is specified using the shortName option, as seen in the example above.
W3C documents are produced by groups of some sort: Working Groups (WG), Interest Groups (IG), the TAG, and Community or Business Groups (CG, BG). For simplicity, we will be referring to all of the above as "Working Groups", since one should not be required to understand the many subtleties of the W3C Process in order to write a good specification. Which group a spec belongs to is denoted by the group configuration option. A list of valid group names can be found at: https://respec.org/w3c/groups/.
When these groups release a document, they must include some information that is relevant and specific to them — all of this information is required. Documents produced in other situations (e.g., Submissions, unofficial drafts, etc.) don't require these options.
The result of changing these configuration options can be seen in the "Status of this Document" section.
At any given time a specification must be in a given status. The specStatus option indicates which status that is. Typically, a status has implications in terms of what other options may be required. For instance, a document that is intended to become a Recommendation eventually and that is not the First Public Working Draft (FPWD) of that specification will require previousPublishDate and previousMaturity to be specified.
Note: The process of publishing specifications typically involves releasing multiple versions in a row that have specific dates (so that people can see the evolution, and also for IP reasons). Additionally, some specification statuses involve delimited review periods. These are all specified using date-related options. The format used for all dates is YYYY-MM-DD, except when only year is required, in which case it is a 4-digit number.
The specStatus section list all the possible status values.
Most groups maintain some form of version control system which is exposed over the web so that people can keep track of what edits are being made to a specification in between official releases. It is often useful to point to such documents, including from released specifications, so that people wishing to report issues can make sure that they aren't already fixed, and in general get the very latest version. In fact, Editor Drafts (ED) are often considered to be the most useful reference to have to a group's work.
A specification does not always travel alone. In some cases, there can be an accompanying errata document, which you can specify by providing a URL for it.
Likewise, some groups occasionally find it desirable to produce alternative formats in which people may read the specification. For instance, to access it on an ebook reader you may produce an ePub alternative, or if your specification is intended to be read by printing devices you might use PDF. The alternateFormats option can be used to specify these alternate representations.
If your specification has a test suite (it does, right?), then you can point to it using testSuiteURI. And when your tests have successfully passed in enough implementations, you will want to document that in an implementation report which you can link to using implementationReportURI.
All the best fun in standards brought to you neatly packaged in a single section!
By default, W3C specifications all get the regular W3C copyright notice and archaic document license, except for unofficial documents which are under CC-BY. In some cases however, you will want to modify that.
For all document types other than "unofficial", you can use additionalCopyrightHolders to indicate that the copyright is shared not just amongst the W3C's hosts but also with other organizations (typically this is used for documents developed jointly with another SDO such as the IETF). For unofficial documents, this simply replaces the default CC-BY license.
If you wish the copyright date to span several years rather than just the year matching publishDate (e.g., 2009-2013) then you can use copyrightStart.
At times, the patent situation of a specification may warrant being documented beyond the usual boilerplate. In such cases, use addPatentNote. Its content will get injected at the end of the SotD section (right after the patent policy paragraph).
If you are working on a new version of an existing Recommendation, then it is required that your document point to that previous version. This is done using the prevRecShortname and prevRecURI options, which respectively provide the shortName for the existing Recommendation (e.g., "SVG", as opposed to "SVG2") and its URL. If prevRecURI is not specified but prevRecShortname is, the latter will be used to generate the former by prefixing "https://www.w3.org/TR/" to it. Note however that while in the overwhelming majority of cases this works, it is not recommended to use this approach since if the Recommendation is later Rescinded, the link will be stale. Instead, use the dated link to the Recommendation.
The process for the publication of Notes has been a source of confusion. When producing multiple drafts of a Note in succession, some groups have traditionally simply published them all as Notes one after the other, indicating in the abstract or SotD if they intend to work further on this document or if it is final. Since Notes are not normative and entail no IP concerns, they don't need an elaborate process and this process was perhaps not entirely bad. However, that's not how Notes are commonly handled nowadays.
The currently recommended process for Notes is closer to that which is used for Recommendation Track documents, typically: FPWD -> WD (n times) -> LC -> Note. Given that any group may decide at any time to release a Rec-Track document as a Note instead (often because it has been abandoned), this is Process-correct but it does involve jumping through hoops (notably for IP) that likely should not be needed. It has been explained to me several times why this switch took place, but I can never recall the justification. At any rate, if you are confused with the Note track process but wish to stick to it, you can do so by setting noRecTrack to true.
Best practices may be shown, numbered, and formatted using a div with class practice containing a p > span.practicelab with the practice's title and a p.practicedesc with description of the practice.
This feature is rarely used, and likely needs to be updated. If you wish to use it in anger, please contact me and we can improve support for it.
<div class="practice">
<p>
<span id="some-practice" class="practicelab">Title of the practice</span>
</p>
<p class="practicedesc">
More detailed description of the practice.
</p>
</div>If a section element with id bp-summary is present, then a summary list of best practices will be placed in it, linked to the best practices that have an id on the span element.
<section id="bp-summary"></section>Some of ReSpec's configuration options can be specified in the query string, and they override the options specified in the source. For example, you can override the subtitle by, for example, doing the following: index.html?subtitle=This is a subtitle.
This is useful for quickly overriding configuration options without needing to directly edit the document itself (e.g., for the purpose of exporting a document draft with a different specStatus).