Skip to content

Commit 27cd411

Browse files
shaseleyshaseley
authored
Editorial: Clean up spec markdown (#75)
Editorial: Clean up spec markdown
1 parent 344e410 commit 27cd411

File tree

7 files changed

+249
-290
lines changed

7 files changed

+249
-290
lines changed

‎spec/controlling-tasks.md

+44-51
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,12 @@
1-
Controlling Tasks {#sec-controlling-tasks}
2-
=====================
1+
# Controlling Tasks # {#sec-controlling-tasks}
32

4-
Tasks scheduled through the {{Scheduler}} interface can be controlled with a
5-
{{TaskController}} by passing the {{TaskSignal}} provided by
6-
{{AbortController/signal|controller.signal}} as the
7-
{{SchedulerPostTaskOptions/signal|option}} when calling {{Scheduler/postTask()}}.
8-
The {{TaskController}} interface supports aborting and changing the priority of
9-
a task or group of tasks.
3+
Tasks scheduled through the {{Scheduler}} interface can be controlled with a {{TaskController}} by
4+
passing the {{TaskSignal}} provided by {{AbortController/signal|controller.signal}} as the
5+
{{SchedulerPostTaskOptions/signal|option}} when calling {{Scheduler/postTask()}}. The
6+
{{TaskController}} interface supports aborting and changing the priority of a task or group of
7+
tasks.
108

11-
The `TaskPriorityChangeEvent` Interface {#sec-task-priority-change-event}
12-
---------------------
9+
## The `TaskPriorityChangeEvent` Interface ## {#sec-task-priority-change-event}
1310

1411
<pre class='idl'>
1512
[Exposed=(Window, Worker)]
@@ -27,19 +24,17 @@ The `TaskPriorityChangeEvent` Interface {#sec-task-priority-change-event}
2724
<dl class="domintro non-normative">
2825
<dt><code>event . {{TaskPriorityChangeEvent/previousPriority}}</code></dt>
2926
<dd>
30-
<p>Returns the {{TaskPriority}} of the corresponding {{TaskSignal}} prior to
31-
this `prioritychange` event.
27+
<p>Returns the {{TaskPriority}} of the corresponding {{TaskSignal}} prior to this
28+
`prioritychange` event.
3229

3330
<p>The new {{TaskPriority}} can be read with `event.target.priority`.
3431
</dd>
3532
</dl>
3633

37-
The <dfn attribute for=TaskPriorityChangeEvent>previousPriority</dfn> getter
38-
steps are to return the value that the corresponding attribute was initialized
39-
to.
34+
The <dfn attribute for=TaskPriorityChangeEvent>previousPriority</dfn> getter steps are to return the
35+
value that the corresponding attribute was initialized to.
4036

41-
The `TaskController` Interface {#sec-task-controller}
42-
---------------------
37+
## The `TaskController` Interface ## {#sec-task-controller}
4338

4439
<pre class='idl'>
4540
dictionary TaskControllerInit {
@@ -54,22 +49,21 @@ The `TaskController` Interface {#sec-task-controller}
5449
};
5550
</pre>
5651

57-
Note: {{TaskController}}'s {{AbortController/signal}} getter, which is
58-
inherited from {{AbortController}}, returns a {{TaskSignal}} object.
52+
Note: {{TaskController}}'s {{AbortController/signal}} getter, which is inherited from
53+
{{AbortController}}, returns a {{TaskSignal}} object.
5954

6055
<dl class="domintro non-normative">
6156
<dt><code>controller = new {{TaskController/TaskController()|TaskController}}( |init| )</code>
6257
<dd>
63-
<p> Returns a new {{TaskController}} whose {{AbortController/signal}} is
64-
set to a newly created {{TaskSignal}} with its {{TaskSignal/priority}}
65-
initialized to |init|'s {{TaskControllerInit/priority}}.
58+
<p> Returns a new {{TaskController}} whose {{AbortController/signal}} is set to a newly created
59+
{{TaskSignal}} with its {{TaskSignal/priority}} initialized to |init|'s
60+
{{TaskControllerInit/priority}}.
6661
</dd>
6762

6863
<dt><code>controller . {{TaskController/setPriority()|setPriority}}( |priority| )</code>
6964
<dd>
70-
<p>Invoking this method will change the associated {{TaskSignal}}'s
71-
[=TaskSignal/priority=], signal the priority change to any observers, and
72-
cause `prioritychange` events to be dispatched.
65+
<p>Invoking this method will change the associated {{TaskSignal}}'s [=TaskSignal/priority=],
66+
signal the priority change to any observers, and cause `prioritychange` events to be dispatched.
7367
</dd>
7468
</dl>
7569

@@ -82,12 +76,10 @@ inherited from {{AbortController}}, returns a {{TaskSignal}} object.
8276
1. Set [=this's=] [=AbortController/signal=] to |signal|.
8377
</div>
8478

85-
The <dfn method for=TaskController><code>setPriority(|priority|)</code></dfn>
86-
method steps are to [=TaskSignal/signal priority change=] on [=this=]'s
87-
[=AbortController/signal=] given |priority|.
79+
The <dfn method for=TaskController><code>setPriority(|priority|)</code></dfn> method steps are to
80+
[=TaskSignal/signal priority change=] on [=this=]'s [=AbortController/signal=] given |priority|.
8881

89-
The `TaskSignal` Interface {#sec-task-signal}
90-
---------------------
82+
## The `TaskSignal` Interface ## {#sec-task-signal}
9183

9284
<pre class='idl'>
9385
dictionary TaskSignalAnyInit {
@@ -104,9 +96,9 @@ The `TaskSignal` Interface {#sec-task-signal}
10496
};
10597
</pre>
10698

107-
Note: {{TaskSignal}} inherits from {{AbortSignal}} and can be used in APIs that
108-
accept an {{AbortSignal}}. Additionally, {{Scheduler/postTask()}} accepts an
109-
{{AbortSignal}}, which can be useful if dynamic prioritization is not needed.
99+
Note: {{TaskSignal}} inherits from {{AbortSignal}} and can be used in APIs that accept an
100+
{{AbortSignal}}. Additionally, {{Scheduler/postTask()}} accepts an {{AbortSignal}}, which can be
101+
useful if dynamic prioritization is not needed.
110102

111103
<dl class="domintro non-normative">
112104
<dt><code>TaskSignal . <a method for=TaskSignal lt="any(signals, init)">any</a>(|signals|, |init|)</code>
@@ -137,30 +129,32 @@ A {{TaskSignal}} object has associated <dfn for=TaskSignal>dependent signals</df
137129
of {{TaskSignal}} objects that are dependent on the object for their [=TaskSignal/priority=]), which
138130
is initially empty.
139131

140-
A {{TaskSignal}} object has an associated <dfn for=TaskSignal>dependent</dfn> (a
141-
boolean), which is initially false.
132+
A {{TaskSignal}} object has an associated <dfn for=TaskSignal>dependent</dfn> (a boolean), which is
133+
initially false.
142134

143-
<br>
135+
<hr>
144136

145-
The <dfn attribute for="TaskSignal">priority</dfn> getter steps are to return
146-
[=this=]'s [=TaskSignal/priority=].
137+
The <dfn attribute for="TaskSignal">priority</dfn> getter steps are to return [=this=]'s
138+
[=TaskSignal/priority=].
147139

148-
The <dfn attribute for=TaskSignal><code>onprioritychange</code></dfn> attribute
149-
is an [=event handler IDL attribute=] for the `onprioritychange`
150-
[=event handler=], whose [=event handler event type=] is
151-
<dfn event for=TaskSignal>prioritychange</dfn>.
140+
The <dfn attribute for=TaskSignal><code>onprioritychange</code></dfn> attribute is an [=event
141+
handler IDL attribute=] for the `onprioritychange` [=event handler=], whose [=event handler event
142+
type=] is <dfn event for=TaskSignal>prioritychange</dfn>.
152143

153-
To <dfn for="TaskSignal">add a priority change algorithm</dfn> |algorithm| to a
154-
{{TaskSignal}} object |signal|, [=set/append=] |algorithm| to |signal|'s
155-
[=TaskSignal/priority change algorithms=].
144+
The static <dfn method for=TaskSignal><code>any(|signals|, |init|)</code></dfn> method steps are to
145+
return the result of [=creating a dependent task signal=] from |signals| and |init|.
156146

157-
<br>
147+
<hr>
158148

159149
A {{TaskSignal}} <dfn for=TaskSignal lt="has fixed priority|have fixed priority">has fixed priority</dfn>
160150
if it is a [=TaskSignal/dependent=] signal with a null [=TaskSignal/source signal=].
161151

152+
To <dfn for="TaskSignal">add a priority change algorithm</dfn> |algorithm| to a {{TaskSignal}}
153+
object |signal|, [=set/append=] |algorithm| to |signal|'s [=TaskSignal/priority change algorithms=].
154+
162155
<div algorithm>
163-
The static <dfn method for=TaskSignal><code>any(|signals|, |init|)</code></dfn> method steps are:
156+
To <dfn>create a dependent task signal</dfn> from a [=list=] of {{AbortSignal}} objects |signals|
157+
and a {{TaskSignalAnyInit}} |init|:
164158

165159
1. Let |resultSignal| be the result of <a for=AbortSignal>creating a dependent signal</a> from
166160
|signals| using the {{TaskSignal}} interface and the [=current realm=].
@@ -180,8 +174,8 @@ if it is a [=TaskSignal/dependent=] signal with a null [=TaskSignal/source signa
180174
</div>
181175

182176
<div algorithm>
183-
To <dfn for="TaskSignal">signal priority change</dfn> on a {{TaskSignal}}
184-
object |signal|, given a {{TaskPriority}} |priority|:
177+
To <dfn for="TaskSignal">signal priority change</dfn> on a {{TaskSignal}} object |signal|, given a
178+
{{TaskPriority}} |priority|:
185179

186180
1. If |signal|'s [=TaskSignal/priority changing=] is true, then [=exception/throw=]
187181
a "{{NotAllowedError!!exception}}" {{DOMException}}.
@@ -205,7 +199,6 @@ A [=TaskSignal/dependent=] {{TaskSignal}} object must not be garbage collected w
205199
[=TaskSignal/source signal=] is non-null and it has registered event listeners for its
206200
{{TaskSignal/prioritychange}} event or its [=TaskSignal/priority change algorithms=] is non-empty.
207201

208-
Examples {#sec-controlling-tasks-examples}
209-
---------------------
202+
## Examples ## {#sec-controlling-tasks-examples}
210203

211204
**TODO**(shaseley): Add examples.

‎spec/index.bs

+13
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,19 @@ Include MDN Panels: maybe
6969
top: -0.8em;
7070
left: -0.8em;
7171
}
72+
73+
/* WHATWG-style <hr>s, instead of WICG-style. Specific selector is necessary to override WICG styles. */
74+
:not(.head) > :not(.head) + hr {
75+
display: block;
76+
background: none;
77+
border: none;
78+
padding: 0;
79+
margin: 2em 0;
80+
height: auto;
81+
}
82+
:not(.head) > :not(.head) + hr::before {
83+
content: none;
84+
}
7285
</style>
7386

7487
<pre class=link-defaults>

‎spec/introduction.md

+1-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
Introduction {#intro}
2-
=====================
1+
# Introduction # {#intro}
32

43
<div class="non-normative">
54

‎spec/patches.md

+27-35
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,50 @@
1-
Modifications to Other Standards {#sec-patches}
2-
=====================
1+
# Modifications to Other Standards # {#sec-patches}
32

4-
The HTML Standard {#sec-patches-html}
5-
---------------------
3+
## The HTML Standard ## {#sec-patches-html}
64

75
### `WindowOrWorkerGlobalScope` ### {#sec-patches-html-windoworworkerglobalscope}
86

9-
Each object implementing the {{WindowOrWorkerGlobalScope}} mixin has a
10-
corresponding <dfn for="WindowOrWorkerGlobalScope">scheduler</dfn>, which
11-
is initialized as a new {{Scheduler}}.
7+
Each object implementing the {{WindowOrWorkerGlobalScope}} mixin has a corresponding
8+
<dfn for="WindowOrWorkerGlobalScope">scheduler</dfn>, which is initialized as a new {{Scheduler}}.
129

1310
<pre class='idl'>
1411
partial interface mixin WindowOrWorkerGlobalScope {
1512
[Replaceable] readonly attribute Scheduler scheduler;
1613
};
1714
</pre>
1815

19-
The <dfn attribute for="WindowOrWorkerGlobalScope">scheduler</dfn> attribute's
20-
getter steps are to return [=this=]'s [=WindowOrWorkerGlobalScope/scheduler=].
21-
16+
The <dfn attribute for="WindowOrWorkerGlobalScope">scheduler</dfn> attribute's getter steps are to
17+
return [=this=]'s [=WindowOrWorkerGlobalScope/scheduler=].
2218

2319
### <a href="https://html.spec.whatwg.org/multipage/webappapis.html#definitions-3">Event loop: definitions</a> ### {#sec-patches-html-event-loop-definitions}
2420

25-
Replace: For each [=event loop=], every [=task source=] must be associated with
26-
a specific [=task queue=].
21+
Replace: For each [=event loop=], every [=task source=] must be associated with a specific [=task
22+
queue=].
2723

28-
With: For each [=event loop=], every [=task source=] that is not a
29-
[=scheduler task source=] must be associated with a specific [=task queue=].
24+
With: For each [=event loop=], every [=task source=] that is not a [=scheduler task source=] must be
25+
associated with a specific [=task queue=].
3026

3127
### <a href="https://html.spec.whatwg.org/multipage/webappapis.html#event-loop-processing-model">Event loop: processing model</a> ### {#sec-patches-html-event-loop-processing}
3228

3329
Add the following steps to the event loop processing steps, before step 1:
3430

35-
1. Let |queues| be the [=set=] of the [=event loop=]'s [=task queues=] that
36-
contain at least one <a for="task">runnable</a> <a for="/">task</a>.
37-
1. Let |schedulers| be the [=set=] of all {{Scheduler}} objects whose
38-
[=relevant agent's=] [=agent/event loop=] is this event loop and that
39-
[=have a runnable task=].
40-
1. If |schedulers| and |queues| are both [=list/empty=], skip to the
41-
<code>microtasks</code> step below.
31+
1. Let |queues| be the [=set=] of the [=event loop=]'s [=task queues=] that contain at least one
32+
[=task/runnable=] [=task=].
33+
1. Let |schedulers| be the [=set=] of all {{Scheduler}} objects whose [=relevant agent's=]
34+
[=agent/event loop=] is this event loop and that [=have a runnable task=].
35+
1. If |schedulers| and |queues| are both [=list/empty=], skip to the <code>microtasks</code> step
36+
below.
4237

4338
Modify step 1 to read:
4439

45-
1. Let |taskQueue| be one of the following, chosen in an
46-
[=implementation-defined=] manner:
47-
* If |queues| is not [=list/empty=], one of the [=task queues=] in |queues|,
48-
chosen in an [=implementation-defined=] manner.
49-
* If |schedulers| is not [=list/empty=], the result of
50-
[=selecting the task queue of the next scheduler task=] from one of the
51-
{{Scheduler}}s in |schedulers|, chosen in an [=implementation-defined=]
52-
manner.
53-
54-
Issue: The |taskQueue| in this step will either be a [=set=] of [=tasks=] or a
55-
[=set=] of [=scheduler tasks=]. The steps that follow only [=set/remove=] an
56-
[=set/item=], so they are *roughly* compatible. Ideally, there would be a
57-
common task queue interface that supports a `pop()` method that would return a
58-
plain [=task=], but that would invlove a fair amount of refactoring.
40+
1. Let |taskQueue| be one of the following, chosen in an [=implementation-defined=] manner:
41+
* If |queues| is not [=list/empty=], one of the [=task queues=] in |queues|, chosen in an
42+
[=implementation-defined=] manner.
43+
* If |schedulers| is not [=list/empty=], the result of [=selecting the task queue of the next
44+
scheduler task=] from one of the {{Scheduler}}s in |schedulers|, chosen in an
45+
[=implementation-defined=] manner.
46+
47+
Issue: The |taskQueue| in this step will either be a [=set=] of [=tasks=] or a [=set=] of
48+
[=scheduler tasks=]. The steps that follow only [=set/remove=] an [=set/item=], so they are
49+
*roughly* compatible. Ideally, there would be a common task queue interface that supports a `pop()`
50+
method that would return a plain [=task=], but that would involve a fair amount of refactoring.

‎spec/privacy.md

+1-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
Privacy Considerations {#sec-privacy}
2-
=====================
1+
# Privacy Considerations # {#sec-privacy}
32

43
<div class="non-normative">
54

0 commit comments

Comments
 (0)