UPGRADE: Clarify examples.

Fixes #226.

Author: mikewest

specs/upgrade/index.html

@@ -71,7 +71,7 @@
    <h1 class="p-name no-ref" id="title">Upgrade Insecure Requests</h1>
 
    <h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft,
-    <time class="dt-updated" datetime="2015-07-14">14 July 2015</time></span></h2>
+    <time class="dt-updated" datetime="2015-07-15">15 July 2015</time></span></h2>
 
    <div data-fill-with="spec-metadata">
     <dl>
@@ -168,6 +168,11 @@ <h2 class="no-num no-toc no-ref heading settled" id="contents"><span class="cont
      <ul class="toc">
       <li><a href="#goals"><span class="secno">1.1</span> <span class="content">Goals</span></a>
       <li><a href="#examples"><span class="secno">1.2</span> <span class="content">Examples</span></a>
+       <ul class="toc">
+        <li><a href="#example-subresource"><span class="secno">1.2.1</span> <span class="content">Subresource Upgrades</span></a>
+        <li><a href="#example-navigation"><span class="secno">1.2.2</span> <span class="content">Navigational Upgrades</span></a>
+        <li><a href="#example-failed"><span class="secno">1.2.3</span> <span class="content">Failed Upgrade</span></a>
+       </ul>
       <li><a href="#recommendations"><span class="secno">1.3</span> <span class="content">Recommendations</span></a>
      </ul>
     <li><a href="#key-concepts"><span class="secno">2</span> <span class="content">Key Concepts and Terminology</span></a>
@@ -350,6 +355,9 @@ <h3 class="heading settled" data-level="1.1" id="goals"><span class="secno">1.1.
     <h3 class="heading settled" data-level="1.2" id="examples"><span class="secno">1.2. </span><span class="content">Examples</span><a class="self-link" href="#examples"></a></h3>
 
 
+    <h4 class="heading settled" data-level="1.2.1" id="example-subresource"><span class="secno">1.2.1. </span><span class="content">Subresource Upgrades</span><a class="self-link" href="#example-subresource"></a></h4>
+
+  
     <div class="example" id="example-35db2d27"><a class="self-link" href="#example-35db2d27"></a>
     Megacorp, Inc. wishes to migrate <code>http://example.com/</code> to
     <code>https://example.com</code>. They set up their servers
@@ -405,6 +413,9 @@ <h3 class="heading settled" data-level="1.2" id="examples"><span class="secno">1
     </div>
 
 
+    <h4 class="heading settled" data-level="1.2.2" id="example-navigation"><span class="secno">1.2.2. </span><span class="content">Navigational Upgrades</span><a class="self-link" href="#example-navigation"></a></h4>
+
+  
     <div class="example" id="example-1b5868ed"><a class="self-link" href="#example-1b5868ed"></a>
     Megacorp, Inc. isn’t quite ready to deliver Strict Transport Security
     headers <a data-link-type="biblio" href="#biblio-rfc6797">[RFC6797]</a>, but does want to keep users on secure pages when
@@ -452,6 +463,33 @@ <h3 class="heading settled" data-level="1.2" id="examples"><span class="secno">1
     </div>
 
 
+    <h4 class="heading settled" data-level="1.2.3" id="example-failed"><span class="secno">1.2.3. </span><span class="content">Failed Upgrade</span><a class="self-link" href="#example-failed"></a></h4>
+
+  
+    <div class="example" id="example-962745f2"><a class="self-link" href="#example-962745f2"></a>
+    Tinycorp, Inc. enabled <code><a data-link-type="dfn" href="#upgrade_insecure_requests">upgrade-insecure-requests</a></code> a bit
+    earlier than they should have, as they don’t actually support HTTPS on
+    <code>http://cdn.example.com/</code>. Given the following code:
+
+    
+     <pre>&lt;img src="http://cdn.example.com/image.png">
+</pre>
+     
+
+
+     <p>User agents will upgrade requests, as described in <a href="#example-subresource">§1.2.1 Subresource Upgrades</a>,
+    rewriting the URL as <code>https://cdn.example.com/image.png</code>. As the
+    server doesn’t respond to secure requests, this results in a network error.</p>
+     
+
+
+     <p>There is no fallback in this scenario: the user agent acts just as though
+    the request had been intentionally made, and the request fails.</p>
+     
+  
+    </div>
+
+  
     <h3 class="heading settled" data-level="1.3" id="recommendations"><span class="secno">1.3. </span><span class="content">Recommendations</span><a class="self-link" href="#recommendations"></a></h3>
 
 

specs/upgrade/index.src.html

@@ -243,6 +243,8 @@ <h3 id="goals">Goals</h3>
 
   <h3 id="examples">Examples</h3>
 
+  <h4 id="example-subresource">Subresource Upgrades</h4>
+
   <div class="example">
     Megacorp, Inc. wishes to migrate <code>http://example.com/</code> to
     <code>https://example.com</code>. They set up their servers
@@ -283,6 +285,8 @@ <h3 id="examples">Examples</h3>
     transparently upgraded with no effort on their part.
   </div>
 
+  <h4 id="example-navigation">Navigational Upgrades</h4>
+
   <div class="example">
     Megacorp, Inc. isn't quite ready to deliver Strict Transport Security
     headers [[RFC6797]], but does want to keep users on secure pages when
@@ -316,6 +320,25 @@ <h3 id="examples">Examples</h3>
     won't be upgraded.
   </div>
 
+  <h4 id="example-failed">Failed Upgrade</h4>
+
+  <div class="example">
+    Tinycorp, Inc. enabled <code><a>upgrade-insecure-requests</a></code> a bit
+    earlier than they should have, as they don't actually support HTTPS on
+    <code>http://cdn.example.com/</code>. Given the following code:
+    
+    <pre>
+      &lt;img src="http://cdn.example.com/image.png"&gt;
+    </pre>
+
+    User agents will upgrade requests, as described in [[#example-subresource]],
+    rewriting the URL as <code>https://cdn.example.com/image.png</code>. As the
+    server doesn't respond to secure requests, this results in a network error.
+
+    There is no fallback in this scenario: the user agent acts just as though
+    the request had been intentionally made, and the request fails.
+  </div>
+
   <h3 id="recommendations">Recommendations</h3>
 
   We recommend that authors who wish to ensure that user agents which support