Shorthands Guide

Shorthands Cheat Sheet

Similar to markdown, shorthands are custom ways of writing things that trigger special behavior in ReSpec. The most commonly used one you've likely seen is [[Reference]]. Shorthands save you time and work: you write a lot less HTML, and ReSpec does all the linking and error checking for you.

Each of these special character combinations, as well as what behavior they trigger, are detailed below.

Note: Only WebIDL identifiers are case sensitive.

Type	Syntax	Examples
WebIDL	{{WebIDLThing}}	{{PaymentRequest}} {{PaymentRequest/show()}}
Concepts in specs	[=normal link=]	[=queue a task=]
Variable in an algorithm	|variable:Type|	Let |p:Promise| be a new {{Promise}}
HTML elements	[^element^]	[^iframe^]
HTML attributes	[^element/attribute^]	[^iframe/allow^]
References	[[shortName]]	[[RFC2119]]
Expansions	[[[#some-id]]]	[[[#example-2]]] expands and links to "Example 2"

By design, we also share a lot of syntax with the BikeShed document processor. This makes it easier for everyone to edit both ReSpec and BikeShed specifications at the same time.

WebIDL {#webidl-shorthands}

On the Web, and in Web Standards, WebIDL is a meta language that we use to define Javascript APIs. Please see our WebIDL Guide. Please see the WebIDL spec for more info.

To link to something in WebIDL, you need to know its identifier. An identifier is the name of the interface, dictionary, or enum.

For example, {{PaymentRequest}} links to the PaymentRequest interface.

You can link attributes, methods, or members by using the interface name, /, and the name of the thing you want to link to. For example, {{PaymentRequest/show()}} links to the show() operation of the PaymentRequest interface.

Examples

Type	Syntax	Examples
Interface, Dictionary, Enum or IDL type	{{Identifier}}	{{PaymentRequest}} {{unrestricted double}} {{long long}}
Attribute	{{Identifier/attributeName}}	{{PaymentRequest/id}}
Operation or Method	{{Identifier/methodName()}} {{Identifier/methodName(someArg)}}	{{PaymentRequest/show()}} {{PaymentRequest/show(detailsPromise)}}
Static Attribute	{{Identifier.attribute}}	{{SomeInterface.someAttribute}}
Static Operation or Static Method	{{Identifier.methodName()}} {{Identifier.methodName(arg)}}	{{URL.createObjectURL()}} {{URL.createObjectURL(obj)}}
Enum Value	{{Identifier/"value"}}	{{PaymentComplete/"success"}}
DOM Exception	{{"Identifier"}}	{{"NotAllowedError"}}

Concepts {#concept-shorthands}

Concepts include: ideas, named algorithms, useful terms, and/or non-webIDL things that are defined in a spec.

Basically, "defined" means that a thing is within <dfn> tags. For example, <dfn>success</dfn> and <dfn>the steps to make a great meal</dfn> are defined concepts.

Linking to concepts

The syntax is [=concept you want to link to=]. For example, [=queue a task=] and [=fire an event=].

To link to a concept in another spec, you need to use the xref configuration option, and simply cite the spec you want to link to:

<p data-cite="HTML DOM">
  You can [=queue a task=] to [=fire an event=] named `"respec-is-amazing"`.
</p>

See xref for more information.

Plural Forms

ReSpec supports automatically linking to plural forms. Thus, [=fruits=] links to the singular concept of fruit, even across specs.

Aliasing concepts

Warning: Aliasing is not recommended.

Always try to adapt your text to a defined concept, and only use an alias if absolutely needed! This keeps specs consistent and keeps things easier to find across specs.

Having said that, sometimes [=convoluted thing =] might be confusing or not make sense in the context of your spec. In such cases, use a pipe | to "alias" a given concept into something that better fits the flow of your spec.

For example, with [=convoluted thing | simpler thing=], simpler thing will be the text on your spec. It will link to convoluted thing.

Another reason is that the definition’s default name does not grammatically fit into your sentence. For example, your definition is [=queue a task=] but you are giving an example of "task queuing". Alias the concept with [=queue a task|task queuing=] (again, don't do this! fix your spec instead or talk to the other editors of the other spec to export a more sane definition 🙇‍♂️).

Examples

Type	Syntax	Examples
Concept	[=concept=]	[=queue a task=]
Aliased concept	[=concept|some alias=] [=convoluted thing|simpler thing=]	[=queue a task|task queuing=]

Scoped concepts

Just as WebIDL interfaces can have methods and attributes, concepts have a very specific relationship to each other.

For example, the definition of a forEach() method for a list behaves differently from the definition of forEach() method for a map: the former operates on a single item, while the letter operates on a key/value pair. To make the relationship clear, we would write [=map/for each=], which is different to, say, [=list/for each=].

To associate a concept with another concept, use data-dfn-for to indicate who or what owns the concept. This tells Respec who or what the concept is "for". See the example below:

A <dfn>car</dfn> has a <dfn data-for="car">engine</dfn>, which burns petroleum.
A <dfn>browser</dfn> has a <dfn data-for="browser">engine</dfn>, which burns
democracy.

Examples

Type	Syntax	Examples
Concept for thing	[=concept/sub concept=]	[=list/for each=] [=map/for each=] [=Document/visible=]

Variables in algorithms {#variable-shorthands}

The syntax is |name|, where name is the name of the variable.

Let |value| be the {{DOMString}} "hello". ... If |value| is not "hello", then
do…

Giving variables data types

Add : and the data type after the variable's name.

For example, |value:DOMString| tells Respec that the variable value is of type {{DOMString}}.

ReSpec tracks declared variables within algorithms, allowing users to click on them to have them highlighted.

This helps readers know where variables were declared and where they are used. If the variable has is type information, ReSpec also propagates this throughout an algorithm. When a reader hovers over a variable, Respec presents information about the variable's type (see an example - GIF, 2.8MB).

Examples

Type	Syntax	Examples
Variable	|variable|	|value|
Variable with a data type	|variable:dataType|	|value:DOMString|

HTML Elements and attributes {#element-shorthands}

To reference HTML elements, use the following syntax: [^tagname^]. * Here, the tagname is a valid HTML tag that is defined in the HTML spec or some other spec that defines the tag.

You can also link to particular content attributes of HTML elements by using a / after then tag name, followed by the name of the attribute you'd like to link to.

For example, [^iframe/allow^] links to the allow attribute for an iframe in the HTML spec.

Examples

Type	Syntax	Examples
Element	[^element^]	[^iframe^]
Element with Content Attribute	[^element/contentAttribute^]	[^iframe/allow^]

Note: To link to an IDL attribute on a HTML element's interface, which is different from an element attribute, you would do, for example {{HTMLIframeElement/allow}}.

Referencing other specifications {#reference-shorthands}

To reference another specification, just write [[FOO]] - where FOO is the short name or id of a specification. If you are don't know the the short name or id, please search for the spec at SpecRef.

Examples

Type	Syntax	Examples
Normal Reference	[[SHORTNAME]]	[[HTML]]
Expanded Reference	[[[SHORTNAME]]]	[[[FULLSCREEN]]], [[[fullscreen API]]] are expanded and rendered as Full Screen API
Informative spec	[[?SHORTNAME]]	Payments can be useful [[?PAYMENT-REQUEST]].
Escaped reference	[[\anything]]	This is not a reference. It is [[\something else]].
Inner-document expansion	[[[#fragment]]]	See [[[#installability-signals]]] is expanded and rendered as See § 2.6 Installability signals.
Multi-page reference	[[SHORTNAME/page#fragment]]	[[SOMESPEC/foo.html#bar]] (Not recommended, use only if you really need it!)