[css3-lists] Rewrite the scopes section, slightly tweak the previous section again.

Author: tabatkins

css3-lists/Overview.html

@@ -1554,9 +1554,9 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
    among other things, to automatically number list items in CSS.
 
   <p> A <a href="#counter0"><i>counter</i></a> has an integer value and a <a
-   href="#counter-scope"><i>scope</i></a> which dictates which elements share
-   a given counter. The value of a <a href="#counter0"><i>counter</i></a> can
-   be different on different elements in the document, allowing list items to
+   href="#scope"><i>scope</i></a> which dictates which elements share a given
+   counter. The value of a <a href="#counter0"><i>counter</i></a> can be
+   different on different elements in the document, allowing list items to
    generate successive numbers in their markers. They are created and
    manipulated with the ‘<a href="#counter-increment"><code
    class=property>counter-increment</code></a>’, ‘<a
@@ -1611,7 +1611,8 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
 
   <p> The ‘<a href="#counter-reset"><code
    class=property>counter-reset</code></a>’ property creates new counters,
-   with new associated <i>scopes</i>. Its values are defined as follows:
+   with new associated <a href="#scope"><i>scopes</i></a>. Its values are
+   defined as follows:
 
   <dl>
    <dt>none
@@ -1620,8 +1621,9 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
 
    <dt><code>&lt;ident> &lt;integer>?</code>
 
-   <dd> The element <i title="establishes a counter">establishes one or more
-    new counters</i>. Each <code>&lt;ident></code> names a new counter which
+   <dd> The element <a href="#establishes-a-counter"><i
+    title="establishes a counter">establishes one or more new
+    counters</i></a>. Each <code>&lt;ident></code> names a new counter which
     is created.
     <p> If an <code>&lt;integer></code> is provided after an
      <code>&lt;ident></code>, the newly established counter's value is set to
@@ -1732,7 +1734,10 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
 
    <dd> The element alters the value of one or more counters on it. If there
     is not currently a counter of the given name on the element, the element
-    <i>establishes a counter</i> of the given name.
+    <a href="#establishes-a-counter"><i>establishes a counter</i></a> of the
+    given name and initally sets its value to ‘<code class=css>0</code>’
+    (though it may then immediately set or increment that value to something
+    different).
     <p> If an <code>&lt;integer></code> is provided after an
      <code>&lt;ident></code>, it sets the named counter to that integer (for
      ‘<a href="#counter-set"><code
@@ -1793,11 +1798,37 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
   <h3 id=nested-counters><span class=secno>8.1. </span> Nested counters and
    scope</h3>
 
-  <p> Counters are "self-nesting", in the sense that resetting a counter in a
-   child element automatically creates a new instance of the counter. This is
-   important for situations like lists in HTML, where lists can be nested
-   inside lists to arbitrary depth. It would be impossible to define uniquely
-   named counters for each level.
+  <p> Every <a href="#counter0"><i>counter</i></a> is associated with a <dfn
+   id=scope title="scope|scopes">scope</dfn>, which defines which elements in
+   the document share a given counter.
+
+  <p> <a href="#scope"><i>Scopes</i></a> have a name, which is the same as
+   their associated counter, a root element, which is the element that
+   establishes the counter, and a set of contained elements, which are the
+   elements that share the given counter. When an element <dfn
+   id=establishes-a-counter>establishes a counter</dfn>, it creates a counter
+   and scope of the given name, sets the scope's root element to the element
+   that establishes it, and sets the contained elements to the element and
+   its descendants, all following siblings of the root element up to but not
+   including the first sibling that establishes a counter of the same name,
+   and all descendants of those siblings.
+
+  <p> The value of a counter can change across its scope. Whenever an element
+   sets the value of a counter, the altered value is what is seen by all
+   elements contained in the scope that are later in document order (unless,
+   of course, another element between the two further alters the counter's
+   value).
+
+  <p> Counters are "self-nesting"; establishing a counter in an element
+   already contained in the scope of another counter of the same name simply
+   creates a new instance of the counter. This is important for situations
+   like lists in HTML, where lists can be nested inside lists to arbitrary
+   depth. It would be impossible to define uniquely named counters for each
+   level. As explained in a later section, the ‘<a href="#counter0"><code
+   class=css>counter()</code></a>’ function only uses the innermost counter
+   of a given name on the element, but the ‘<code
+   class=css>counters()</code>’ function uses all counters of a given name
+   that contain the element.
 
   <div class=example>
    <p> Thus, the following suffices to number nested list items. The result
@@ -1806,34 +1837,16 @@ <h3 id=nested-counters><span class=secno>8.1. </span> Nested counters and
     inside</code>’ on the LI element:
 
    <pre>
-OL { counter-reset: item }
-LI { display: block }
-LI:before { content: counter(item) ". "; counter-increment: item }</pre>
-  </div>
-
-  <p> The self-nesting is based on the principle that every element or
-   pseudo-element that has a ‘<a href="#counter-reset"><code
-   class=property>counter-reset</code></a>’ for a counter X, creates a
-   fresh counter X, the <dfn id=counter-scope
-   title="scope|counter scope">scope</dfn> of which is the element or
-   pseudo-element, its following siblings up to but not including the first
-   one that resets the same counter, and all the descendants of those
-   elements.
-
-  <p>Additionally, if an element has a ‘<a href="#counter-set"><code
-   class=property>counter-set</code></a>’ or ‘<a
-   href="#counter-increment"><code
-   class=property>counter-increment</code></a>’ for a counter that is not
-   in scope for the element, it establishes a scope for that counter
-   identically to if ‘<a href="#counter-reset"><code
-   class=property>counter-reset</code></a>’ were used on the element to
-   reset the counter to ‘<code class=css>0</code>’.
+ol { counter-reset: item }
+li { display: block }
+li::before { content: counter(item) ". "; counter-increment: item }</pre>
 
-  <p>In the example above, an OL will create a counter, and all children of
-   the OL will refer to that counter.
+   <p> In this example, an OL will create a counter, and all children of the
+    OL will refer to that counter.
+  </div>
 
-  <div class=html-example>
-   <p>If we denote by item[<var>n</var>] the <var>n</var><sup>th</sup>
+  <div class=example>
+   <p> If we denote by item[<var>n</var>] the <var>n</var><sup>th</sup>
     instance of the "item" counter, and by "(" and ")"the beginning and end
     of a scope, then the following HTML fragment will use the indicated
     counters. (We assume the style sheet as given in the example above).
@@ -1859,24 +1872,9 @@ <h3 id=nested-counters><span class=secno>8.1. </span> Nested counters and
   &lt;LI>item         &lt;!--  increment item[4] to 1   -->
   &lt;LI>item         &lt;!--  increment item[4] to 2   -->
 &lt;/OL>              &lt;!-- )                         --></pre>
