Clarify usage of "insertion steps" in the HTML Standard #7712

sylph01 · 2022-03-16T08:13:22Z

(partly) closes #2771 .

Introduced the concept "HTML element insertion steps"
Defined what "insertion steps" mean in terms of the HTML standard

TODO:

Check if this approach is correct
For each element that requires a definition of insertion steps, rewrite the current wording using HTML element insertion steps

/embedded-content.html ( diff )
/form-control-infrastructure.html ( diff )
/form-elements.html ( diff )
/images.html ( diff )
/infrastructure.html ( diff )
/media.html ( diff )
/scripting.html ( diff )

- Introduced the concept HTML element insertion steps - Changed the wording from the issue comment so that the term "insertion steps" come earlier in the sentence

domenic

This setup looks good!

source

The insertion steps in the HTML std -> The insertion steps for the HTML std

sylph01 · 2022-03-16T22:43:51Z

Now that the setups are done I'm going to fix the definitions in each element next

This would be needed in 4.8.12.5, 4.10.7, 4.10.17.3

sylph01 · 2022-03-17T13:18:39Z

It seems like we also need to define "HTML element removing steps" and do the same for insertion steps, because section 4.8.12.5, 4.10.7, 4.10.17.3 are written with both "node is inserted" and "node is removed" symetrically. I added the definition @ 53cf966.

As far as I can check from cross-references, all usages of "node is removed" is used symetrically along "node is inserted", so I believe it is fine to fix them altogether in this PR.

The ones in 4.10.7, 4.10.17.3 are trivial so I'm going to fix them next. I might need help/opinions on 4.8.4.3.2 (Reacting to DOM mutations, under img) and 4.12.1.1 (Processing model, under script) because these may involve rewriting other parts around it. I will prepare these questions when I finish the more trivial ones.

sylph01 · 2022-03-17T13:40:34Z

Hmm, 4.10.7 (The select element) wasn't actually that trivial. This one has a list of steps to run that is shared with the "insertion step", "removing step", and also when the option asks for a reset. If we can name the list of things to do when multiple element is absent then all of these can point to the same code block, but I'm not sure if we can introduce a name for something that's only used under a certain section.
If it's fine to introduce a name, it will become something like:

The select HTML element insertion steps, given insertedNode are:

If the select element's multiple attribute is absent, then invoke that select element's selectedness setting algorithm.
...(same for removing steps and option asking for a reset)...

The select element's selectedness setting algorithm is:

Run the first applicable set of steps from the following list:
...(the dl after that)

sylph01 · 2022-03-17T14:59:13Z

Rewrote 4.10.17.3 on my machine but GitHub doesn't allow me to push... (seems like there's issues on the server side)

I would like comments/suggestions on the following matters:

4.8.4.3.2 Reacting to DOM mutations

As this section is written as a list of relevant mutations, taking these two bullets that mention insertion/removing then rewriting as insertion steps doesn't work. I suggest rewriting these two bullets as following:

The element's HTML element insertion steps or HTML element removing steps counts the mutation as a relevant mutation.

then either after the list or under section 4.8.3, add the definition of insertion steps/removing steps:

The source HTML element insertion steps, given insertedNode are:

If insertedNode's next sibling is an img element and their parent is a picture element, then, count this as a relevant mutation for the img element.
...

4.10.7 The select element

... is as commented above.

4.12.1.1 Processing model

My understanding is that events listed here which triggers the user agent preparing the script element happen after a node (the script element itself, or any node or document fragment that is inserted into the script element), which means that these events are not a part of the insertion step and does not need a definition. If any insertion step is to be defined, it would be for the node or document fragment that would be inserted into the script element. Is this correct / does this make sense?

If so, I believe that the usage of [inserted] here can be left as is, and they will refer to that specific node's insertion steps if need be.

domenic

Here are a few nits, will comment on the substantive questions next...

source

domenic · 2022-03-17T16:49:53Z

Very encouraging progress!

If it's fine to introduce a name, it will become something like:

It's definitely fine to introduce definitions that are only used locally :).

