Skip to content

Commit

Permalink
Add specific Processing headings + minor editorial (#1071)
Browse files Browse the repository at this point in the history
This splits the “Link type "serviceworker"” ≫ “Processing” section into
two sections with separate headings:

* Processing the Link header
* Processing the link element

It also includes a minor editorial change to add the word “or” in a
place where lack of it makes the text ambiguous; this sentence:

> When a serviceworker link’s link element is inserted into a document,
> a serviceworker link is created on a link element that is already in a
> document tree, or the href or scope attributes of the link element of a
> serviceworker link is changed, the user agent should run these steps

...could be read as saying:

> When a serviceworker link’s link element is inserted into a document,
> **then** a serviceworker link is created on a link element...

When what it actually seems to mean is:

> When a serviceworker link’s link element is inserted into a document,
> **or** a serviceworker link is created on a link element...

That “or” is somewhat implied from the rest of the sentence, but this
this change just inserts an explicit “or” to make it more clear.
  • Loading branch information
sideshowbarker authored and jungkees committed Feb 14, 2017
1 parent 69aaeb4 commit e61d12e
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 24 deletions.
6 changes: 4 additions & 2 deletions docs/index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -1731,7 +1731,7 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe
The <dfn id="dfn-link-type-serviceworker" lt="serviceworker link type"><code>serviceworker</code></dfn> keyword may be used with <{link}> elements. This keyword creates an <a>external resource link</a> (<dfn id="dfn-serviceworker-link">serviceworker link</dfn>) that is used to declare a [=/service worker registration=] and its [=service worker registration/scope url=].

<section>
<h3 id="link-element-processing">Processing</h3>
<h3 id="link-header-processing">Processing the <code>Link</code> header</h3>

When a user agent that supports [[!RFC5988]] processes a <code>Link</code> header that contains a <a>serviceworker link</a>, the user agent *should* run these steps:

Expand All @@ -1748,7 +1748,9 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe
1. Let |useCache| be true if the <code>Link</code> header has a <a>target attribute</a> named "<code>usecache</code>", otherwise false.
1. Invoke [=Start Register=] with |scopeURL|, |scriptURL|, a new <a>promise</a>, null, |contextURL|, |workerType|, and |useCache|.

When a <a>serviceworker link</a>'s <{link}> element is <a>inserted into a document</a>, a <a>serviceworker link</a> is created on a <{link}> element that is already <a>in a document tree</a>, or the <{link/href}> or <{link/scope}> attributes of the <{link}> element of a <a>serviceworker link</a> is changed, the user agent *should* run these steps:
<h3 id="link-element-processing">Processing the <{link}> element</h3>

When a <a>serviceworker link</a>'s <{link}> element is <a>inserted into a document</a>, or a <a>serviceworker link</a> is created on a <{link}> element that is already <a>in a document tree</a>, or the <{link/href}> or <{link/scope}> attributes of the <{link}> element of a <a>serviceworker link</a> is changed, the user agent *should* run these steps:

1. If the <{link/href}> attribute is the empty string, abort these steps.
1. Let |client| be the document's [=ServiceWorkerContainer/service worker client=].
Expand Down
48 changes: 26 additions & 22 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -1177,7 +1177,7 @@
}
}
</style>
<meta content="Bikeshed version 017e947f5c8044969eb6c697519bf98b715cf564" name="generator">
<meta content="Bikeshed version d589f866ce24170b0e9661175eeecbffc94d0f9c" name="generator">
<style>/* style-md-lists */

