Add explanation and examples for early hints

Author: noamr

source

@@ -14341,21 +14341,68 @@ interface <dfn interface>HTMLLinkElement</dfn> : <span>HTMLElement</span> {
    <li><p>Return <var>links</var>.</p></li>
   </ol>
 
-  <h6>Early Hint Headers</h6>
+  <h6>Early Hints</h6>
 
-  <p>Early hint headers allow user-agents to perform some operations, such as speculative loading
-  resources that are likely to be used by the document, before the navigation request is fully
+  <p><dfn>Early hints</dfn> allow user-agents to perform some operations, such as to speculatively
+  load resources that are likely to be used by the document, before the navigation request is fully
   handled by the server and a response code is served. Servers can indicate early hints by serving a
   <span data-x="concept-response">response</span> with a 103 status code before serving the final
   <span data-x="concept-response">response</span>.<ref spec=RFC8297></p>
 
+  <div class="example">
+   <p>For example, given the following sequence of responses:</p>
+   <pre>
+    103 Early Hint
+    Link: &lt;/image.png&gt;; rel=preload; as=image
+   </pre>
+
+   <pre>
+    200 OK
+    Content-Type: text/html
+
+    &lt;!DOCTYPE html&gt;
+    ...
+    &lt;img src="/image.png"&gt;
+   </pre>
+
+   <p>the image will start loading before the HTML content arrives.</p>
+  </div>
+
   <p class="note">Only the first early hint response served during the navigation is handled, and it
-  is discarded if it is succeeded by a cross-origin redirect. In addition to the early hint, the 103
-  response may also contain a <span>Content Security Policy</span> header, which is enforced when
-  processing the early hints.</p>
+  is discarded if it is succeeded by a cross-origin redirect. In addition to the early hint, it is
+  possbile that the 103 response contains a <span>Content Security Policy</span> header, which is
+  enforced when processing the early hints.</p>
+
+  <div class="example">
+   <p>For example, given the following sequence of responses:</p>
+   <pre>
+    103 Early Hint
+    Content-Security-Policy: style-src: self;
+    Link: &lt;/style.css&gt;; rel=preload; as=style
+   </pre>
+
+   <pre>
+    103 Early Hint
+    Link: &lt;/image.png&gt;; rel=preload; as=image
+   </pre>
+
+   <pre>
+    302 Redirect
+    Location: /alternate.html
+   </pre>
+
+   <pre>
+    200 OK
+    Content-Security-Policy: style-src: none;
+    Link: &lt;/font.ttf&gt;; rel=prelad; as=font
+   </pre>
+
+   <p>The font and style would be loaded, and the image will be discarded, as only the first early hint
+   response in the final redirect chain is respected. The late <span>Content Security Policy</span>
+   header comes after the request to fetch the style has already been performed, but the style will
+   not be accessible to the document.</p>
+  </div>
 
-  <p class="example">
-  </p>
 
   <p>To <dfn>process early hint headers</dfn> given a
   <span data-x="concept-response">response</span> <var>response</var> and an
@@ -88787,7 +88834,7 @@ interface <dfn interface>Location</dfn> { // but see also <a href="#the-location
        <li>
         <p>Set <var>uncommittedPreloads</var> to null.</p>
 
-        <p class="note">Preloaded links from <span data-x="process early hint headers">early hint
+        <p class="note">Preloaded links from <span data-x="early hints">early hint
         headers</span> remain in the preload cache after a <span>same origin</span> redirect, but
         get discarded when the redirect is cross-origin.</p>
        </li>
@@ -127445,6 +127492,9 @@ INSERT INTERFACES HERE
    <dt id="refsRFC7578">[RFC7578]</dt>
    <dd><cite><a href="https://tools.ietf.org/html/rfc7578">Returning Values from Forms: multipart/form-data</a></cite>, L. Masinter. IETF.</dd>
 
+   <dt id="refsRFC8297">[RFC8297]</dt>
+   <dd><cite><a href="https://tools.ietf.org/html/rfc8297">An HTTP Status Code for Indicating Hints</a></cite>, K. Oku. IETF.</dd>
+
    <dt id="refsSCREENORIENTATION">[SCREENORIENTATION]</dt>
    <dd><cite><a href="https://w3c.github.io/screen-orientation/">Screen Orientation API</a></cite>, M. Lamouri, M. Cáceres. W3C.</dd>