[css3-lists] Rewrite and reorganize the 'counter-*' section.

Author: tabatkins

css3-lists/Overview.html

@@ -25,12 +25,12 @@
 
    <h1>CSS Lists and Counters Module Level 3</h1>
 
-   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 24 August 2012</h2>
+   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 25 August 2012</h2>
 
    <dl>
     <dt>This version:
 
-    <dd><!--<a href="http://www.w3.org/TR/2012/WD-css3-lists-20120824">http://www.w3.org/TR/2012/WD-css3-lists-20120824</a>-->
+    <dd><!--<a href="http://www.w3.org/TR/2012/WD-css3-lists-20120825">http://www.w3.org/TR/2012/WD-css3-lists-20120825</a>-->
      <a
      href="http://dev.w3.org/csswg/css3-lists/">http://dev.w3.org/csswg/css3-lists/</a>
 
@@ -354,12 +354,13 @@ <h2 id=declaring-a-list-item><span class=secno>2. </span> Declaring a List
    class=css>::marker</code>’ pseudo-elements; no other elements do.
 
   <p> Additionally, <a href="#list-item"><i>list items</i></a> automatically
-   increment the special ‘<code class=css>list-item</code>’
-   <i>counter</i>. Unless the ‘<a href="#counter-increment"><code
+   increment the special ‘<code class=css>list-item</code>’ <a
+   href="#counter0"><i>counter</i></a>. Unless the ‘<a
+   href="#counter-increment"><code
    class=property>counter-increment</code></a>’ property manually specifies
-   a different increment for the ‘<code class=css>list-item</code>’
-   <i>counter</i>, it must be incremented by 1 on every <a
-   href="#list-item"><i>list item</i></a>, at the same time that
+   a different increment for the ‘<code class=css>list-item</code>’ <a
+   href="#counter0"><i>counter</i></a>, it must be incremented by 1 on every
+   <a href="#list-item"><i>list item</i></a>, at the same time that
    <i>counters</i> are normally incremented. (This has no effect on the
    values of the ‘<code class=css>counter-*</code>’ properties.)
 
@@ -1549,27 +1550,33 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
    ‘<a href="#counter-reset"><code
    class=property>counter-reset</code></a>’ properties</h2>
 
-  <p>Automatic numbering in CSS2 is controlled with three properties: ‘<a
-   href="#counter-increment"><code
+  <p> A <dfn id=counter0>counter</dfn> is a special numeric object used,
+   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
+   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
    href="#counter-set"><code class=property>counter-set</code></a>’ and
    ‘<a href="#counter-reset"><code
-   class=property>counter-reset</code></a>’. The <dfn id=counters
-   title="list counter">counters</dfn> defined by these properties are used
-   with the ‘<code class=css>counter()</code>’ and ‘<code
-   class=css>counters()</code>’ functions.
+   class=property>counter-reset</code></a>’ properties, and used with the
+   ‘<a href="#counter0"><code class=css>counter()</code></a>’ and
+   ‘<code class=css>counters()</code>’ functions.
 
   <table class=propdef>
    <tbody>
     <tr>
      <th>Name:
 
-     <td><dfn id=counter-increment>counter-increment</dfn>
+     <td><dfn id=counter-reset>counter-reset</dfn>
 
     <tr>
      <th>Value:
 
-     <td>[ &lt;identifier> &lt;integer>? ]+ | none
+     <td>[ &lt;ident> &lt;integer>? ]+ | none
 
     <tr>
      <th>Initial:
@@ -1602,6 +1609,26 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
      <td>specified value
   </table>
 
+  <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:
+
+  <dl>
+   <dt>none
+
+   <dd> This element does not establish any new counters.
+
+   <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
+    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
+     that integer.. Otherwise, the starting value of the new counter is
+     ‘<code class=css>0</code>’.
+  </dl>
+
   <table class=propdef>
    <tbody>
     <tr>
@@ -1612,7 +1639,7 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
     <tr>
      <th>Value:
 
-     <td>[ &lt;identifier> &lt;integer>? ]+ | none
+     <td>[ &lt;ident> &lt;integer>? ]+ | none
 
     <tr>
      <th>Initial:
@@ -1650,12 +1677,12 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
     <tr>
      <th>Name:
 
-     <td><dfn id=counter-reset>counter-reset</dfn>
+     <td><dfn id=counter-increment>counter-increment</dfn>
 
     <tr>
      <th>Value:
 
-     <td>[ &lt;identifier> &lt;integer>? ]+ | none
+     <td>[ &lt;ident> &lt;integer>? ]+ | none
 
     <tr>
      <th>Initial:
@@ -1688,37 +1715,36 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
      <td>specified value
   </table>
 
