Editorial prep for wrapping algorithms in <div> by jmdyck · Pull Request #11379 · whatwg/html

jmdyck · 2025-06-14T15:35:34Z

Issue #10483 discusses the possibility of wrapping the spec's algorithms in <div algorithm>. To simplify that process, this PR makes some preliminary editorial changes. Specifically, it implements @domenic's suggestions in #10483 (comment) (or at least I think it does).

<dl> (4 commits) Eliminate cases where <dl>-containing-algorithms isn't the best editorial choice.
For these I recommend viewing the diffs with "Hide whitespace" (ignore whitespace differences). Even so, they're still kinda messy.
(Sections: 2.7.1, 8.1.4.2, 8.9.1.1, 8.9.1.2)
<hN> (2 commits) Eliminate cases where an <hN> element contains an algorithm's dfn/name/parameters.
(Sections: 2.6.3.1, 2.7, 7.2.1.3, 7.2.3, 7.2.4, 7.5.7, 8.1.6)
w-nodev (2 commits) Eliminate cases where wrapping would capture a <div w-nodev> tag.
(Sections: 4.13.4, 11.2.2)

/custom-elements.html ( diff )
/structured-data.html ( diff )
/system-state.html ( diff )
/webappapis.html ( diff )
/worklets.html ( diff )

Use markup+wording more like that of ImageData.

Use the single-sentence algorithm form (twice).

Use "The foo getter steps are to ..."

jmdyck · 2025-06-14T15:59:48Z

(Hm, getting build errors, but when I build locally I get Success.)

jmdyck · 2025-06-14T17:33:49Z

The CI errors are from "conformance checker", which is saying that attributes noexport and abstract-op are not allowed on element p. This relates to commit 5, where I changed a bunch of hN to p.

The build process converts:

noexport in source to data-noexport="" in output
abstract-op in source to data-dfn-type=abstract-op in output

but I'm not sure what significance those have.

I'll note that, in the status quo, only the abstract operations in 2.7.* have the abstract-op attribute, not the ones in 7.2.1.3, which makes me wonder how essential it is.

domenic

Thanks for this work!! The biggest issue is that when converting from headings to paragraphs, we need to do a bit of work to make them actual semantic paragraphs. I've left some suggestions on how to do that inline.

domenic · 2025-06-16T04:32:32Z

  </ol>

-  <h6 id="HTMLAllCollection-call">[[Call]] ( <var>thisArgument</var>,  <var>argumentsList</var> )</h6>
+  <p id="HTMLAllCollection-call">[[Call]] ( <var>thisArgument</var>,  <var>argumentsList</var> )</p>


We should flesh this out a bit more to be a proper paragraph. Something like:

<p id="HTMLAllCollection-call">The [[Call]]( <var>thisArgument</var>, <var>argumentsList</var> ) internal method steps for <code>HTMLAllCollection</code> instances are:</p>

Done (in 2.6.3.1, 7.2.3, 7.2.4), with slightly different wording.

Also, I didn't like the fact that the signature was unstyled, so I wrapped it in <dfn> and gave it the ID from the <hN>. But I think this has some side-effects with IDs that I don't entirely understand.

And for WindowProxy and Location, I'm not thrilled with the repetition. For those, maybe it would make sense to instead convert each set to a <dl>.

This looks good at a high level. Can I ask for a slight tweak? Instead of id="", use data-x="". Then, update

with an additional [[Call]] internal method described in the <a href="#HTMLAllCollection-call">section below</a>

to something like with <span data-x="HTMLAllCollection-call">a custom [[Call]] method</span>.

domenic · 2025-06-16T04:36:30Z

+  <p id="structuredserializeinternal" noexport data-lt="StructuredSerializeInternal"
  abstract-op><dfn>StructuredSerializeInternal</dfn> ( <var>value</var>, <var>forStorage</var> [ ,
-  <var>memory</var> ] )</h4>
+  <var>memory</var> ] )</p>


We should move the attributes to the <dfn>. See https://speced.github.io/bikeshed/#dfn-contract .

I also think that this style is just abusing a <p> as a heading. So we should flesh it out to something more like

The StructuredSerializeInternal abstract operation takes as input...

This process can throw an exception, ...

The StructuredSerializeInternal( value, forStorage [, memory ]) steps are:

Similarly below.

I've done this on the first 4 abstract ops in 2.7.3, so you can see how it looks (assuming the build completes). Personally, I prefer the status quo.