-  </div>
-
-  <p>As explained in a later section, the ‘<a href="#counter0"><code
-   class=css>counter()</code></a>’ function generates a string based off of
-   the innermost scope of the named counter, while the ‘<code
-   class=css>counters()</code>’ function generates a string based on the
-   values of <em>all</em> the in-scope counters with a given name.
 
-  <div class=example>
-   <p>
-
-   <p>The following style sheet numbers nested list items as "1", "1.1",
-    "1.1.1", etc.
-
-   <pre>
-OL { counter-reset: item }
-LI { display: block }
-LI:before { content: counters(item, "."); counter-increment: item }</pre>
+   <p class=issue> Rewrite this example as an image showing the scopes
+    visually.
   </div>
 
   <h3 id=counters-without-boxes><span class=secno>8.2. </span> Counters in
@@ -3692,9 +3690,6 @@ <h2 class=no-num id=index>Index</h2>
    <li>counter-reset, <a href="#counter-reset"
     title=counter-reset><strong>8.</strong></a>
 
-   <li>counter scope, <a href="#counter-scope"
-    title="counter scope"><strong>8.1.</strong></a>
-
    <li>counter-set, <a href="#counter-set"
     title=counter-set><strong>8.</strong></a>
 
@@ -3734,6 +3729,9 @@ <h2 class=no-num id=index>Index</h2>
 
    <li>disc, <a href="#disc" title=disc><strong>12.</strong></a>
 
+   <li>establishes a counter, <a href="#establishes-a-counter"
+    title="establishes a counter"><strong>8.1.</strong></a>
+
    <li>fallback, <a href="#descdef-fallback"
     title=fallback><strong>10.6.</strong></a>
 
@@ -3821,7 +3819,9 @@ <h2 class=no-num id=index>Index</h2>
    <li>range, <a href="#descdef-range" title=range><strong>10.5.</strong></a>
 
 
-   <li>scope, <a href="#counter-scope" title=scope><strong>8.1.</strong></a>
+   <li>scope, <a href="#scope" title=scope><strong>8.1.</strong></a>
+
+   <li>scopes, <a href="#scope" title=scopes><strong>8.1.</strong></a>
 
    <li>square, <a href="#square" title=square><strong>12.</strong></a>
 

css3-lists/Overview.src.html

@@ -1095,7 +1095,9 @@ <h2 id='counter'>
 		<dd>
 			The element alters the value of one or more counters on it.
 			If there is not currently a counter of the given name on the element,
