Update advice to favor the relevant realm over the current one

domenic · annevk · commit 488e201ebf67 · 2016-08-25T08:58:14.000+02:00
Fixes whatwg#1653, and also clarifies and tidies up some stuff while in the area.
diff --git a/source b/source
@@ -87199,15 +87199,16 @@ interface <dfn>NavigatorOnLine</dfn> {
 
     <dt><dfn data-x="concept-current-everything">Current</dfn></dt>
     <dd>This corresponds to the currently-running function object, including built-in user-agent
-    functions which might not be implemented as JavaScript. (It is derived from the <span>current
-    JavaScript realm</span>.)</dd>
+    functions which might not be implemented as JavaScript. (It is derived from the <span
+    data-x="current Realm Record">current JavaScript realm</span>.)</dd>
 
     <dt><dfn data-x="concept-relevant-everything">Relevant</dfn></dt>
     <dd>Every <span>platform object</span> has a <span data-x="concept-relevant-realm">relevant
-    Realm</span>. When writing algorithms, the most prominent <span>platform object</span> whose
-    <span data-x="concept-relevant-realm">relevant Realm</span> might be important is the
-    <b>this</b> value of the currently-running function object. In some cases, there can be other
-    important <span data-x="concept-relevant-realm">relevant Realms</span>, such as those of any
+    Realm</span>, which is roughly the <span>JavaScript realm</span> in which it was created. When
+    writing algorithms, the most prominent <span>platform object</span> whose <span
+    data-x="concept-relevant-realm">relevant Realm</span> might be important is the <b>this</b>
+    value of the currently-running function object. In some cases, there can be other important
+    <span data-x="concept-relevant-realm">relevant Realms</span>, such as those of any
     arguments.</dd>
   </dl>
 
@@ -87271,31 +87272,33 @@ interface <dfn>NavigatorOnLine</dfn> {
 
   <p class="warning">The <span data-x="concept-incumbent-everything">incumbent</span> and <span
   data-x="concept-entry-everything">entry</span> concepts should not be used by new specifications,
-  and we are considering whether we can remove almost all existing uses. See <a
-  href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=26603">Bugzilla bug 26603</a> for <span
+  as they are excessively complicated and unintuitive to work with. We are working to remove almost
+  all existing uses from the platform: see <a
+  href="https://github.com/whatwg/html/issues/1430">issue #1430</a> for <span
   data-x="concept-incumbent-everything">incumbent</span>, and <a
-  href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=27203">Bugzilla bug 27203</a> for <span
+  href="https://github.com/whatwg/html/issues/1431">issue #1431</a> for <span
   data-x="concept-entry-everything">entry</span>.</p>
 
-  <p class="note">Currently, the <span data-x="concept-incumbent-everything">incumbent</span>
-  concept is used in some security checks, and the <span
-  data-x="concept-entry-everything">entry</span> concept is sometimes used to obtain, amongst other
-  things, the <span>API base URL</span> to <span data-x="parse a url">parse a URL</span>, used in
-  scripts running in that <span>unit of related similar-origin browsing contexts</span>.</p>
+  <p>In general, web platform specifications should use the <span
+  data-x="concept-relevant-everything">relevant</span> concept, applied to the object being operated
+  on (usually the <b>this</b> value of the current method). This mismatches the JavaScript
+  specification, where <span data-x="concept-current-everything">current</span> is generally used as
+  the default (e.g. in determining the <span>JavaScript realm</span> whose <code
+  data-x="">Array</code> constructor should be used to construct the result in <code
+  data-x="">Array.prototype.map</code>). But this inconsistency is so embedded in the platform that
+  we have to accept it going forward.</p>
 
-  <p>In general, the <span data-x="concept-current-everything">current</span> concept is what should
-  be used by specifications going forward. There is an important exception, however. If an algorithm
-  is creating an object that is to be persisted and returned multiple times (instead of simply
-  returned to author code right away, and never vended again), it should use the <span
-  data-x="concept-relevant-everything">relevant</span> concept with regard to the object on which
-  the method in question is being executed. This prevents cross-realm calls from causing an object
-  to store objects created in the "wrong" realm.</p>
+  <p>Note that in constructors, where there is no <b>this</b> value yet, the <span
+  data-x="concept-current-everything">current</span> concept is the appropriate default.</p>
 
   <div class="example">
-   <p>The <code data-x="dom-navigator-getBattery">navigator.getBattery()</code> method creates
-   promises in the <span data-x="concept-relevant-realm">relevant Realm</span> for the
-   <code>Navigator</code> object on which it is invoked. This has the following impact: <ref
-   spec=BATTERY>
+   <p>One reason why the <span data-x="concept-relevant-everything">relevant</span> concept is
+   generally a better default choice than the <span
+   data-x="concept-current-everything">current</span> concept is that it is more suitable for
+   creating an object that is to be persisted and returned multiple times. For example, the <code
+   data-x="dom-navigator-getBattery">navigator.getBattery()</code> method creates promises in the
+   <span data-x="concept-relevant-realm">relevant Realm</span> for the <code>Navigator</code> object
+   on which it is invoked. This has the following impact: <ref spec=BATTERY>
 
    <pre>&lt;!-- outer.html -->
 &lt;!DOCTYPE html>
