A lot of #ref-for-dom-* spec URLs can be updated

[foolip]

We have a lot of spec URLs like this now: https://dom.spec.whatwg.org/#ref-for-dom-abortcontroller-abortcontroller①

This one in particular should be https://dom.spec.whatwg.org/#interface-abortcontroller or https://dom.spec.whatwg.org/#abortcontroller

I suspect most of these URLs can be updated.

cc @sideshowbarker

[foolip]

I see these URL fragments also show up directly on MDN, making this more important I think: https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#specifications

[sideshowbarker]

We have a lot of spec URLs like this now: https://dom.spec.whatwg.org/#ref-for-dom-abortcontroller-abortcontroller①

Can you explain what the problem is with that spec URL.

That spec URL was very intentionally chosen. So were all the others similar to it. They were chosen because they point direclty to parts of the so-called “domintro” sections of specs that are written specifically for developers — rather than the parts of the spec which are written for implementors.

When a developer follows that https://dom.spec.whatwg.org/#ref-for-dom-abortcontroller-abortcontroller① link from MDN, this is they spec text they see right away — what they are taken to directly:

controller = new AbortController() Returns a new controller whose signal is set to a newly created AbortSignal object.

In other words, that tells developers, right away, what they can expect see when they call new AbortController().

That’s what we want developers to see.

This one in particular should be dom.spec.whatwg.org/#interface-abortcontroller or dom.spec.whatwg.org/#abortcontroller

When a developer goes to https://dom.spec.whatwg.org/#interface-abortcontroller, or to https://dom.spec.whatwg.org/#abortcontroller, what they see first is a WebIDL block. That’s not good, since I think we all agree that we basically don’t want developers looking at WebIDL. WebIDL is for implementors.

I suspect most of these URLs can be updated.

I would object to changing any of them without a specific reason. Every single one of them was carefully and intentionally chosen.

[foolip]

Can you explain what the problem is with that spec URL.

Mainly the "①" in the fragment makes me nervous. These are generated backlinks, and they'll change if any reference to https://dom.spec.whatwg.org/#dom-abortcontroller-abortcontroller (in this example) is added before that domintro box.

Admittedly I also had my implementer goggles on when claiming https://dom.spec.whatwg.org/#interface-abortcontroller is the best link, and linking to domintro boxes seems better if they have stable IDs.

[sideshowbarker]

Mainly the "①" in the fragment makes me nervous. These are generated backlinks, and they'll change if any reference to dom.spec.whatwg.org/#dom-abortcontroller-abortcontroller (in this example) is added before that domintro box.

Yeah I agree that they can end up pointing to a different part of the spec if something is added before the domintro box, and I realized that when I added them. But I didn’t want to further block the addition of spec URLs to BCD on getting that general spec problem resolved first. And I didn’t want to add URLs for the non-developers parts of the spec that we’d just need to definitely replace later with the right URLs for the developer parts of the specs.

Admittedly I also had my implementer goggles on when claiming dom.spec.whatwg.org/#interface-abortcontroller is the best link, and linking to domintro boxes seems better if they have stable IDs.

I think linking to the domintro boxes is better even for now — even though the URLs are not guaranteed to remain stable. In practice, the vast majority of them aren’t likely to change any time very soon. So for now already are getting developers directed to the right parts of the specs.

We can work in parallel with the spec editors on getting stable URLs added to the spec for all of those target sections. I don’t know yet exactly what is the best way to do that — but in the case of the HTML spec, a lot of those domintro targets already have stable -dev URLs. In the case of the HTML spec, I think that’s due because in Wattsi, we added this code:

https://github.com/whatwg/wattsi/blob/main/src/wattsi.pas#L954-L957

            if (Variant <> vDEV) then
               // If this isn't the dev edition, then we need to adjust the ID value to prevent the
               // issue reported at https://github.com/whatwg/html-build/issues/121
               EnsureID(Element, MungeTopicToID(CrossReferenceName + '-dev'))

But for all other WHATWG specs, we use Bikeshed. So maybe there is something we could add to Bikeshed that would facilitate auto-generating spec URLs with stable fragment IDs like that.

Or short of that, specs could be edited to hardcode stable IDs into the source.

Either way, once we have stable fragments for them, I can personally go in and update them all, one by one. I added them all one by one to begin with, so I am well aware of how much work it would be to replace them. It would be time-consuming but it’s not a crazy number. It’s on the order of a few hundred URLs, not even one thousand.

In fact by my count it’s right around 650 total:

spec	number of URLs
fetch.spec.whatwg.org	250
dom.spec.whatwg.org	187
w3c.github.io/IndexedDB	71
streams.spec.whatwg.org	46
wicg.github.io/webusb	37
w3c.github.io/deviceorientation	10
various other	47

If we were able to get Bikeshed updated with some code to auto-generate stable replacements for all those, that same code could be made to spit out some debug output that mapped the old IDs to the new stable ones — and that output could then be used to script the addition of the replacements for them in BCD.

But even if it turns out to not be scriptable, replacing them manually in BCD would be on the order of hours of person time, not days. The numbers for the Fetch and DOM URLs are intimidating, but even those cases would take a few hours each at most. And the rest of those sets would each take maybe 1 hour or less.

Anyway, now that we’re recognizing the issue together, I guess it’s time for me to raise a Bikeshed issue for it — and start looking at the code myself to see if we can make it automatically do something like what we did for wattsi.

[foolip]

Thanks @sideshowbarker for that detailed breakdown! A Bikeshed issue for this sounds great. Here's the domintro box of for the example I've been using: https://github.com/whatwg/dom/blob/f346858acfdb5ce30dfbad4c1383db2245b7f5ff/dom.bs#L1738-L1749

It looks to me like there's actually no Bikeshed support around these, so maybe the answer will be "add IDs". Or do you see some other way we could do this?

[sideshowbarker]

It looks to me like there's actually no Bikeshed support around these, so maybe the answer will be "add IDs". Or do you see some other way we could do this?

For the case of the WHATWG specs and the IndexedDB spec and other specs which are also using class=domintro sections, I think Bikeshed could be updated to do this: When generating an ID for an element:

1. Check if the element has a class=domintro ancestor.
2. If the element has a class=domintro ancestor, then instead of generating a id=ref-for-FooBar①, etc., ID for it, generate an ID in the form id=FooBar-dev.
3. For the purposes of enabling the dfn popups, ensure the id=FooBar-dev element still gets included in the same list of “this references the FooBar dfn” elements that the id=ref-for-FooBar①, etc., elements do.

So that would work for roughly 90% of the cases (the Fetch and DOM specs and other WHATWG specs and the IndexedDB spec). In the other 10% of the cases (e.g., the WebUSB spec) I think those don’t yet have class=domintro sections but do separate the non-normative developer information into separate sentences — and so those specs could be updated to wrap those this-is-for-developers sentences in <span class=domintro>…</span> markup, and then the same proposed new Bikeshed logic would work for those as well.

And since that 10% amounts to only about 65 targets, it wouldn’t be an unreasonable amount of work to manually add that <span class=domintro>…</span> markup to them.

I can imagine there might be a few corner cases where the step #2 ID generation would result in duplicate IDs — but if so, even that could be checked for and handled in the generating code.

Anyway, I think the above should all work. I say that without of course having yet tried to write the code, but I can’t see why it wouldn’t be possible — and it doesn’t seem to me like it would be difficult to write up.

[foolip]

That sounds like a reasonable first plan, let's hope Tab agrees :)

[sideshowbarker]

OK, I created a Bikeshed PR for this at https://github.com/tabatkins/bikeshed/pull/2094.