[css3-lists] Rewrite counter inheritance to be correct. Editorial tweaks elsewhere in the counter section.

--HG--
extra : rebase_source : 4bff40b5a1e7b55c2860ae398a4dfa4c9e6dd567

Author: tabatkins

css3-lists/Overview.html

@@ -10,10 +10,10 @@
 
   <meta content="CSS Lists and Counters Module Level 3" name=dcterms.title>
   <meta content=text name=dcterms.type>
-  <meta content=2012-11-27 name=dcterms.issued>
+  <meta content=2012-11-29 name=dcterms.issued>
   <meta content="http://dev.w3.org/csswg/css3-lists/" name=dcterms.creator>
   <meta content=W3C name=dcterms.publisher>
-  <meta content="http://www.w3.org/TR/2012/ED-css3-lists-20121127/"
+  <meta content="http://www.w3.org/TR/2012/ED-css3-lists-20121129/"
    name=dcterms.identifier>
   <meta content="text/html; charset=utf-8" http-equiv=Content-Type>
   <link href="http://dev.w3.org/csswg/default.css" rel=stylesheet
@@ -36,13 +36,13 @@
 
    <h1>CSS Lists and Counters Module Level 3</h1>
 
-   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 27 November
+   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 29 November
     2012</h2>
 
    <dl>
     <dt>This version:
 
-    <dd><!--<a href="http://www.w3.org/TR/2012/WD-css3-lists-20121127">http://www.w3.org/TR/2012/WD-css3-lists-20121127</a>-->
+    <dd><!--<a href="http://www.w3.org/TR/2012/WD-css3-lists-20121129">http://www.w3.org/TR/2012/WD-css3-lists-20121129</a>-->
      <a
      href="http://dev.w3.org/csswg/css3-lists/">http://dev.w3.org/csswg/css3-lists/</a>
 
@@ -1496,25 +1496,21 @@ <h3 id=marker-side><span class=secno>7.2. </span> The ‘<a
   <h2 id=counter><span class=secno>8. </span> Automatic Numbering With
    Counters</h2>
 
-  <p> A <dfn id=counter0>counter</dfn> is a special object used, among other
-   things, to automatically number list items in CSS. They are created and
-   manipulated with the ‘<a href="#counter-increment"><code
+  <p> A <dfn id=counter0>counter</dfn> is a special concept used, among other
+   things, to automatically number list items in CSS. Every element has a
+   collection of zero or more counters, which are inherited through the
+   document tree in a way similar to inherited property values. They are
+   created and manipulated with the ‘<a href="#counter-increment"><code
    class=property>counter-increment</code></a>’, ‘<a
    href="#counter-set"><code class=property>counter-set</code></a>’ and
    ‘<a href="#counter-reset"><code
    class=property>counter-reset</code></a>’ properties, and used with the
    <a href="#counter-function"><code
    title=counter-function>counter()</code></a> and <a
    href="#counters-function"><code
-   title=counters-function>counters()</code></a> functions. Counters have an
-   integer value, a creator element, and possibly another counter nested
-   inside themselves.
-
-  <p> Each element has a collection of zero or more counters. Counters
-   inherit between elements in a way similar to other CSS values, but they
-   can inherit from previous siblings in addition to the normal behavior of
-   inheriting from parents. Counters can also "nest" inside of each other,
-   which makes it easier to number nested lists.
+   title=counters-function>counters()</code></a> functions. Counters have a
+   name, an integer value, a creator element, and possibly another counter
+   nested inside themselves.
 
   <h3 id=counter-properties><span class=secno>8.1. </span> Manipulating
    Counters: the ‘<a href="#counter-increment"><code
@@ -1724,9 +1720,10 @@ <h3 id=counter-properties><span class=secno>8.1. </span> Manipulating
 }</pre>
   </div>
 
