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

JavaScript Configuration Options

addPatentNote

Content that gets inserted at the end of the SotD; used in case the patent situation of your specification requires some specific mentions (e.g. for an ongoing PAG).

additionalCopyrightHolders

For regular documents, this is used to specify that additional parties hold a copyright jointly with W3C on this document. This is typically used when publishing documents that were developed in cooperation with other friendly SDOs such as the IETF. The option is simply some text giving the addition copyright holders. For unofficial documents, this string is used to replace the default CC licence. Example for regular documents and example for unofficial documents.

alternateFormats

An array of objects, each of which has two required fields: uri, for the link to the alternate document, and label, for a human readable string that matches it. This is used to link to alternate formats for the same content (e.g. PDF, ePub, PS).

authors

An array of objects describing the authors of the document. See editors for details on the objects.

charterDisclosureURI

For IG-NOTEs, this must be specified. It is the URL of IP disclosure as per the IG's charter.

copyrightStart

ReSpec knows to include a copyright year that matches the publishDate in the copyright notice. However, for documents developed over a period of several years it is preferable to indicate the first year during which the copyright started by setting this option. Note that this can always be safely specified since if copyrightStart is the same as the publishDate's year it is ignored. See an example.

crEnd

A YYYY-MM-DD date. Documents that are in Candidate Recommendation (specStatus is "CR") are required to indicate a date before which the group guarantees that it will not move to the next step on the track (PR or REC) so that implementers know how long they have. Use this to provide that date.

diffTool

If you want to produce a diffmarked version of your specification, you can use this setting to point to a specific diff tool. It should expect to receive parameters called oldfile, newcontent, and base. By default it is set to http://www.aptest.com/standards/htmldiff/htmldiff.pl.

doRDFa

A setting indicating what version of RDFa to use when annotating the specification with semantic information that is compatible with RDFa Processors as used in the major search engines. Legal values are "1.0" to generate RDFa 1.0-compatible semantic markup, "1.1" to generate RDFa 1.1-compatible semantic markup, and false to indicate that no RDFa information should be included at all. Defaults to "1.1".

The values "1.0" and "1.1" must be included in quotation marks. Also, the value "1.0" should not be used in new specifications - it is only supported for legacy reasons.

edDraftURI

The URI of the Editor's Draft, used in the header. This is required for specStatus = "ED". Any good old URL will do the trick.

editors

An array of objects describing the editors of the document (in order). Each object must follow the structure below:

name
The name of the person. This field is required (and the only required one).
url
The URL for the person, can be used to point to the person's personal site.
company
The company for which the person is working.
companyURL
The URL for the above company.
mailto
An email with which to contact the person.
note
Additional information on the person, often used to indicate a former employer (if the person switched companies during edition) or to clarify that an editor is no longer active even if her name is still attached to the document out of respect for her past contributions.

errata

An URL providing a link to a document capturing errata for the specification.

extraCSS

Deprecated. An array of links to additional style sheets to include. This is one of the very few configuration options that is not backwards-compatible with v1 as support for it was completely removed (because almost everyone used it wrong, and it was not very useful).

implementationReportURI

The URL of the implementation report (documenting how your test suite fares with implementations), gets included in the specification's headers.

includePermalinks

An option that tells the system to add a 'permalink' to each non-introductory section of your document assuming the section or heading element has an explicit ID. The permalink will show as an indicator on the same line as the section heading, by default immediately after the heading text. Options include:

permalinkSymbol
The character(s) to use for the permalink indicator. The default symbol is '§'.
permalinkEdge
Setting this to true tells the system to place the permalink indicator on the right edge of the page. The default is to put the indicator immediately after the heading text.
permalinkHide
Setting this to true tells the system to hide the permalink symbol unless the heading is being hovered over. The default is to show the symbol at all times.

Finally, if you do not want a section to have a permlink indicator, a class of "nolink" on that heading will exclude it.

lcEnd

A YYYY-MM-DD date. Documents that are in Last Call (specStatus is "LC") are required to indicate an end date for the review period. Use this to provide it.

