whatwg / html

HTML Standard
https://html.spec.whatwg.org/multipage/
Other
8.18k stars 2.71k forks source link

Update all "queue a task" invocations to explicitly specify their task source #4506

Open domenic opened 5 years ago

domenic commented 5 years ago

The spec currently is not very precise about how you specify the task source when queuing the task. Lots of parts of the spec do so via nearby sentences such as

The task source for the tasks mentioned above is the DOM manipulation task source

or

The task source for the tasks queued by algorithms in this section is the DOM manipulation task source.

or even

Queue a task to run the iframe load event steps.

The task source for this task is the DOM manipulation task source.

The way in which you have to search around to find the actual task source is frustrating and has led to some confusion in the past. (TODO citation needed.)

https://github.com/whatwg/html/pull/4465 proposes that we explicitly use "Queue a task on the X task source to ..." from now on. This issue tracks updating the rest of the spec to do so, once that lands.


I am tagging this as "good first issue", and help would be appreciated working through it. Once #4465 lands, the work here should consist of:

If someone wants to work on this, I suggest they first try it on one or two sections, then send a pull request, and we can make sure the process works out. Then you can unleash yourself on the rest of the spec :).

gterzian commented 5 years ago

The way in which you have to search around to find the actual task source is frustrating and has led to some confusion in the past. (TODO citation needed.)

A citation from a personal experience:

  1. The whatwg/html/ issue: https://github.com/whatwg/html/issues/3789
  2. The implementation side: https://github.com/servo/servo/issues/21114
domenic commented 5 years ago

Note that #4465 has landed, so if anyone wants to take on this issue, the groundwork is ready :)

littledan commented 5 years ago

Do you have a recommendation for how to define infrequently used or single-use task sources? In PRs I am working on, I am using the new "on the..." wording, but maintain those redundant statements to define the task source in the section. See https://github.com/whatwg/html/pull/4613#discussion_r284048895 and https://github.com/whatwg/html/pull/4571.

Should I put a <dfn> around the first usage? Or define all these infrequently used task sources with the frequently used others above? Something else?

Edit: @TimothyGu pointed out that there are multiple precedents to the inline dfn wording, so I will go with that.