More importantly, I belatedly experimented with html-build, and found that wrapping a <div> around these <hN> + <ol> made no difference to the output (other than reproducing the div tags). (There would certainly be problems if we div-wrapped a <hN split-filename=...>, but these cases are nowhere near that.)

So it turns out, I had no reason to bring up <hN> as a problem for <div algo>-wrapping. Consequently, I'd like to withdraw my <hN>-related commits from this PR.

(The build failed, but the files got refreshed anyway.)

I do slightly prefer the conversion you've done here, with two added tweaks:

Always put the <dfn> odn the steps line, instead of the first use.

Add <hr>s between abstract ops.

However I'm very much fine with you withdrawing these commits, to let you escape from the yak-shaving hole more quickly :)

domenic · 2025-06-16T04:38:36Z

-  <h5 id="the-hostensurecanaddprivateelement-implementation"><dfn>HostEnsureCanAddPrivateElement</dfn>(<var>O</var>)</h5>
+  <h5>General host hooks</h5>
+
+  <p id="the-hostensurecanaddprivateelement-implementation"><dfn>HostEnsureCanAddPrivateElement</dfn>(<var>O</var>)</p>


For these I guess the paragraph-ish pattern would be something like

JavaScript contains an implementation-defined HostEnsureCanAddPrivateElement abstract operation. User agents must use the following HostEnsureCanAddPrivateElement( O ) steps: [JAVASCRIPT]

domenic · 2025-06-16T04:40:49Z

+   prefix.</li>
+   <!-- Fetch doesn't actually require the value to start with "Mozilla/5.0 (". -->

+   <li>


This algorithm is written in a weird style. If you want to improve it (not required for this PR!), I think the modern style would be:

Let trail be ...

If the navigator compatibility mode is ..., then return trail.

Assert: the navigator compatibility mode is Gecko.

If trail starts with..., then return ....

Return the prefix of trail up to...

Noted for later.

…nodev> ... in 4.13.4. - Split a paragraph into two. - Change `<span w-nodev>` inside the second `<p>` into `<div w-nodev>` outside it. - Merge two adjacent `<div w-nodev>`.

... in 11.2.2 "Registering a class and invoking its methods"

…uct}

…nguage}

jmdyck · 2025-06-18T03:16:21Z

Okay, I've withdrawn the <hN>-related commits. I think that means all your comments are resolved, obsoleted, or deferred, @domenic. (And the build is successful, yay.)

jmdyck added 4 commits June 13, 2025 20:13

Dissolve <dl> in 2.7.1 "Serializable objects" example

c662e9f

Use markup+wording more like that of ImageData.

Dissolve <dl> in 8.1.4.2 "Fetching scripts"

041d65a

Use the single-sentence algorithm form (twice).

Dissolve <dl> in 8.9.1.1 "Client identification"

c453ed7

Use "The foo getter steps are to ..."

Dissolve <dl> in 8.9.1.2 "Language preferences"

f614b37

Use "The foo getter steps are to ..."

jmdyck mentioned this pull request Jun 14, 2025

Static checker for the spec? #10483

Open

domenic reviewed Jun 16, 2025

View reviewed changes

jmdyck added 4 commits June 17, 2025 22:59

Put CustomElementRegistry's define method entirely within a <div w-…

e5a2c31

…nodev> ... in 4.13.4. - Split a paragraph into two. - Change `<span w-nodev>` inside the second `<p>` into `<div w-nodev>` outside it. - Merge two adjacent `<div w-nodev>`.

Dissolve a <div w-nodev> by adding w-nodev to its 2 children

ab1efec

... in 11.2.2 "Registering a class and invoking its methods"

tweak: Remove "the string" from NavigatorID.{appCodeName,appName,prod…

e45d76f

…uct}

tweak: Delete commented-out NavigatorLanguage.{browserLanguage,userLa…

b019e78

…nguage}

jmdyck force-pushed the pre_algo branch from 6aca57c to b019e78 Compare June 18, 2025 03:10

domenic approved these changes Jun 18, 2025

View reviewed changes

domenic merged commit f9c8085 into whatwg:main Jun 18, 2025
2 checks passed

jmdyck deleted the pre_algo branch June 18, 2025 13:10

jmdyck mentioned this pull request Jun 21, 2025

Markup: Wrap algorithms in <div> tags #11392

Merged

Uh oh!

Conversation

jmdyck commented Jun 14, 2025 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jmdyck commented Jun 14, 2025

Uh oh!

jmdyck commented Jun 14, 2025

Uh oh!

domenic left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jmdyck commented Jun 18, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

jmdyck commented Jun 14, 2025 •

edited by pr-preview Bot

Loading