Like most specification preprocessors, Wattsi accepts as input a language that is based on HTML, but has extra features. We document those features, and how to use them, here.
Wattsi supports semi-automatic cross referencing to <dfn> elements defined elsewhere in the spec. Each <dfn> has a canonical definition string which is used to refer to it; this string must be unique among all <dfn> elements in the spec.
By default, the canonical definition string is the text content of the <dfn> element. It can be customized by using the data-x="" attribute on the definition. This is usually done when the text content is too generic to be unique.
When referencing a definition, you use the <span> or <code> elements. These work in a symmetrical manner: by default, they attempt to cross-reference a term according to their text content, but the term referenced can be overridden by using the data-x="" attribute.
In this example, we use the default canonical definition string for the <dfn>. We later refer to it both by its full name, when that is appropriate, or by using data-x="" combined with a shortened text content, where the context is clear and we don't want to be long-winded.
<p>A <dfn>custom element definition</dfn> consists of...</p>
<p>... These steps will return either a <span>custom element definition</span> or null.</p>
<p>... Eventually an appropriate <span data-x="custom element definition">definition</span> will be
registered.</p>In this example, the <dfn>'s text content ("name") is too common to use the default behavior, so we assign it a custom canonical definition string by using data-x="":
<p>Each <span>custom element definition</span> has a <dfn
data-x="concept-custom-element-definition-name">name</dfn>.</p>
<p>In general, algorithms look up custom elements by any of <span
data-x="concept-custom-element-definition-name">name</span>, ...</p>Note that the choice of "concept-custom-element-definition-name" was arbitrary; any unique string would suffice. However, since the ID for a <dfn> (and thus the URL fragment for any links to it) is derived from its canonical definition string, we try to choose ones that look nice and are meaningful.
Wattsi does not perform any automatic pluralization or stemming. Thus, if you want to refer to a concept by some variant of its canonical definition string, you'll need to use data-x="" on the <span> or <code>:
<p>It may be preferable for <span data-x="custom element definition">custom element
definitions</span> to be...</p>However, canonical definition strings are case-insensitive, so at least you don't have to worry about initial capitalization:
<p><span>Custom element definition</span> is a neat concept.</p>If you need to use a <span> or <code> element without it being a cross-reference, then you can use an empty data-x="" attribute:
<p>In the following document, the element definition for <code data-x="">img-viewer</code> is loaded
asynchronously:</p>Wattsi does not support any database of definitions across all specifications in the ecosystem (like Bikeshed does). To work around this, we have a section in the source which contains "proxy" definitions.
This section is near the top of the source, in an element marked with the w-nooutput attribute, so that its contents do not make their way into the final spec, but are still parsed and processed to assemble the cross-reference database.
These proxy definitions use a new attribute, data-x-href="", which indicates the external URL where the definition was originally located. For example:
<dfn data-x-href="https://infra.spec.whatwg.org/#code-point">code point</dfn>
<dfn data-x-href="https://infra.spec.whatwg.org/#list">list</dfn>Note that we might not use the same name as the defining spec for a term, as in the following example where the original term is too common to be used by itself:
<dfn data-x-href="https://infra.spec.whatwg.org/#list-append">list append</dfn>
<dfn data-x-href="https://infra.spec.whatwg.org/#list-remove">list replace</dfn>We can then use these "proxy definitions" as normal:
<p>Each <code>DOMStringList</code> object has an associated <span>list</span>.</p>
<p><span data-x="list append">Append</span> <var>serializedEntry</var> to
<var>serialized</var>.[[SetData]].</p>Definitions that are meant to be used by other specifications need to be exported using the Bikeshed definition data model. In practice, this means adding data-export="" to the <dfn>, and if appropriate, data-dfn-type="", data-lt="", or data-dfn-for="" attributes. Some examples:
<p>To run steps <dfn data-export="">in parallel</dfn> means...</p><dt><dfn data-x="external resource link" data-lt="external resource link" data-export="">Links to
external resources</dfn></dt><p>The <code>Document</code> has an <dfn data-x="concept-document-https-state" data-export=""
data-dfn-for="Document">HTTPS state</dfn>...</p><dt><dfn data-export="" data-dfn-type="selector"><code
data-x="selector-defined">:defined</code></dfn></dt>For more information on how these are used, see the corresponding sections of the Bikeshed docs:
- Definition Types (
data-dfn-type="") - Changing the Linking Text (
data-lt="") - Namespacing a Definition (
data-dfn-for="")
Note that the syntax those sections describe is different than the data-* attributes used in the general protocol, since those documentation sections are describing how to write Bikeshed source files. But the semantics and value spaces are the same.
To produce the familiar bracketed references to other specifications, e.g.
There are a number of dynamic selectors that can be used with HTML. This section defines when these selectors match HTML elements. [SELECTORS] [CSSUI]
you can use the (nonstandard) <ref> element:
<p>There are a number of dynamic selectors that can be used with HTML. This section defines when
these selectors match HTML elements. <ref>SELECTORS</ref> <ref>CSSUI</ref></p>These match against a bibliography, which is a manually-maintained and sorted <dl> at the end of the source file, identified by having the ID "ref-list". Its entries look like the following:
<dt id="refsSELECTORS">[SELECTORS]</dt>
<dd><cite><a href="https://drafts.csswg.org/selectors/">Selectors</a></cite>, E. Etemad, T. Çelik, D. Glazman, I. Hickson, P. Linss, J. Williams. W3C.</dd>There are currently up to five variants of the specification produced on each build:
- Singlepage
- Multipage
- Developer's edition
- Commit snapshots
- Review drafts
To selectively include or omit content from these variants, you can use the following attributes on any element:
- w-nohtml
- Omitted from singlepage and multipage
- w-nosplit
- Omitted from multipage
- w-nodev
- Ommitted from the developer's edition
- w-nosnap
- Omitted from commit snapshots
- w-noreview
- Omitted from review drafts
- w-dev
- Included only in the developer's edition; a shorthand for
w-nohtml w-nosnap w-noreview
The most important of these for day-to-day work is w-nodev, which is used to exclude content (such as details only interesting to web browser implementers) from the developer's edition.
The w-nooutput attribute will hide the result from all formats. However, its contents will still be processed. This is used for the cross-specification dependencies section.
Wattsi has several of macros used to insert common text fragments. They will act on exact, case-sensitive matches for the following HTML comment strings:
<!-- NON-NORMATIVE SECTION -->inserts a "This section is non-normative." notice. (Example)<!--INSERT FINGERPRINT-->inserts a fingerprint image to indicate a feature that may cause fingerprinting. (See the "Privacy concerns" section)<!--smalltoc-->inserts a table of contents limited to top-level headings<!--toc-->inserts a complete table of contents
Of these, only the first two will be useful for most spec editing.
Comments, apart from the above macros, will be stripped from the output. As such you can use them as notes to yourself or to future editors of the spec.