/* This is a weird hack for me not yet following the commonmark spec
Expand Down Expand Up @@ -1424,7 +1424,7 @@
<div class="head">
<p data-fill-with="logo"><a class="logo" href="http://www.w3.org/"> <img alt="W3C" height="48" src="https://www.w3.org/StyleSheets/TR/2016/logos/W3C" width="72"> </a> </p>
<h1 class="p-name no-ref" id="title">Service Workers Nightly</h1>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft, <time class="dt-updated" datetime="2017-02-13">13 February 2017</time></span></h2>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft, <time class="dt-updated" datetime="2017-02-14">14 February 2017</time></span></h2>
<div data-fill-with="spec-metadata">
<dl>
<dt>This version:
Expand Down Expand Up @@ -1614,8 +1614,9 @@ <h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
<li>
<a href="#link-type-serviceworker"><span class="secno">5</span> <span class="content">Link type "<code>serviceworker</code>"</span></a>
<ol class="toc">
<li><a href="#link-element-processing"><span class="secno">5.1</span> <span class="content">Processing</span></a>
<li><a href="#link-element-interface-extensions"><span class="secno">5.2</span> <span class="content">Link element interface extensions</span></a>
<li><a href="#link-header-processing"><span class="secno">5.1</span> <span class="content">Processing the <code>Link</code> header</span></a>
<li><a href="#link-element-processing"><span class="secno">5.2</span> <span class="content">Processing the <code><span>link</span></code> element</span></a>
<li><a href="#link-element-interface-extensions"><span class="secno">5.3</span> <span class="content">Link element interface extensions</span></a>
</ol>
<li>
<a href="#cache-objects"><span class="secno">6</span> <span class="content">Caches</span></a>
Expand Down Expand Up @@ -3584,7 +3585,7 @@ <h3 class="heading settled" data-level="4.9" id="execution-context-events"><span
<h2 class="heading settled" data-level="5" id="link-type-serviceworker"><span class="secno">5. </span><span class="content">Link type "<code>serviceworker</code>"</span><a class="self-link" href="#link-type-serviceworker"></a></h2>
<p>The <dfn data-dfn-type="dfn" data-lt="serviceworker link type" data-noexport="" id="dfn-link-type-serviceworker"><code>serviceworker</code><a class="self-link" href="#dfn-link-type-serviceworker"></a></dfn> keyword may be used with <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/semantics.html#the-link-element">link</a></code> elements. This keyword creates an <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/semantics.html#external-resource-link">external resource link</a> (<dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport="" id="dfn-serviceworker-link">serviceworker link</dfn>) that is used to declare a <a data-link-type="dfn" href="#dfn-service-worker-registration" id="ref-for-dfn-service-worker-registration-50">service worker registration</a> and its <a data-link-type="dfn" href="#dfn-scope-url" id="ref-for-dfn-scope-url-12">scope url</a>.</p>
<section>
<h3 class="heading settled" data-level="5.1" id="link-element-processing"><span class="secno">5.1. </span><span class="content">Processing</span><a class="self-link" href="#link-element-processing"></a></h3>
<h3 class="heading settled" data-level="5.1" id="link-header-processing"><span class="secno">5.1. </span><span class="content">Processing the <code>Link</code> header</span><a class="self-link" href="#link-header-processing"></a></h3>
<p>When a user agent that supports <a data-link-type="biblio" href="#biblio-rfc5988">[RFC5988]</a> processes a <code>Link</code> header that contains a <a data-link-type="dfn" href="#dfn-serviceworker-link" id="ref-for-dfn-serviceworker-link-1">serviceworker link</a>, the user agent <em>should</em> run these steps:</p>
<ol>
<li data-md="">
Expand Down Expand Up @@ -3612,7 +3613,8 @@ <h3 class="heading settled" data-level="5.1" id="link-element-processing"><span
<li data-md="">
<p>Invoke <a data-link-type="dfn" href="#start-register" id="ref-for-start-register-2">Start Register</a> with <var>scopeURL</var>, <var>scriptURL</var>, a new <a data-link-type="dfn" href="http://tc39.github.io/ecma262/#sec-promise-objects">promise</a>, null, <var>contextURL</var>, <var>workerType</var>, and <var>useCache</var>.</p>
</ol>
<p>When a <a data-link-type="dfn" href="#dfn-serviceworker-link" id="ref-for-dfn-serviceworker-link-2">serviceworker link</a>’s <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/semantics.html#the-link-element">link</a></code> element is <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/infrastructure.html#insert-an-element-into-a-document">inserted into a document</a>, a <a data-link-type="dfn" href="#dfn-serviceworker-link" id="ref-for-dfn-serviceworker-link-3">serviceworker link</a> is created on a <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/semantics.html#the-link-element">link</a></code> element that is already <a data-link-type="dfn" href="https://dom.spec.whatwg.org/#in-a-document-tree">in a document tree</a>, or the <code><a data-link-type="element-sub" href="https://html.spec.whatwg.org/multipage/semantics.html#attr-link-href">href</a></code> or <code><a data-link-type="element-sub" href="#element-attrdef-link-scope" id="ref-for-element-attrdef-link-scope-1">scope</a></code> attributes of the <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/semantics.html#the-link-element">link</a></code> element of a <a data-link-type="dfn" href="#dfn-serviceworker-link" id="ref-for-dfn-serviceworker-link-4">serviceworker link</a> is changed, the user agent <em>should</em> run these steps:</p>
<h3 class="heading settled" data-level="5.2" id="link-element-processing"><span class="secno">5.2. </span><span class="content">Processing the <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/semantics.html#the-link-element">link</a></code> element</span><a class="self-link" href="#link-element-processing"></a></h3>
<p>When a <a data-link-type="dfn" href="#dfn-serviceworker-link" id="ref-for-dfn-serviceworker-link-2">serviceworker link</a>’s <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/semantics.html#the-link-element">link</a></code> element is <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/infrastructure.html#insert-an-element-into-a-document">inserted into a document</a>, or a <a data-link-type="dfn" href="#dfn-serviceworker-link" id="ref-for-dfn-serviceworker-link-3">serviceworker link</a> is created on a <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/semantics.html#the-link-element">link</a></code> element that is already <a data-link-type="dfn" href="https://dom.spec.whatwg.org/#in-a-document-tree">in a document tree</a>, or the <code><a data-link-type="element-sub" href="https://html.spec.whatwg.org/multipage/semantics.html#attr-link-href">href</a></code> or <code><a data-link-type="element-sub" href="#element-attrdef-link-scope" id="ref-for-element-attrdef-link-scope-1">scope</a></code> attributes of the <code><a data-link-type="element" href="https://html.spec.whatwg.org/multipage/semantics.html#the-link-element">link</a></code> element of a <a data-link-type="dfn" href="#dfn-serviceworker-link" id="ref-for-dfn-serviceworker-link-4">serviceworker link</a> is changed, the user agent <em>should</em> run these steps:</p>
<ol>
<li data-md="">
<p>If the <code><a data-link-type="element-sub" href="https://html.spec.whatwg.org/multipage/semantics.html#attr-link-href">href</a></code> attribute is the empty string, abort these steps.</p>
Expand Down Expand Up @@ -3661,7 +3663,7 @@ <h3 class="heading settled" data-level="5.1" id="link-element-processing"><span
</div>
</section>
<section>
<h3 class="heading settled" data-level="5.2" id="link-element-interface-extensions"><span class="secno">5.2. </span><span class="content">Link element interface extensions</span><a class="self-link" href="#link-element-interface-extensions"></a></h3>
<h3 class="heading settled" data-level="5.3" id="link-element-interface-extensions"><span class="secno">5.3. </span><span class="content">Link element interface extensions</span><a class="self-link" href="#link-element-interface-extensions"></a></h3>
<pre class="idl highlight def"><span class="kt">partial</span> <span class="kt">interface</span> <a class="nv idl-code" data-link-type="interface" href="https://html.spec.whatwg.org/multipage/semantics.html#htmllinkelement">HTMLLinkElement</a> {
[<a class="nv idl-code" data-link-type="extended-attribute" href="https://html.spec.whatwg.org/multipage/scripting.html#cereactions">CEReactions</a>] <span class="kt">attribute</span> <span class="kt">USVString</span> <a class="nv idl-code" data-link-type="attribute" data-type="USVString" href="#link-scope-attribute" id="ref-for-link-scope-attribute-1">scope</a>;
[<a class="nv idl-code" data-link-type="extended-attribute" href="https://html.spec.whatwg.org/multipage/scripting.html#cereactions">CEReactions</a>] <span class="kt">attribute</span> <a class="n" data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/workers.html#workertype">WorkerType</a> <a class="nv idl-code" data-link-type="attribute" data-type="WorkerType" href="#link-workertype-attribute" id="ref-for-link-workertype-attribute-1">workerType</a>;
Expand Down Expand Up @@ -6923,8 +6925,8 @@ <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="c
<ul>
<li><a href="#dom-serviceworkerregistration-scope">attribute for ServiceWorkerRegistration</a><span>, in §3.2.5</span>
<li><a href="#dom-registrationoptions-scope">dict-member for RegistrationOptions</a><span>, in §3.4</span>
<li><a href="#link-scope-attribute">attribute for HTMLLinkElement</a><span>, in §5.2</span>
<li><a href="#element-attrdef-link-scope">element-attr for link</a><span>, in §5.2</span>
<li><a href="#link-scope-attribute">attribute for HTMLLinkElement</a><span>, in §5.3</span>
<li><a href="#element-attrdef-link-scope">element-attr for link</a><span>, in §5.3</span>
</ul>
<li><a href="#dom-foreignfetchoptions-scopes">scopes</a><span>, in §4.5</span>
<li><a href="#dfn-scope-to-registration-map">scope to registration map</a><span>, in §Unnumbered section</span>
Expand Down Expand Up @@ -7029,13 +7031,13 @@ <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="c
<li><a href="#dfn-use-cache">dfn for service worker registration</a><span>, in §2.2</span>
<li><a href="#dfn-job-use-cache">dfn for job</a><span>, in §Unnumbered section</span>
</ul>
<li><a href="#element-attrdef-link-usecache">usecache</a><span>, in §5.2</span>
<li><a href="#element-attrdef-link-usecache">usecache</a><span>, in §5.3</span>
<li>
useCache
<ul>
<li><a href="#dom-serviceworkerregistration-usecache">attribute for ServiceWorkerRegistration</a><span>, in §3.2.6</span>
<li><a href="#dom-registrationoptions-usecache">dict-member for RegistrationOptions</a><span>, in §3.4</span>
<li><a href="#link-usecache-attribute">attribute for HTMLLinkElement</a><span>, in §5.2</span>
<li><a href="#link-usecache-attribute">attribute for HTMLLinkElement</a><span>, in §5.3</span>
</ul>
<li><a href="#dfn-use">used</a><span>, in §2.4</span>
<li><a href="#dfn-use">uses</a><span>, in §2.4</span>
Expand All @@ -7058,8 +7060,8 @@ <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="c
<li><a href="#dom-clienttype-worker">worker</a><span>, in §4.3</span>
<li><a href="#dom-clienttype-worker">"worker"</a><span>, in §4.3</span>
<li><a href="#dfn-worker-client">worker client</a><span>, in §2.3</span>
<li><a href="#element-attrdef-link-workertype">workertype</a><span>, in §5.2</span>
<li><a href="#link-workertype-attribute">workerType</a><span>, in §5.2</span>
<li><a href="#element-attrdef-link-workertype">workertype</a><span>, in §5.3</span>
<li><a href="#link-workertype-attribute">workerType</a><span>, in §5.3</span>
<li><a href="#dfn-job-worker-type">worker type</a><span>, in §Unnumbered section</span>
</ul>
<h3 class="no-num no-ref heading settled" id="index-defined-elsewhere"><span class="content">Terms defined by reference</span><a class="self-link" href="#index-defined-elsewhere"></a></h3>
Expand Down Expand Up @@ -8456,7 +8458,7 @@ <h2 class="no-num no-ref heading settled" id="issues-index"><span class="content
<li><a href="#ref-for-serviceworkercontainer-service-worker-client-5">3.4.5. getRegistrations()</a>
<li><a href="#ref-for-serviceworkercontainer-service-worker-client-6">3.5. Events</a>
<li><a href="#ref-for-serviceworkercontainer-service-worker-client-7">4.2.5. postMessage(message, transfer)</a>
<li><a href="#ref-for-serviceworkercontainer-service-worker-client-8">5.1. Processing</a>
<li><a href="#ref-for-serviceworkercontainer-service-worker-client-8">5.2. Processing the link element</a>
<li><a href="#ref-for-serviceworkercontainer-service-worker-client-9">Notify Controller Change</a>
</ul>
</aside>
Expand Down Expand Up @@ -9318,43 +9320,44 @@ <h2 class="no-num no-ref heading settled" id="issues-index"><span class="content
<aside class="dfn-panel" data-for="dfn-serviceworker-link">
<b><a href="#dfn-serviceworker-link">#dfn-serviceworker-link</a></b><b>Referenced in:</b>
<ul>
<li><a href="#ref-for-dfn-serviceworker-link-1">5.1. Processing</a> <a href="#ref-for-dfn-serviceworker-link-2">(2)</a> <a href="#ref-for-dfn-serviceworker-link-3">(3)</a> <a href="#ref-for-dfn-serviceworker-link-4">(4)</a> <a href="#ref-for-dfn-serviceworker-link-5">(5)</a>
<li><a href="#ref-for-dfn-serviceworker-link-1">5.1. Processing the Link header</a>
<li><a href="#ref-for-dfn-serviceworker-link-2">5.2. Processing the link element</a> <a href="#ref-for-dfn-serviceworker-link-3">(2)</a> <a href="#ref-for-dfn-serviceworker-link-4">(3)</a> <a href="#ref-for-dfn-serviceworker-link-5">(4)</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="link-scope-attribute">
<b><a href="#link-scope-attribute">#link-scope-attribute</a></b><b>Referenced in:</b>
<ul>
<li><a href="#ref-for-link-scope-attribute-1">5.2. Link element interface extensions</a>
<li><a href="#ref-for-link-scope-attribute-1">5.3. Link element interface extensions</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="element-attrdef-link-scope">
<b><a href="#element-attrdef-link-scope">#element-attrdef-link-scope</a></b><b>Referenced in:</b>
<ul>
<li><a href="#ref-for-element-attrdef-link-scope-1">5.1. Processing</a> <a href="#ref-for-element-attrdef-link-scope-2">(2)</a> <a href="#ref-for-element-attrdef-link-scope-3">(3)</a>
<li><a href="#ref-for-element-attrdef-link-scope-1">5.2. Processing the link element</a> <a href="#ref-for-element-attrdef-link-scope-2">(2)</a> <a href="#ref-for-element-attrdef-link-scope-3">(3)</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="link-workertype-attribute">
<b><a href="#link-workertype-attribute">#link-workertype-attribute</a></b><b>Referenced in:</b>
<ul>
<li><a href="#ref-for-link-workertype-attribute-1">5.2. Link element interface extensions</a>
<li><a href="#ref-for-link-workertype-attribute-1">5.3. Link element interface extensions</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="element-attrdef-link-workertype">
<b><a href="#element-attrdef-link-workertype">#element-attrdef-link-workertype</a></b><b>Referenced in:</b>
<ul>
<li><a href="#ref-for-element-attrdef-link-workertype-1">5.1. Processing</a> <a href="#ref-for-element-attrdef-link-workertype-2">(2)</a>
<li><a href="#ref-for-element-attrdef-link-workertype-1">5.2. Processing the link element</a> <a href="#ref-for-element-attrdef-link-workertype-2">(2)</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="link-usecache-attribute">
<b><a href="#link-usecache-attribute">#link-usecache-attribute</a></b><b>Referenced in:</b>
<ul>
<li><a href="#ref-for-link-usecache-attribute-1">5.2. Link element interface extensions</a>
<li><a href="#ref-for-link-usecache-attribute-1">5.3. Link element interface extensions</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="element-attrdef-link-usecache">
<b><a href="#element-attrdef-link-usecache">#element-attrdef-link-usecache</a></b><b>Referenced in:</b>
<ul>
<li><a href="#ref-for-element-attrdef-link-usecache-1">5.1. Processing</a>
<li><a href="#ref-for-element-attrdef-link-usecache-1">5.2. Processing the link element</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="dfn-fetching-record">
Expand Down Expand Up @@ -9796,7 +9799,8 @@ <h2 class="no-num no-ref heading settled" id="issues-index"><span class="content
<b><a href="#start-register">#start-register</a></b><b>Referenced in:</b>
<ul>
<li><a href="#ref-for-start-register-1">3.4.3. register(scriptURL, options)</a>
<li><a href="#ref-for-start-register-2">5.1. Processing</a> <a href="#ref-for-start-register-3">(2)</a>
<li><a href="#ref-for-start-register-2">5.1. Processing the Link header</a>
<li><a href="#ref-for-start-register-3">5.2. Processing the link element</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="register">
Expand Down

0 comments on commit e61d12e

Please sign in to comment.