localBiblio

If you need to include a one-off reference that isn't in the SpecRef database or if you need to override an existing reference with specific content, then you can use this configuration option.

Its value is an object that has the reference names as its keys and specific objects describing the references as its values. Keys include authors (an array of names), href (a link to the reference), title (the reference's name), status (its maturity as a standard), and publisher (the organisation publishing it). Only title is required.

    localBiblio:  {
        "WEREWOLF": {
            title:    "Tremble Puny Villagers"
        ,   href:     "http://w3.org/werewolf"
        ,   authors:  [
                "Dominique Hazael-Massieux"
            ,   "Doug the Simple Villager"
            ]
        ,   status:   "RSCND"
        ,   publisher:  "W3C"
        }
    }
  

logos

logos gives you the ability to override the standard W3C logo with one or more other logos.

The logos property takes an array that contains a set of objects. Each of these objects contains at least a `src` or an `alt` property, along with optional `height`, `width`, `id`, and `url` properties that can be used to further customize the included logo.

The above makes more sense when seen in an example:

logos: [
   {
      src: 'http://example.com/logo.gif',
      href: "http://example.com",
      alt: "example.com",
      width: 100,
      height: 42,
      id: 'something'
   }
]

This causes the standard logo to replaced with

<p>
  <a href="http://example.com">
    <span id="something">
      <img src="http://example.com/logo.gif" width='100' height='42' alt='example.com' />
    </span>
  </a>
</p>

maxTocLevel

A number indicating the maximum depth of the table of contents, in case you wish to limit it so as to keep it more readable. Defaults to 0 which includes all levels.

noLegacyStyle

A boolean indicating that automatically generated legacy DOM-style sections (Attributes and Methods) following the WebIDL blocks are removed. Setting this boolean true brings the document style closer to that of used by Anolis. If you are migrating a document that uses the legacy DOM-style, you need to manually move the prose from Attributes and Methods sections and put it below the IDL markup definition into its own paragraph(s). Additionally, you need to link the IDL members back to the prose; ReSpec automatically generates fragment identifiers that start with #widl-, and you must manually add corresponding ids to appropriate parts in your prose.

noRecTrack

A boolean indicating that a document is not intended to become a Recommendation. Used for Notes while in unfinished maturity states.

noTOC

When set to true, no table of contents is generated.

otherLinks

otherLinks gives you the ability to add additional links to the header of the document. This is useful if you want to link to other resources, like a news feed, a repository, or a relevant website.

The otherLinks property takes an array that contains a set of objects. Each of these objects contains a `key` and a `data` property. The `key` is the text that will contain the links to the relevant resources. The `data` is another array of objects that contain the data describing the resource (with the properties `value` which is a string, and `href` which is the URL you want to link to).

The above makes more sense when seen in an example:

otherLinks: [{
    key: "Version history:",
    data: [{
      value: "Commit History.",
      href: "https://github.com/ResponsiveImagesCG/ri-usecases/commits/gh-pages"
 }, {
      value: "Github commits on Twitter.",
      href: "https://twitter.com/respimg_commits"
 }]

Becomes:

Version Histroy:
Commit History.
Github commits on Twitter:
Github commits on Twitter.

prevED

Sometimes it happens that a document is moved in the version control system, passed from one group to another, or split into several smaller documents. In such cases since the version control information is harder to find, this option can be used to point to a previous Editor's Draft. Rarely used.

prevRecShortname

If you are working on a new version of an existing Recommendation, use this to indicate what its shortName was.

prevRecURI

If you are working on a new version of an existing Recommendation, use this to indicate what its URL was.

If a prevRecURI is not specified but prevRecShortname is, the latter will be used to generate the former by prefixing "http://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.

previousDiffURI

When producing a diffmarked version, ReSpec uses the previousURI as the old version by default. Use this configuration option if you wish to override this to a specific URL.

previousMaturity

A YYYY-MM-DD date. When a previousPublishDate is specified, this is typically required as well in order to generate the "Previous Version" link since it includes an indication of the previous document's maturity level, which cannot be guessed. The values are the same as for specStatus. Please note that some values of this option make no sense depending on the current document specStatus but that the rules for validating consistency are convoluted enough that ReSpec does not try to check them. If you pick the wrong value (typically by forgetting to change it), the Link Checker will most likely catch the error before publication (the same goes for previousPublishDate).

previousPublishDate

A YYYY-MM-DD date. When there is a previous release of a given specification, this is used to generate the "Previous Version" link. It is required for Recommendation Track documents.

previousURI

Not normally required, as this is typically defaulted properly for you. However, if the previous version of a document happened not to live on the W3C site (or not at a regular location) then you can set this.

processVersion

ReSpec knows to include an indication of the W3C process under which the document was developed. This indication appears at the end of the Status of This Document section. By default it indicates the new "2014" process. You can override this by setting the processVersion configuration option to anything other than "2014". The previous process document, for example, was "2005".

publishDate

A YYYY-MM-DD date. The publication date of the present document. For documents that are in flux, such as Editor's Drafts or unofficial documents, this is best left unspecified as ReSpec will use the document's last modification date (as provided by the browser) in order to set this. For documents intended for official publication, this is normally required.

Note that the last modified date provided by the browser can at times be wrong. This often happens when the server is itself providing a broken value, or at times when differences in timezones (that are not always well accounted-for by servers or browsers) cause the day to shift by one.

refNote

The text of a note to include at the beginning of the References section.

shortName

The specification's "short name", which is the name used in W3C URLs such as "http://www.w3.org/TR/short-name" (and several other generated URLs).

specStatus

The specification's type, which can be a maturity level (e.g. Working Draft) if it is on a publication track but can also take other values for other types of documents (e.g. "unofficial" for, well, unofficial documents).

value meaning
base Just the basic template, not a specification. Use this for public documentation produced by a group that has no current clear plan to be officially published. Example
MO Member-Only Document. Similar to base, but for documents that need to be clearly flagged as being restricted in access to W3C Members. This is rarely, if ever, useful. Example
unofficial An unofficial draft. Use this if you're producing a document outside of W3C but want to use styles that match those of W3C specifications, for instance to propose a new document while hosting it on your own server. Note that this automatically licences the content under CC-BY v3.0. If you want a different copyright, you will need to set the various copyright configuration options. Example
ED Editor's Draft. Use this for documents that are maintained in the group's own repository. Requires edDraftURI to be specified. This is the default value. Example
FPWD First Public Working Draft. Example
WD Working Draft. Requires previousPublishDate and previousMaturity. Example
LC Last Call Working Draft. Requires previousPublishDate, previousMaturity, and lcEnd. Example
CR Candidate Recommendation. Requires previousPublishDate, previousMaturity, and crEnd. Example
PR Proposed Recommendation. Requires previousPublishDate and previousMaturity. Example
PER Proposed Edited Recommendation. Requires previousPublishDate and previousMaturity. Example
REC Recommendation. Requires previousPublishDate and previousMaturity. Example
RSCND Rescinded Recommendation. Requires previousPublishDate and previousMaturity. I wish there were more of those. The style is so edgy. Example
NOTE Deprecated. A note. It is unclear to me how this differs from the more specific WG-NOTE and friends. Do not use this. Example
FPWD-NOTE First Public Working Draft of a Note (of any kind, it would seem). Example
WG-NOTE Working Group Note. Example
BG-DRAFT, BG-FINAL Business Group Draft or Final Report. Example Draft Report
CG-DRAFT, CG-FINAL Community Group Draft or Final Report. Example Draft Report
IG-NOTE Interest Group Note. For this, charterDisclosureURI is required. Example
Member-SUBM Member Submission. Note that ReSpec uses the default W3C copyright for this, but that you are entitled to retain your own copyright instead of transferring it to W3C. Use the copyright options for this. Example
Team-SUBM Team Submission. Example
XGR Deprecated. Incubator Group Report. Requires xgrGroupShortName and xgrDocShortName. Example
draft-finding Draft TAG Finding. If you are one of the Nine and working on a Finding, this is for you. Note that for findings, ReSpec currently does not support very robust SotD generation (there don't seem to be solid rules for what constitutes a valid Finding SotD) so you'll have to specify your own. If there are rules that could be used, please report a bug. ReSpec further assumes some conventions for finding URLs that are not consistent throughout all of the TAG's repository, specifically that all findings live in "http://www.w3.org/2001/tag/doc/", that the latest version is at "http://www.w3.org/2001/tag/doc/shortName", and that the dated versions are at "shortName-YYYYMMDD". Example
finding TAG Finding. Same as above, but final. Example

subjectPrefix

If you wish feedback to your mailing list about this specific document to have a specific prefix subject in its subject line, then specify this (including the [ and ] if you want them). The various of the heading matter that refer to the mailing list will use this information.

subtitle

A simple string that will be used as a subtitle for the specification, right under the title.

testSuiteURI

The URL of your test suite, gets included in the specification's headers.

tocIntroductory

A boolean which when set to true will cause the introductory sections to also show up in the table of contents. This is rarely needed, but some groups prefer to have it that way.

wg

The full public name of the group, including "Working/Interest/Incubator/etc. Group" as applicable. E.g. "Device APIs Working Group".

wgPatentURI

The URL of the public list of patent disclosures for the group, e.g. "http://www.w3.org/2004/01/pp-impl/43696/status".

PLEASE NOTE: it is extremely easy to cut and paste this value from somewhere else and to fail to notice that you are using the wrong value. Given the legal patent implications in pointing to the wrong resource, please triple-check that you are using the link relevant to your group. In order to find your group's link, go to http://www.w3.org/2004/01/pp-impl/, locate your group, and click on its "(Status)" link.

wgPublicList

The short name of the mailing list on which the group conducts its public discussion. E.g. "public-device-apis".

wgURI

The URI to the public page of the group. E.g. "http://w3.org/2009/dap/".

xgrDocShortName

Deprecated. The short name of the group report, e.g. "mbui". Since XGs typically produce a single report, it is typical to use the same short name for the report as is used for the group, therefore this option defaults to xgrGroupShortName.

xgrGroupShortName

Deprecated. The short name of the group, as included in its URI, e.g. "model-based-ui". This is required for XGs.

Elements

figure

Specification figures are indicated using the figure element, with a nested figcaption. They can occur anywhere.

A Table of Figures is generated and inserted in the document if you include an element with ID tof.

Figures can be automatically linked to using a link pointing to their ID with no content (e.g. <a href='#foo-figures'></a>).

section

Specification sections are indicated using the section element. They can be nested arbitrarily in order to indicate sub-sections.

The first h* child element is taken to be the section's title. You do not need to worry about nesting depth: ReSpec will take any element in the h1-h6 range and renumber it to match the section's nesting depth correctly. It is a common convention (though by no means a requirement) to use h2 for all sections.

If you nest deeper than the h6 level, apart from having a hard-to-navigate document you will keep getting h6 elements.

Section can be automatically linked to using a link pointing to their ID with no content (e.g. <a href='#foo-section'></a>).

Special sections

Some sections with specific IDs have special meanings.

abstract
Required. The specification's abstract, which should contain a paragraph. You shouldn't include the "Abstract" title.
bp-summary
If present, its content will be set to a summary of the list of best practices described in the document.
conformance
Specifications often have "Conformance Requirements", which are made of free-form text and some boilerplate mentioning RFC 2119. A section with this ID will add the title and the boilerplate, while keeping the content you include in it. The added paragraphs are essentially boilerplate but are useful in clarifying the normative status of specific sections and listing the RFC 2119 keywords that are normally used for testable assertions in the specification. The part that you write is dedicated to providing more information about how conformance works for your given specification, it is often used to define product conformance classes. If testable assertions and conformance classes sound like gibberish to you, it is highly recommended that you read http://www.w3.org/TR/test-methodology/. In fact, even if you understand what those are but haven't read this document, go read it.
sotd
Required. The "Status of this Document" section. Obviously, you do not need to include the endless reams of boilerplate that that section normally contains: that's generated for you. However, the PubRules require that part of that boilerplate be "a custom paragraph". The content you include in this section is therefore injected as that custom paragraph (you can have several, in fact any markup you want is used). Don't spend too much time putting together the best of your prose for this, it is almost certain that no one will ever read it.

title

The title element is left untouched, but its content is used to also set the h1 title for the specification.

Attributes

data-include-format

Data is normally included as HTML (injected into the DOM as such) but there are time when you want to include content as text. If so, set this attribute to text. That is the only supported value (you can also use html, but that's the default behaviour).

data-include-replace

By default inclusion happens by placing the content inside the including element. At time, you will actually want the element to be replaced by the inclusion. If so, simply set this attribute to any truthy value.

data-include-sync

Inclusion is normally asynchronous, which means that the content may or may not get further processed by ReSpec depending on the point at which it gets inserted (which isn't deterministic). If you need to ensure that content gets injected before the rest of the pipeline runs, set this to any truthy value.

Be warned that there is a steep performance penalty in doing so, since all ReSpec processing will effectively pause until the content has been fully fetched and inserted.

data-include

A URL pointing to a resource, relative to the including document. The content will get included as a child of the element on which the inclusion is performed (unless data-include-replace is used, in which case it replaces the element), replacing its existing content.

The include filter runs recursively so that included content that contains data-include attributes will work (just be sure not to build a circular loop in there, ReSpec won't detect it if only because it doesn't mind if you're shooting yourself in the foot).

By default the inclusion is asynchronous, which means that the included content may or may not be further processed by ReSpec after it gets added to the DOM (the result won't be deterministic and so is only useful if the content is not meant to be further processed). If you wish to ensure that ReSpec processing is applied to the content, use data-include-sync

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.

data-merge

This is a list of white space separated WebIDL identifiers that you wish to have merged into the current WebIDL section, so as to have them all described together rather than as separate sections. This is typically used to bring the definition for one or more dictionaries into the same section as an interface.

data-oninclude

Behaves in the same way as data-transform, applied to the included content. The functions receive a third parameter giving the URL of the loaded content.

data-transform

This is a list of white space separated JavaScript function names that will be called in turn in order to transform the content inside the given element. The functions need to be globally available.

Each function gets called with the ReSpec utils object and a string of the content to transform.

Each function must return the transformed content.

dir

ReSpec defaults the dir attribute on your root element to ltr. If you are writing in a language that requires a different directionality, simply set this attribute to another value.

lang

ReSpec defaults the lang attribute on your root element to en. If you are writing in another language, simply set this attribute to another value.

Classes

appendix

Marks a section as being an appendix (which will be numbered with letters). Note that this does not make it informative as some appendices can contain normative material.

It is important to know that every section following an appendix will also be made to be an appendix.

example

Marks a pre or div as being an example. This provides it with a specific styling and header.

highlight

Indicates that an example or a code fragment should be syntax highlighted. The syntax highlighter will do its best to guess how to perform highlighting without knowing the language.

If needed you can tweak the syntax highlighting styles in order to obtain better results.

informative

Used for regular sections or appendices that are not meant to contain normative material. It will automatically preface its content with the well-know “This section is non-normative” paragraph.

introductory

When set on a section indicates that it is meant as introductory material that need not be linked to from the table of contents. The abstract, SotD, and ToC sections automatically fall into this category (but you need not worry about flagging them as such).

If you do wish all the introductory sections to be present in the ToC, see tocIntroductory.

practice

A div containing a best practice description.

practicedesc

A paragraph containing the description of a best practice, inside a practice description.

practicelab

A span containing the title of a best practice, inside a practice description.

remove

If you want to include content that is used during the generation of the specification but must be removed from the output, then add the remove class to it. That is used for instance for all the script elements that pull in ReSpec and define its configuration.

Events

ReSpec has a general event publish / subscribe system. Developers extending the system can do so by subscribing to events they care about and performing actions when those events are fired. The interfaces and events are documented in this section.