-  <p>The ‘<a href="#counter-increment"><code
-   class=property>counter-increment</code></a>’ property accepts one or
-   more names of counters (identifiers), each one optionally followed by an
-   integer. The integer indicates by how much the counter is incremented for
-   the element it's set on. The default increment is ‘<code
-   class=css>1</code>’.
-
-  <p>The ‘<a href="#counter-set"><code
+  <p> The ‘<a href="#counter-set"><code
    class=property>counter-set</code></a>’ and ‘<a
-   href="#counter-reset"><code class=property>counter-reset</code></a>’
-   properties also contains a list of one or more names of counters, each one
-   optionally followed by an integer. The integer gives the value that the
-   counter is set to on the element it's set on. The default is ‘<code
-   class=css>0</code>’.
-
-  <p>On all of these properties, a value of ‘<a
-   href="#list-style-type-none"><code class=property>none</code></a>’ means
-   that no counters are incremented, set, or reset, respectively. Counter
-   names must not be ‘<code class=property>initial</code>’, ‘<code
-   class=property>inherit</code>’, or ‘<a
-   href="#list-style-type-none"><code class=property>none</code></a>’;
-   using one of these keywords as a counter name makes the property invalid.
-
-  <p>‘<a href="#counter-reset"><code
-   class=property>counter-reset</code></a>’ always establishes a new <a
-   href="#counter-scope"><i>counter scope</i></a> on the element it's set on.
-   ‘<a href="#counter-increment"><code
-   class=property>counter-increment</code></a>’ and ‘<a
-   href="#counter-set"><code class=property>counter-set</code></a>’
-   sometimes establish a new <a href="#counter-scope"><i>counter
-   scope</i></a> on the element they're set on.
+   href="#counter-increment"><code
+   class=property>counter-increment</code></a>’ properties manipulate the
+   value of existing counters. They only create new counters if there is no
+   counter of the given name on the element yet. Their values are defined as
+   follows:
+
+  <dl>
+   <dt>none
+
+   <dd> This element does not alter the value of any counters.
+
+   <dt><code>&lt;ident> &lt;integer>?</code>
+
+   <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.
+    <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
+     class=property>counter-set</code></a>’) or increments the value of the
+     named counter by that integer (for ‘<a href="#counter-increment"><code
+     class=property>counter-increment</code></a>’). Otherwise, the
+     counter's value is set to ‘<code class=css>0</code>’ (for ‘<a
+     href="#counter-set"><code class=property>counter-set</code></a>’) or
+     incremented by ‘<code class=css>1</code>’ (for ‘<a
+     href="#counter-increment"><code
+     class=property>counter-increment</code></a>’).
+  </dl>
 
   <div class=example>
    <p>This example shows a way to number chapters and sections with "Chapter
@@ -1736,13 +1762,13 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
 }</pre>
   </div>
 
-  <p>Resetting a counter is done <em>before</em> setting a counter, which is
-   done <em>before</em> incrementing a counter, which is done <em>before</em>
-   using a counter (for example, in the ‘<code
+  <p> Resetting a counter must be done <em>before</em> setting a counter,
+   which must be done <em>before</em> incrementing a counter, which must be
+   done <em>before</em> using a counter (for example, in the ‘<code
    class=property>content</code>’ property).
 
   <div class=note>
-   <p>The counter properties follow the cascading rules as normal. Thus, due
+   <p> The counter properties follow the cascading rules as normal. Thus, due
     to cascading, the following style sheet:
 
    <div class=example>
@@ -1751,14 +1777,14 @@ <h2 id=counter><span class=secno>8. </span> Automatic Counters and
 H1 { counter-reset: imagenum 99 }</pre>
    </div>
 
-   <p>will only reset ‘<code class=property>imagenum</code>’. To reset
+   <p> will only reset ‘<code class=property>imagenum</code>’. To reset
     both counters, they have to be specified together:
 
    <div class=example>
     <pre>H1 { counter-reset: section -1 imagenum 99 }</pre>
    </div>
 
-   <p>The same principles apply to the ‘<a href="#counter-set"><code
+   <p> The same principles apply to the ‘<a href="#counter-set"><code
     class=property>counter-set</code></a>’ and ‘<a
     href="#counter-increment"><code
     class=property>counter-increment</code></a>’ properties.
@@ -1767,15 +1793,15 @@ <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
+  <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.
 
   <div class=example>
-   <p>Thus, the following suffices to number nested list items. The result is
-    very similar to that of setting ‘<code
+   <p> Thus, the following suffices to number nested list items. The result
+    is very similar to that of setting ‘<code
     class=css>display:list-item</code>’ and ‘<code class=css>list-style:
     inside</code>’ on the LI element:
 
@@ -1785,7 +1811,7 @@ <h3 id=nested-counters><span class=secno>8.1. </span> Nested counters and
 LI:before { content: counter(item) ". "; counter-increment: item }</pre>
   </div>
 
-  <p>The self-nesting is based on the principle that every element or
+  <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
@@ -1835,9 +1861,9 @@ <h3 id=nested-counters><span class=secno>8.1. </span> Nested counters and
 &lt;/OL>              &lt;!-- )                         --></pre>
   </div>
 