-  <p> Resetting counters must be done <em>before</em> setting counters, which
-   must be done <em>before</em> incrementing counters, which must be done
-   <em>before</em> using counters (for example, in the ‘<code
+  <p> Inheriting counters must be done <em>before</em> resetting counters,
+   which must be done <em>before</em> setting counters, which must be done
+   <em>before</em> incrementing counters, which must be done <em>before</em>
+   using counters (for example, in the ‘<code
    class=property>content</code>’ property).
 
   <div class=note>
@@ -1756,15 +1753,78 @@ <h3 id=creating-counters><span class=secno>8.2. </span> Creating and
    Inheriting Counters</h3>
 
   <p> Every element has a (possibly empty) set of counters. Like many other
-   CSS values, an element can inherit counters from another element. Unlike
-   many other CSS values, elements can inherit counters from their previous
-   sibling as well as their parent.
+   CSS values, an element can inherit counters from another element. However,
+   unlike other CSS values, the method that counters are inherited is
+   somewhat complex. A counter and its value are inherited
+   <em>separately</em>, possibly from different elements.
+
+  <p> If an element has a previous sibling, it must inherit all of the
+   sibling's counters. Otherwise, if the element has a parent, it must
+   inherit all of the parent's counters. Otherwise, the element must have an
+   empty set of counters.
+
+  <p> The element then inherits counter <em>values</em> from the immediately
+   preceding element <strong>in document order</strong>. This must be done by
+   examining the set of counters that the immediately preceding element has,
+   and, for every counter that exists in both the element's set and the
+   preceding element's set, giving the element's counter the same value. (If
+   an element is the first element in the document, and thus has no
+   immediately preceding element, it also doesn't have a parent or a previous
+   sibling, and thus no counters to begin with.)
+
+  <div class=example id=counter-inheritance-example>
+   <p> Take the following code as an example:
+
+   <pre>
+&lt;ul style='counter-reset: example 0;'>
+  <b
+    class=foo>&lt;li id='foo' style='counter-increment: example;'></b>
+  	foo
+  	<b
+    class=bar>&lt;div id='bar' style='counter-increment: example;'>bar&lt;/div></b>
+  &lt;/li>
+  <b
+    class=baz>&lt;li id='baz'></b>
+  	baz
+  &lt;/li>
+&lt;/ul></pre>
+
+   <p> Recall that "in document order" turns a document tree into an ordered
+    list, where an element comes before its children, and its children come
+    before its next sibling. In other words, for a language like HTML, its
+    the order in which the parser encounters start tags as it reads the
+    document.
+
+   <p> In here, the <code>&lt;ul></code> element establishes a new counter
+    named "example", and sets its value to 0. The <b class=foo>"foo"</b>
+    element, being the first child of the <code>&lt;ul></code>, inherits this
+    counter. Its parent is also its immediately preceding element in document
+    order, so it inherits the value 0 with it, and then immediately
+    increments the value to 1.
+
+   <p> The same happens with the <b class=bar>"bar"</b> element. It inherits
+    the "example" counter from <b class=foo>"foo"</b>, and inherits the value
+    1 from it as well and increments it to 2.
+
+   <p> However, the <b class=baz>"baz"</b> element is a bit different. It
+    inherits the "example" counter from the <b class=foo>"foo"</b> element,
+    its previous sibling. However, rather than inheriting the value 1 from <b
+    class=foo>"foo"</b> along with the counter, in inherits the value 2 from
+    <b class=bar>"bar"</b>, the previous element in document order.
+
+   <p> This behavior allows a single counter to be used throughout a
+    document, continuously incrementing, without the author having to worry
+    about the nested structure of their document.
+  </div>
 
-  <p> If an element has a previous sibling, it inherits all of the sibling's
-   counters (both those the sibling inherited, and ones the sibling created).
-   Otherwise, if an element has a parent, it inherits all of the parent's
-   counters. Otherwise, the element starts with an empty set of counters.
+ <head>
+  <style>
+	#counter-inheritance-example b.foo { color: hsl(0, 80%, 40%); }
+	#counter-inheritance-example b.bar { color: hsl(120, 80%, 30%); }
+	#counter-inheritance-example b.baz { color: hsl(240, 80%, 50%); }
+	</style>
 
+ <body>
   <p> Elements can create additional counters on themselves, which can then
    be passed onto siblings or children. To <dfn
    id=create-a-new-counter>create a new counter</dfn>, specify an element
@@ -1775,8 +1835,8 @@ <h3 id=creating-counters><span class=secno>8.2. </span> Creating and
    <li> If no counters of that name exist on the element, create a new
     counter with that name on the element.
 
-   <li> Otherwise, if a counter of the name exists on the element, and it was
-    created by a preceding sibling, replace the innermost counter of that
+   <li> Otherwise, if a counter of that name exists on the element, and it
+    was created by a preceding sibling, replace the innermost counter of that
     name on the element with a newly-created counter with that name.
 
    <li> Otherwise, create a new counter with that name and nest it inside of

css3-lists/Overview.src.html

@@ -978,21 +978,17 @@ <h2 id='counter'>
 Automatic Numbering With Counters</h2>
 
 	<p>
-		A <dfn>counter</dfn> is a special object
+		A <dfn>counter</dfn> is a special concept
 		used, among other things, to automatically number list items in CSS.
+		Every element has a collection of zero or more counters,
+		which are inherited through the document tree in a way similar to inherited property values.
 		They are created and manipulated with the 'counter-increment', 'counter-set' and 'counter-reset' properties,
 		and used with the <code title='counter-function'>counter()</code> and <code title='counters-function'>counters()</code> functions.
-		Counters have an integer value,
+		Counters have a name,
+		an integer value,
 		a creator element,
 		and possibly another counter nested inside themselves.
 
-	<p>
-		Each element has a collection of zero or more counters.
-		Counters inherit between elements in a way similar to other CSS values,
-		but they can inherit from previous siblings in addition to the normal behavior of inheriting from parents.
-		Counters can also "nest" inside of each other,
-		which makes it easier to number nested lists.
-
 <h3 id='counter-properties'>
 Manipulating Counters: the 'counter-increment', 'counter-set' and 'counter-reset' properties</h2>
 
@@ -1141,7 +1137,8 @@ <h3 id='counter-properties'>
 	</div>
 
 	<p>
-		Resetting counters must be done <em>before</em> setting counters, 
+		Inheriting counters must be done <em>before</em> resetting counters,
+		which must be done <em>before</em> setting counters, 
 		which must be done <em>before</em> incrementing counters, 
 		which must be done <em>before</em> using counters 
 		(for example, in the 'content' property).
@@ -1178,17 +1175,84 @@ <h3 id="creating-counters">
 		Every element has a (possibly empty) set of counters.
 		Like many other CSS values,
 		an element can inherit counters from another element.
-		Unlike many other CSS values,
-		elements can inherit counters from their previous sibling
-		as well as their parent.
+		However, unlike other CSS values,
+		the method that counters are inherited is somewhat complex.
+		A counter and its value are inherited <em>separately</em>,
+		possibly from different elements.
 
 	<p>
 		If an element has a previous sibling,
-		it inherits all of the sibling's counters
-		(both those the sibling inherited, and ones the sibling created).
-		Otherwise, if an element has a parent,
-		it inherits all of the parent's counters.
-		Otherwise, the element starts with an empty set of counters.
+		it must inherit all of the sibling's counters.
+		Otherwise, if the element has a parent,
+		it must inherit all of the parent's counters.
+		Otherwise, the element must have an empty set of counters.
+
+	<p>
+		The element then inherits counter <em>values</em>
+		from the immediately preceding element <strong>in document order</strong>.
+		This must be done by examining the set of counters that the immediately preceding element has,
+		and, for every counter that exists in both the element's set and the preceding element's set,
+		giving the element's counter the same value.
+		(If an element is the first element in the document,
+		and thus has no immediately preceding element,
+		it also doesn't have a parent or a previous sibling,
+		and thus no counters to begin with.)
+
+	<div class='example' id='counter-inheritance-example'>
+		<p>
+			Take the following code as an example:
+
+		<pre>
+&lt;ul style='counter-reset: example 0;'>
+  <b class='foo'>&lt;li id='foo' style='counter-increment: example;'></b>
+  	foo
+  	<b class='bar'>&lt;div id='bar' style='counter-increment: example;'>bar&lt;/div></b>
+  &lt;/li>
+  <b class='baz'>&lt;li id='baz'></b>
+  	baz
+  &lt;/li>
+&lt;/ul></pre>
+
+		<p>
+			Recall that "in document order" turns a document tree into an ordered list,
+			where an element comes before its children,
+			and its children come before its next sibling.
+			In other words, 
+			for a language like HTML,
+			its the order in which the parser encounters start tags as it reads the document.
+
+		<p>
+			In here, the <code>&lt;ul></code> element establishes a new counter named "example",
+			and sets its value to 0.
+			The <b class='foo'>"foo"</b> element, being the first child of the <code>&lt;ul></code>,
+			inherits this counter.
+			Its parent is also its immediately preceding element in document order,
+			so it inherits the value 0 with it,
+			and then immediately increments the value to 1.
+
+		<p>
+			The same happens with the <b class='bar'>"bar"</b> element.
+			It inherits the "example" counter from <b class='foo'>"foo"</b>,
+			and inherits the value 1 from it as well
+			and increments it to 2.
+
+		<p>
+			However, the <b class='baz'>"baz"</b> element is a bit different.
+			It inherits the "example" counter from the <b class='foo'>"foo"</b> element,
+			its previous sibling.
+			However, rather than inheriting the value 1 from <b class='foo'>"foo"</b> along with the counter,
+			in inherits the value 2 from <b class='bar'>"bar"</b>, the previous element in document order.
+
+		<p>
+			This behavior allows a single counter to be used throughout a document,
+			continuously incrementing,
+			without the author having to worry about the nested structure of their document.
+	</div>
+	<style>
+	#counter-inheritance-example b.foo { color: hsl(0, 80%, 40%); }
+	#counter-inheritance-example b.bar { color: hsl(120, 80%, 30%); }
+	#counter-inheritance-example b.baz { color: hsl(240, 80%, 50%); }
+	</style>
 
 	<p>
 		Elements can create additional counters on themselves,
@@ -1205,7 +1269,7 @@ <h3 id="creating-counters">
 			create a new counter with that name on the element.
 
 		<li>
-			Otherwise, if a counter of the name exists on the element,
+			Otherwise, if a counter of that name exists on the element,
 			and it was created by a preceding sibling,
 			replace the innermost counter of that name on the element
 			with a newly-created counter with that name.