-			the element <i>establishes a counter</i> of the given name.
+			the element <i>establishes a counter</i> of the given name
+			and initally sets its value to ''0''
+			(though it may then immediately set or increment that value to something different).
 
 			<p>
 				If an <code>&lt;integer></code> is provided after an <code>&lt;ident></code>,
@@ -1156,37 +1158,65 @@ <h3 id="nested-counters">
 Nested counters and scope</h3>
 
 	<p>
-		Counters are "self-nesting", 
-		in the sense that resetting a counter in a child element automatically creates a new instance of the counter.
+		Every <i>counter</i> is associated with a <dfn title="scope|scopes">scope</dfn>,
+		which defines which elements in the document share a given counter.
+
+	<p>
+		<i>Scopes</i> have a name,
+		which is the same as their associated counter,
+		a root element,
+		which is the element that establishes the counter,
+		and a set of contained elements,
+		which are the elements that share the given counter.
+		When an element <dfn>establishes a counter</dfn>,
+		it creates a counter and scope of the given name,
+		sets the scope's root element to the element that establishes it,
+		and sets the contained elements to the element and its descendants,
+		all following siblings of the root element up to but not including the first sibling that establishes a counter of the same name,
+		and all descendants of those siblings.
+
+	<p>
+		The value of a counter can change across its scope.
+		Whenever an element sets the value of a counter,
+		the altered value is what is seen by all elements contained in the scope
+		that are later in document order
+		(unless, of course, another element between the two further alters the counter's value).
+
+	<p>
+		Counters are "self-nesting";
+		establishing a counter in an element already contained in the scope of another counter of the same name
+		simply creates a new instance of the counter.
 		This is important for situations like lists in HTML, 
 		where lists can be nested inside lists to arbitrary depth. 
 		It would be impossible to define uniquely named counters for each level.
+		As explained in a later section,
+		the ''counter()'' function only uses the innermost counter of a given name on the element,
+		but the ''counters()'' function uses all counters of a given name that contain the element.
 
 	<div class="example">
 		<p>
 			Thus, the following suffices to number nested list items. 
 			The result is very similar to that of setting 'display:list-item' and 'list-style: inside' on the LI element:
 
 		<pre>
-OL { counter-reset: item }
-LI { display: block }
-LI:before { content: counter(item) ". "; counter-increment: item }</pre>
+ol { counter-reset: item }
+li { display: block }
+li::before { content: counter(item) ". "; counter-increment: item }</pre>
+		
+		<p>
+			In this example, 
+			an OL will create a counter, 
+			and all children of the OL will refer to that counter.
 	</div>
 
-	<p>
-		The self-nesting is based on the principle that every element or pseudo-element that has a 'counter-reset' for a counter X, 
-		creates a fresh counter X, 
-		the <dfn id="counter-scope" title="scope|counter scope">scope</dfn> of which is the element or pseudo-element, 
-		its following siblings up to but not including the first one that resets the same counter, 
-		and all the descendants of those elements.
 
-	<p>Additionally, if an element has a 'counter-set' or 'counter-increment' for a counter that is not in scope for the element, it establishes a scope for that counter identically to if 'counter-reset' were used on the element to reset the counter to ''0''.
-
-	<p>In the example above, an OL will create a counter, and all children of the OL will refer to that counter.
-
-	<div class="html-example">
+	<div class="example">
 
-		<p>If we denote by item[<var>n</var>] the <var>n</var><sup>th</sup> instance of the "item" counter, and by "(" and ")"the beginning and end of a scope, then the following HTML fragment will use the indicated counters. (We assume the style sheet as given in the example above).
+		<p>
+			If we denote by item[<var>n</var>] the <var>n</var><sup>th</sup> instance of the "item" counter, 
+			and by "(" and ")"the beginning and end of a scope, 
+			then the following HTML fragment will use the indicated counters. 
+			(We assume the style sheet as given in the example above).
 
 		<pre>
 &lt;OL>               &lt;!-- (set item[0] to 0         -->
@@ -1209,18 +1239,9 @@ <h3 id="nested-counters">
   &lt;LI>item         &lt;!--  increment item[4] to 1   -->
   &lt;LI>item         &lt;!--  increment item[4] to 2   -->
 &lt;/OL>              &lt;!-- )                         --></pre>
-	</div>
-
-	<p>As explained in a later section, the ''counter()'' function generates a string based off of the innermost scope of the named counter, while the ''counters()'' function generates a string based on the values of <em>all</em> the in-scope counters with a given name.
 
-	<div class="example"><p>
-		<p>The following style sheet numbers nested list items 
-		as "1", "1.1", "1.1.1", etc.
-
-		<pre>
-OL { counter-reset: item }
-LI { display: block }
-LI:before { content: counters(item, "."); counter-increment: item }</pre>
+		<p class='issue'>
+			Rewrite this example as an image showing the scopes visually.
 	</div>