Skip to content

Editorial: Revise reference links with bikeshed #1762

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Editorial: Revise reference links with bikeshed #1762

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dc6edbb
Fix links
monica-ch Mar 24, 2025
577357b
rename the texts
monica-ch Mar 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 17 additions & 7 deletions docs/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,12 @@ spec: ecma-262; urlPrefix: https://tc39.es/ecma262/
text: statement
text: declaration

spec: html; urlPrefix: https://html.spec.whatwg.org/
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would strongly discourage adding references to other specs in the "anchors" block like this. If there are definitions in other specs that you need to reference they should be exported from the other spec, rather than worked around like this (and I think even if they aren't exported, you can still link to them without adding them to anchors by explicitly mentioning the spec).

And the same probably also applies to all the existing html fetch and storage references below.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are actually four ways to create a link to other specification:

  1. W3C standard exports, and use it directly [=something=], which might be what you recommend.
  2. the "anchors" block to explain the combination of spec and text to be linked. Then, use it in the .bs file.
  3. [=something=](https://example.com) style link to directly add a link.
  4. <a href="https://example.com">something</a> to directly add a link.

How do you use them differently? Or, are there a style guide or so to explain the recommended way? In #1760 (comment), I suggested to modify 3 and 4 to either of 1 or 2. I am quite sure that brought this change.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As https://speced.github.io/bikeshed/#custom-dfns sort of hints at, the "anchors" block exists to link to specs that are not in the autolinking database. If a spec is in the autolinking database (as w3c specs all should be) you should never need to use it. You can use an explicit <l spec='html'> indication to link to unexported definitions (although you should probably still work with the target spec to make sure the definition does get exported). Maybe link-defaults also work to explicitly link to an unexported definition. But in either case using anchors to link to specs means for one that you won't get any bikeshed warnings if the destination doesn't exist (or stops to exist), and in general just makes the spec way less maintainable.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created #1763 to track this work. Thanks for bringing this.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the reply and sorry for the delay, let me dump what I understood:

  1. use the W3C spec exported dfns (i.e. autolinking database) as much as possible. It allows bikeshed to find out the broken links when it happens.
  2. if it is not possible (e.g. not W3C spec or so), the "anchors" block or the explicit indication can be used as a fallback, but makes maintainability bad because of bikeshed does not find the broken link.

Let me discuss the next actions in the #1763.

type: dfn
text: HTML Standard;
text: set up a window environment settings object; url:set-up-a-window-environment-settings-object
text: creating a new browsing context; url:creating-a-new-browsing-context

spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
type: attribute
urlPrefix: comms.html
Expand Down Expand Up @@ -117,6 +123,10 @@ spec: fetch; urlPrefix: https://fetch.spec.whatwg.org/
text: request; for: Request; url: concept-request-request
text: HTTP fetch; for: /; url: concept-http-fetch

spec: rfc2397; urlPrefix: https://datatracker.ietf.org/doc/html/rfc2397
type: dfn
text: data: URL; url: section-2

spec: rfc8288; urlPrefix: https://tools.ietf.org/html/rfc8288
type: dfn
text: link context; url: section-3.2
Expand Down Expand Up @@ -322,33 +332,33 @@ spec: storage; urlPrefix: https://storage.spec.whatwg.org/

*The rest of the section is non-normative.*

Issue: The behavior in this section is not fully specified yet and will be specified in [HTML Standard](https://html.spec.whatwg.org). The work is tracked by the [issue](https://github.com/w3c/ServiceWorker/issues/765) and the [pull request](https://github.com/whatwg/html/pull/2809).
Issue: The behavior in this section is not fully specified yet and will be specified in [=HTML Standard=]. The work is tracked by the [issue](https://github.com/w3c/ServiceWorker/issues/765) and the [pull request](https://github.com/whatwg/html/pull/2809).

<section>
<h4 id="control-and-use-window-client">The window client case</h4>

A [=window client=] is [created](https://html.spec.whatwg.org/#set-up-a-window-environment-settings-object) when a [=/browsing context=] is [created](https://html.spec.whatwg.org/#creating-a-new-browsing-context) and when it [=navigates=].
A [=window client=] is [=set up a window environment settings object|created=] when a [=/browsing context=] is [=creating a new browsing context|created=] and when it [=navigates=].

When a [=window client=] is [created](https://html.spec.whatwg.org/#set-up-a-window-environment-settings-object) in the process of a [=/browsing context=] [creation](https://html.spec.whatwg.org/#creating-a-new-browsing-context):
When a [=window client=] is [=set up a window environment settings object|created=] in the process of a [=/browsing context=] [=creating a new browsing context|creation=]:

If the [=/browsing context=]'s initial [=active document=]'s [=/origin=] is an [=opaque origin=], the [=window client=]'s [=active service worker=] is set to null.
Otherwise, it is set to the creator [=/document=]'s [=/service worker client=]'s [=active service worker=].

When a [=window client=] is [created](https://html.spec.whatwg.org/#set-up-a-window-environment-settings-object) in the process of the [=/browsing context=]'s [=navigate|navigation=]:
When a [=window client=] is [=set up a window environment settings object|created=] in the process of the [=/browsing context=]'s [=navigate|navigation=]:

If the [=fetch=] is routed through [=/HTTP fetch=], the [=window client=]'s [=active service worker=] is set to the result of the <a lt="Match Service Worker Registration">service worker registration matching</a>.
Otherwise, if the created [=/document=]'s [=/origin=] is an [=opaque origin=] or not the [=same origin|same=] as its creator [=/document=]'s [=/origin=], the [=window client=]'s [=active service worker=] is set to null.
Otherwise, it is set to the creator [=/document=]'s [=/service worker client=]'s [=active service worker=].

Note: For an initial replacement [=navigate|navigation=], the initial [=window client=] that was [created](https://html.spec.whatwg.org/#set-up-a-window-environment-settings-object) when the [=/browsing context=] was [created](https://html.spec.whatwg.org/#creating-a-new-browsing-context) is reused, but the [=active service worker=] is determined by the same behavior as above.
Note: For an initial replacement [=navigate|navigation=], the initial [=window client=] that was [=set up a window environment settings object|created=] when the [=/browsing context=] was [=creating a new browsing context|created=] is reused, but the [=active service worker=] is determined by the same behavior as above.

Note: <a element-attr for=iframe lt=sandbox>Sandboxed</a> <{iframe}>s without the sandboxing directives, `allow-same-origin` and `allow-scripts`, result in having the [=active service worker=] value of null as their [=/origin=] is an [=opaque origin=].
</section>

<section>
<h4 id="control-and-use-worker-client">The worker client case</h4>

A [=worker client=] is <a href="https://html.spec.whatwg.org/#set-up-a-worker-environment-settings-object">created</a> when the user agent [=run a worker|runs a worker=].
A [=worker client=] is [=set up a window environment settings object|created=] when the user agent [=run a worker|runs a worker=].

When the [=worker client=] is created:

Expand All @@ -357,7 +367,7 @@ spec: storage; urlPrefix: https://storage.spec.whatwg.org/
Otherwise, it is set to the [=active service worker=] of the [=environment settings object=] of the last [=set/item=] in the [=worker client=]'s [=/global object=]'s [=owner set=].
</section>

Note: [=Window clients=] and [=worker clients=] with a [data: URL](https://datatracker.ietf.org/doc/html/rfc2397#section-2) result in having the [=active service worker=] value of null as their [=/origin=] is an [=opaque origin=]. [=Window clients=] and [=worker clients=] with a [=blob URL=] can inherit the [=active service worker=] of their creator [=/document=] or owner, but if the [=/request=]'s [=request/origin=] is not the [=same origin|same=] as the [=/origin=] of their creator [=/document=] or owner, the [=active service worker=] is set to null.
Note: [=Window clients=] and [=worker clients=] with a [=data: URL=] result in having the [=active service worker=] value of null as their [=/origin=] is an [=opaque origin=]. [=Window clients=] and [=worker clients=] with a [=blob URL=] can inherit the [=active service worker=] of their creator [=/document=] or owner, but if the [=/request=]'s [=request/origin=] is not the [=same origin|same=] as the [=/origin=] of their creator [=/document=] or owner, the [=active service worker=] is set to null.
</section>

<section>
Expand Down