The confusing thing about the select section though, is it appears to actually be about option elements, not select elements. I.e., it has the precondition "causing the list of options to gain or lose one or more option elements".

So I think it would actually end up as option HTML element insertion/removal steps, which say something like

If insertedNode's parent is a select element, or its parent is an optgroup element whose parent is a select element, then run that select element's selectedness setting algorithm.

If oldParent is a select element, or its parent is an optgroup element whose parent is a select element, then run that select element's selectedness setting algorithm.

As this section is written as a list of relevant mutations, taking these two bullets that mention insertion/removing then rewriting as insertion steps doesn't work. I suggest rewriting these two bullets as following:

I like this a lot.

4.12.1.1 Processing model

This is trickier, because it isn't necessarily a HTML element that is inserted, and we are so far only making the HTML element insertion rigorous. We don't have a plan for DocumentFragments or text nodes or similar.

I can think of ways to make this rigorous, although they all have some tradeoffs. (E.g., maybe we should add specific steps for handling nodes that are inserted into connected script elements, inside "the insertion steps for the HTML Standard"? But then we've spread out the information about when "prepare a script" runs into two separate places, which makes it harder to read...)

IMO we should leave this for later. If it becomes the only remaining reference to #nodes-are-inserted, then we can change it to link to DOM's insertion steps, which will still be kind of sloppy spec-writing, but it will be a smaller-scoped bit of sloppy spec, and we can tackle it separately.

- "is" -> "are" - remove whitespace before

- Added an insertion step under `source` HTML element insertion steps - Wrote the `img` HTML element insertion steps under 4.8.3 to be consistent with the `source` element

- Introduce "selectedness setting algorithm" - Apply that to insertion steps/removing steps and when asked for a reset

sylph01 · 2022-03-18T09:19:15Z

Thanks for the suggestions! I added the following:

4.10.17.3 Association of controls and forms: 3bda554
4.8.4.3.2 Reacting to DOM mutations: e738216
- I added the definitions of insertion/removing steps under 4.8.3 (the img element) so that it aligns with the source element's definition.
- The source element has a new insertion step from this change. If this needs a specific ordering I can change them.
4.10.7 The select element: 916f7ad

Now I will try to fix the build error I got from the commit that didn't get in yesterday...

- text under `li` needs a `p` - nest `ol` under the `li`

sylph01 · 2022-03-18T10:03:36Z

4.12.1.1 Processing model
This is trickier, because it isn't necessarily a HTML element that is inserted, and we are so far only making the HTML element insertion rigorous.

True, I was missing the case where the thing inserted is not an HTML element.

If we are leaving this part as is as of now then I believe this PR is ready for review. One thing I am worried about is in 4.8.4.3.2 (Reacting to DOM mutations) I had to split the definition of "relevant mutations" across multiple sections (the source element insertion step and the img element insertion step) making it harder to read, but I also think this can't be avoided due to the nature of this definition, and also can be mitigated by using cross-references.

If there's anything else that needs fixing I am ready to fix so please feel free to point them out too. Thanks in advance!

source

domenic · 2022-03-21T17:09:12Z

source

+  <ol>
+    <li><p>If <var>oldParent</var> is a <code>picture</code> element, then, count this as a
+    <span data-x="relevant mutations">relevant mutation</span> for the <code>img</code> element
+    (<var>removedNode</var>).</p></li>


Similarly, let's just say "for removedNode".

Fixed @ 4d87aba

source

domenic · 2022-03-21T17:09:30Z

source

-   data-x="nodes are inserted">element is inserted</span> as a previous sibling.</p></li>
+   <li><p>The element's <span>HTML element insertion steps</span> or <span>HTML element removing
+   steps</span> counts the mutation as a <span data-x="relevant mutations">relevant mutation</span>.
+   </p></li>


No whitespace/newline before closing tags here.

Fixed @ 4d87aba

source

- newline between list items - rewrite img insertion steps to directly mention insertedNode/removedNode - grammar fix - remove redundant dfn data-x - remove extraneous oldParent variable

Use `concept-node-insert-ext` / `concept-node-remove-ext` (in DOM) instead of `nodes are inserted` / `nodes are removed`, as these definitions are now dependent on the DOM Standard definition

- `p` under `li` - then under the same `li` nest the `dl`

domenic

Sorry for the delay in review. I found a couple more issues!

I also pushed a commit with minor fixes to this branch. Please do git pull --rebase before doing any further work and you will get those changes locally.

domenic · 2022-03-23T19:47:17Z

source


   <li><p>The element's parent is a <code>picture</code> element and a <code>source</code> element
-   that was a previous sibling is <span data-x="nodes are removed">removed</span>.</p></li>
+   that was a previous sibling is <span data-x="concept-node-remove-ext">removed</span>.</p></li>


We should be able to convert this into source HTML element removal steps, similar to what you did for the previous bullet.

That's true! Fixed @ 976e48b.

source

domenic · 2022-03-23T19:53:19Z

source

-  <p>When a <span>form-associated element</span> or one of its ancestors <span data-x="nodes are
-  inserted">is inserted</span>, then:
+  <p>The <code>form</code> <span data-x="html element insertion steps">HTML element insertion
+  steps</span>, given <var>insertedNode</var>, are:</p>


So, this change ends up not being correct. It is designed for when any form-associated element is inserted, not for when a form HTML element is inserted.

I think we should move these steps into "the HTML Standard's insertion steps" and "the HTML Standard's removing steps". Then we can add something like

The form owner is also reset by the HTML Standard's insertion steps and removing steps.

Right above "When the user agent is to reset the form owner".

Fixed @ 3c41a2d. Some notes:

I used the concept-node-insert-ext / concept-node-remove-ext data-x here as "the HTML Standard's insertion steps" did not have a data-x associated with it.

About the ordering: I placed the resetting of the form owner to come after each HTML element's HTML element insertion steps.

In the insertion steps, there is a step that would "return", which could be problematic when other steps are added after this happens. If there is a chance that anything could be added after this, we can maybe say "Reset the form owner of the form-associated element, unless the form-associated element's parser inserted flag is set." or something around this line.

Both of those decisions look good to me!

- count as a relevant mutation of an `img` when specific conditions are met

sylph01 · 2022-03-28T07:59:23Z

It looks like checks didn't run on the latest commit. How do I manually run them?

domenic · 2022-03-28T18:21:12Z

It looks like checks didn't run on the latest commit. How do I manually run them?

Sometimes this happens. You can push a small change to make them re-run, or just wait for us to re-run them as part of the review.

domenic

LGTM, thanks so much for your patience!

domenic · 2022-03-28T18:22:38Z

source

+  steps</span>, given <var>removedNode</var> and <var>oldParent</var>, are:</p>
+
+  <ol>
+   <li><p>If <var>removedNode</var>'s next sibling is an <code>img</code> element and


I realized its next sibling is no longer an img element. I'm not sure if there's a rigorous way to fix this, but I will just change it to "next sibling was an img element"

Define HTML element insertion steps and insertion steps for the standard

6103a2f

- Introduced the concept HTML element insertion steps - Changed the wording from the issue comment so that the term "insertion steps" come earlier in the sentence

sylph01 mentioned this pull request Mar 16, 2022

DOM "insertion steps" #2771

Closed

sylph01 marked this pull request as draft March 16, 2022 11:26

domenic reviewed Mar 16, 2022

View reviewed changes

source Show resolved Hide resolved

source Show resolved Hide resolved

source Show resolved Hide resolved

sylph01 added 2 commits March 17, 2022 07:37

Cross-link "local name"

a427b96

Change wording

3856209

The insertion steps in the HTML std -> The insertion steps for the HTML std

sylph01 added 2 commits March 17, 2022 21:34

Change wording of 4.8.2 the source element

2543591

Define HTML element removing steps

53cf966

This would be needed in 4.8.12.5, 4.10.7, 4.10.17.3

Rewrite "4.10.17.3 Association of controls and forms"

3bda554

domenic reviewed Mar 17, 2022

View reviewed changes

source Show resolved Hide resolved

source Outdated Show resolved Hide resolved

sylph01 added 3 commits March 18, 2022 12:53

Minor fixes

4a0e579

- "is" -> "are" - remove whitespace before

Rewrote "4.8.4.3.2 Reacting to DOM mutations"

e738216

- Added an insertion step under `source` HTML element insertion steps - Wrote the `img` HTML element insertion steps under 4.8.3 to be consistent with the `source` element

Rewrote "4.10.7 The select element"

916f7ad

- Introduce "selectedness setting algorithm" - Apply that to insertion steps/removing steps and when asked for a reset

Formatting

98bb9e1

- text under `li` needs a `p` - nest `ol` under the `li`

sylph01 marked this pull request as ready for review March 18, 2022 10:00

domenic reviewed Mar 21, 2022

View reviewed changes

sylph01 and others added 7 commits March 22, 2022 20:21

Minor fixes

4d87aba

- newline between list items - rewrite img insertion steps to directly mention insertedNode/removedNode - grammar fix - remove redundant dfn data-x - remove extraneous oldParent variable

Nest the dl element inside selectedness setting algorithm's ol

a1292b7

Remove "nodes are inserted" and "nodes are removed"

f670528

Use `concept-node-insert-ext` / `concept-node-remove-ext` (in DOM) instead of `nodes are inserted` / `nodes are removed`, as these definitions are now dependent on the DOM Standard definition

Fix improper nesting of dl

ea80634

Re-fix the nesting structure

77cb1cd

- `p` under `li` - then under the same `li` nest the `dl`

Rewrite the selectedness setting algorithm using a single li

ef691bb

Minor fixes

1eadd18

domenic reviewed Mar 23, 2022

View reviewed changes

sylph01 added 2 commits March 24, 2022 21:57

Add source HTML element removing steps

976e48b

- count as a relevant mutation of an `img` when specific conditions are met

Move "form-associated element" insertion/removing steps

3c41a2d

domenic approved these changes Mar 28, 2022

View reviewed changes

domenic added 2 commits March 28, 2022 14:26

Final tweaks

c51e6a0

Indentation tweaks

68cf046

domenic merged commit c4ab67d into whatwg:main Mar 28, 2022

This was referenced May 8, 2024

Why does the handle attribute changes algorithm of popover associate with all HTML elements #10259

Closed

Clean up HTML <-> DOM hooks #10331

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify usage of "insertion steps" in the HTML Standard #7712

Clarify usage of "insertion steps" in the HTML Standard #7712

sylph01 commented Mar 16, 2022 •

edited by pr-preview bot

domenic left a comment

sylph01 commented Mar 16, 2022

sylph01 commented Mar 17, 2022

sylph01 commented Mar 17, 2022 •

edited

sylph01 commented Mar 17, 2022

domenic left a comment

domenic commented Mar 17, 2022

sylph01 commented Mar 18, 2022

sylph01 commented Mar 18, 2022

domenic Mar 21, 2022

sylph01 Mar 22, 2022

domenic Mar 21, 2022

sylph01 Mar 22, 2022

domenic left a comment

domenic Mar 23, 2022

sylph01 Mar 24, 2022

domenic Mar 23, 2022

sylph01 Mar 24, 2022

domenic Mar 28, 2022

sylph01 commented Mar 28, 2022

domenic commented Mar 28, 2022

domenic left a comment

domenic Mar 28, 2022

Clarify usage of "insertion steps" in the HTML Standard #7712

Clarify usage of "insertion steps" in the HTML Standard #7712

Conversation

sylph01 commented Mar 16, 2022 • edited by pr-preview bot

domenic left a comment

Choose a reason for hiding this comment

sylph01 commented Mar 16, 2022

sylph01 commented Mar 17, 2022

sylph01 commented Mar 17, 2022 • edited

sylph01 commented Mar 17, 2022

domenic left a comment

Choose a reason for hiding this comment

domenic commented Mar 17, 2022

sylph01 commented Mar 18, 2022

sylph01 commented Mar 18, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

domenic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sylph01 commented Mar 28, 2022

domenic commented Mar 28, 2022

domenic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sylph01 commented Mar 16, 2022 •

edited by pr-preview bot

sylph01 commented Mar 17, 2022 •

edited