Shorthands Guide

What are shorthands?

• Similar to markdown, shorthands are custom ways of writing things that trigger special behaviour in ReSpec. The most commonly used one you've likely seen is [[Reference]].
• Each of these special character combinations, as well as what behaviour they trigger, are detailed below.
• Note that 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^]
References	[[shortName]]	[[RFC2119]]
Expansions	[[[#some-id]]]	[[[#example-2]]] expands and links to "Example 2"

Why should I use ReSpec’s shorthands?

• Knowing the shorthands saves you time and work: you write a lot less HTML, and ReSpec does all the linking and error checking for you.
• By design, we also share a lot of syntax with our friend, the BikeShed document processor. This makes it easier for everyone to edit both ReSpec and BikeShed specifications at the same time.

---

WebIDL

What is WebIDL?

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

Linking to WebIDL

• 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"}}

Referencing Concepts

What are concepts?

• 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=].

Plural Forms

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

Aliasing concepts

• Please note that 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=]

Examples

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

Concepts belonging to other concepts/things

What are "concepts belonging to other concepts or things?"

• 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 is most probably different from the definition of a forEach() method for a map. 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.

To iterate over a list, use the <dfn data-dfn-for="list">forEach()</dfn>
method, which is defined as...

• Please note that ReSpec does not currently support associating concepts using data-for
  • We are working on adding support. You can track our implementation progress here.

Examples

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

---

Variables in algorithms

Declaring variables in algorithms

• The syntax is |name|, where name is the name of the variable.
• In the example below, value is a declared 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}}.

How does ReSpec annotate variables?

• 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

Examples

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

---

HTML Elements and content attributes

Linking to HTML Elements and Attributes

• 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, you would do, for example {{HTMLIframeElement/allow}}

---

Referencing other specifications

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]]] is expanded and rendered as Fullscreen 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. Similarly with examples. TODO: clarify similarly with examples with Marcos
Multipage reference	[[SHORTNAME/page#fragment]]	[[SOMESPEC/foo.html#bar]] Not recommended. Only if you really need it!

---