Add the Selector Scoping section, explaining the difference between the two different types of selector scoping.

--HG--
extra : rebase_source : cd60b6ad69ead278b5ff7e6bd77dae3951390c58

Author: tabatkins

selectors4/Overview.html

@@ -183,6 +183,9 @@ <h2 class="no-num no-toc" id=contents>Table of Contents</h2>
 
      <li><a href="#invalid"><span class=secno>3.8. </span> Invalid Selectors
       and Error Handling</a>
+
+     <li><a href="#selector-scoping"><span class=secno>3.9. </span> Selector
+      Scoping</a>
     </ul>
 
    <li><a href="#logical-combination"><span class=secno>4. </span> Logical
@@ -1367,6 +1370,50 @@ <h3 id=invalid><span class=secno>3.8. </span> Invalid Selectors and Error
    that the last rule be dropped in favor of Media Queries-style
    error-handling.
 
+  <h3 id=selector-scoping><span class=secno>3.9. </span> Selector Scoping</h3>
+
+  <p> In some instances, selectors may be "scoped", or limited in some way to
+   apply only within a section of the document.
+
+  <p> There are two distinct ways in which selectors can be scoped:
+
+  <dl>
+   <dt><dfn id=scope-contained0>scope-contained</dfn>
+
+   <dd> When a selector is <a
+    href="#scope-contained0"><i>scope-contained</i></a>, it matches as if the
+    elements outside of its scope did not exist. In other words, it acts like
+    the scope defines a sub-document within which the selector is matched.
+
+   <dt><dfn id=scope-limited>scope-limited</dfn>
+
+   <dd> When a selector is <a href="#scope-limited"><i>scope-limited</i></a>,
+    it only matches if the target is within the scope. The rest of the
+    document is still acknowledged and can match all but the last part of the
+    selector; only the target (the element matched by the last compound
+    selector in the selector) is required to be within the scope.
+  </dl>
+
+  <div class=example>
+   <p> The <code>document.querySelector()</code> function defined in <a
+    href="#SELECTORS-API2"
+    rel=biblioentry>[SELECTORS-API2]<!--{{SELECTORS-API2}}--></a> allows the
+    author to define a <a href="#scope-limited"><i>scope-limited</i></a>
+    selector.
+
+   <p> On the other hand, the <code>document.find()</code> function defined
+    in <a href="#SELECTORS-API2"
+    rel=biblioentry>[SELECTORS-API2]<!--{{SELECTORS-API2}}--></a> and the
+    selectors within a scoped stylesheet, defined in <a href="#HTML5"
+    rel=biblioentry>[HTML5]<!--{{HTML5}}--></a>, define <a
+    href="#scope-contained0"><i>scope-contained</i></a> selectors.
+  </div>
+
+  <p> Both kinds of scoping define a <a
+   href="#contextual-reference-element-set"><i>contextual reference element
+   set</i></a>, which can be matched with the <a
+   href="#scope"><code>:scope</code></a> pseudo-class selector.
+
   <h2 id=logical-combination><span class=secno>4. </span> Logical
    Combinations</h2>
 
@@ -1847,10 +1894,7 @@ <h3 id=attribute-case><span class=secno>6.3. </span> Case-sensitivity</h3>
     has a value of <code>hsides</code>, whether that value is represented as
     <code>hsides</code>, <code>HSIDES</code>, <code>hSides</code>, etc. even
     in an XML environment where attribute values are case-sensitive.
-
-   <pre>
-<!-- -->[frame=hsides i] { border-style: solid none; }
-    </pre>
+    f<!-- -->[frame=hsides i] { border-style: solid none; }
   </div>
   <!-- plinss notes we may eventually want to choose other normalizations
        for attribute matching; but since there's no normalization scheme

selectors4/Overview.src.html

@@ -731,6 +731,54 @@ <h3 id="invalid">
   <p class="issue">It's been <a href="http://lists.w3.org/Archives/Public/www-style/2010Nov/0203.html">requested</a>
     that the last rule be dropped in favor of Media Queries-style error-handling.</p>
 
+
+<h3 id='selector-scoping'>
+Selector Scoping</h3>
+
+  <p>
+    In some instances,
+    selectors may be "scoped",
+    or limited in some way to apply only within a section of the document.
+
+  <p>
+    There are two distinct ways in which selectors can be scoped:
+
+  <dl>
+    <dt><dfn>scope-contained</dfn>
+    <dd>
+      When a selector is <i>scope-contained</i>,
+      it matches as if the elements outside of its scope did not exist.
+      In other words,
+      it acts like the scope defines a sub-document within which the selector is matched.
+
+    <dt><dfn>scope-limited</dfn>
+    <dd>
+      When a selector is <i>scope-limited</i>,
+      it only matches if the target is within the scope.
+      The rest of the document is still acknowledged
+      and can match all but the last part of the selector;
+      only the target
+      (the element matched by the last compound selector in the selector)
+      is required to be within the scope.
+  </dl>
+
+  <div class='example'>
+    <p>
+      The <code>document.querySelector()</code> function defined in [[SELECTORS-API2]]
+      allows the author to define a <i>scope-limited</i> selector.
+
+    <p>
+      On the other hand, the <code>document.find()</code> function defined in [[SELECTORS-API2]]
+      and the selectors within a scoped stylesheet, defined in [[HTML5]],
+      define <i>scope-contained</i> selectors.
+  </div>
+
+  <p>
+    Both kinds of scoping define a <i>contextual reference element set</i>,
+    which can be matched with the <code>:scope</code> pseudo-class selector.
+
+
+
 <h2 id="logical-combination">
 Logical Combinations</h2>
 
@@ -1163,8 +1211,7 @@ <h3 id="attribute-case">
       has a value of <code>hsides</code>, whether that value is represented
       as <code>hsides</code>, <code>HSIDES</code>, <code>hSides</code>, etc.
       even in an XML environment where attribute values are case-sensitive.
-    <pre>
-<!-- -->[frame=hsides i] { border-style: solid none; }
+    f<!-- -->[frame=hsides i] { border-style: solid none; }
     </pre>
   </div>