-  <p>As explained in a later section, the ‘<code
-   class=css>counter()</code>’ function generates a string based off of the
-   innermost scope of the named counter, while the ‘<code
+  <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.
 
@@ -1879,12 +1905,12 @@ <h3 id=counters-without-boxes><span class=secno>8.2. </span> Counters in
    so do not apply here.
 
   <h2 id=counter-function><span class=secno>9. </span> Printing Counters: the
-   ‘<code class=css>counter()</code>’ and ‘<code
-   class=css>counters()</code>’ functions</h2>
+   ‘<a href="#counter0"><code class=css>counter()</code></a>’ and
+   ‘<code class=css>counters()</code>’ functions</h2>
 
   <p>Counters have no visible effect by themselves, but their values can be
-   used in the ‘<code class=css>counter()</code>’ and ‘<code
-   class=css>counters()</code>’ functions to generate counter
+   used in the ‘<a href="#counter0"><code class=css>counter()</code></a>’
+   and ‘<code class=css>counters()</code>’ functions to generate counter
    representations. This happens automatically in the default contents of
    ‘<code class=css>::marker</code>’ pseudo-elements, but can be used by
    an author anywhere that accepts a string. Their syntax is:
@@ -1906,10 +1932,10 @@ <h2 id=counter-function><span class=secno>9. </span> Printing Counters: the
    named counter's value using the function's ‘<code
    class=css>&lt;counter-style></code>’. If there are multiple counters of
    that name in scope, the one whose scoping element is closest in
-   document-order to the element on which ‘<code
-   class=css>counter()</code>’ appears is used. If there are no counters of
-   that name in scope, use the value ‘<code class=css>0</code>’ to
-   generate the counter representation. If ‘<a
+   document-order to the element on which ‘<a href="#counter0"><code
+   class=css>counter()</code></a>’ appears is used. If there are no
+   counters of that name in scope, use the value ‘<code
+   class=css>0</code>’ to generate the counter representation. If ‘<a
    href="#list-style-type-none"><code class=css>none</code></a>’ is
    provided as the second argument, the ‘<a
    href="#ltcounter-function"><code
@@ -2056,7 +2082,8 @@ <h2 id=counter-style><span class=secno>10. </span> Defining Custom Counter
    this in an open-ended manner, by allowing the author to define their own
    counter styles. These styles can then be used in the ‘<a
    href="#list-style-type"><code class=property>list-style-type</code></a>’
-   property or in the ‘<code class=css>counter()</code>’ and ‘<code
+   property or in the ‘<a href="#counter0"><code
+   class=css>counter()</code></a>’ and ‘<code
    class=css>counters()</code>’ functions.
 
   <p>A <dfn id=counter-style0>counter style</dfn> defines how to construct
@@ -3459,7 +3486,7 @@ <h2 class=no-num id=property-index>Property index</h2>
     <tr>
      <th><a class=property href="#counter-increment">counter-increment</a>
 
-     <td>[ &lt;identifier> &lt;integer>? ]+ | none
+     <td>[ &lt;ident> &lt;integer>? ]+ | none
 
      <td>none
 
@@ -3474,7 +3501,7 @@ <h2 class=no-num id=property-index>Property index</h2>
     <tr>
      <th><a class=property href="#counter-reset">counter-reset</a>
 
-     <td>[ &lt;identifier> &lt;integer>? ]+ | none
+     <td>[ &lt;ident> &lt;integer>? ]+ | none
 
      <td>none
 
@@ -3489,7 +3516,7 @@ <h2 class=no-num id=property-index>Property index</h2>
     <tr>
      <th><a class=property href="#counter-set">counter-set</a>
 
-     <td>[ &lt;identifier> &lt;integer>? ]+ | none
+     <td>[ &lt;ident> &lt;integer>? ]+ | none
 
      <td>none
 
@@ -3636,6 +3663,8 @@ <h2 class=no-num id=index>Index</h2>
 
    <li>circle, <a href="#circle" title=circle><strong>12.</strong></a>
 
+   <li>counter, <a href="#counter0" title=counter><strong>8.</strong></a>
+
    <li>counter-algorithm, <a href="#algorithm"
     title=counter-algorithm><strong>10.</strong></a>
 
@@ -3733,9 +3762,6 @@ <h2 class=no-num id=index>Index</h2>
    <li>inside, <a href="#list-style-position-inside"
     title=inside><strong>4.</strong></a>
 
-   <li>list counter, <a href="#counters"
-    title="list counter"><strong>8.</strong></a>
-
    <li>list item, <a href="#list-item"
     title="list item"><strong>2.</strong></a>