[css3-lists] Rewrite the counter() section.

Author: tabatkins

css3-lists/Overview.html

@@ -196,8 +196,8 @@ <h2 class="no-num no-toc" id=contents> Table of contents</h2>
     </ul>
 
    <li><a href="#counter-function"><span class=secno>9. </span> Printing
-    Counters: the ‘<code class=css>counter()</code>’ and ‘<code
-    class=css>counters()</code>’ functions</a>
+    Counters: the <code title=counter-function>counter()</code> and <code
+    title=counters-function>counters()</code> functions</a>
 
    <li><a href="#counter-style"><span class=secno>10. </span> Defining Custom
     Counter Styles: the ‘<code class=css>@counter-style</code>’ rule</a>
@@ -1560,8 +1560,10 @@ <h2 id=counter><span class=secno>8. </span> Automatic Numbering With
    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="#counter0"><code class=css>counter()</code></a>’ and
-   ‘<code class=css>counters()</code>’ functions. Counters have an
+   <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.
 
@@ -1927,88 +1929,107 @@ <h3 id=counters-without-boxes><span class=secno>8.4. </span> Counters in
    so do not apply here.
 
   <h2 id=counter-function><span class=secno>9. </span> Printing Counters: the
-   ‘<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 ‘<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:
+   <a href="#counter-function"><code
+   title=counter-function>counter()</code></a> and <a
+   href="#counters-function"><code
+   title=counters-function>counters()</code></a> functions</h2>
+
+  <p> Counters have no visible effect by themselves, but their values can be
+   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. 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:
 
   <pre>
+<dfn id=counter-function
+   title=counter-function>&lt;counter-function></dfn>  =  counter(&lt;ident> [, [ <code>&lt;counter-style></code> | none ] ]? )
 <dfn
-   id=ltcounter-function>&lt;counter-function></dfn>  =  counter(name [, [ &lt;counter-style> | none ] ]? )
-<dfn
-   id=ltcounters-function>&lt;counters-function></dfn> = counters(name, &lt;string>[, [ &lt;counter-style> | none ] ]? )</pre>
+   id=counters-function
+   title=counters-function>&lt;counters-function></dfn> = counters(&lt;ident>, &lt;string>[, [ <code>&lt;counter-style></code> | none ] ]? )</pre>
 
-  <p>For both functions, if the ‘<code
-   class=css>&lt;counter-style></code>’ is omitted it defaults to ‘<a
+  <p> For both functions, the first argument represents the name of a
+   counter, and if the last argument is omitted it defaults to ‘<a
    href="#decimal"><code class=css>decimal</code></a>’.
 
-  <p>A ‘<a href="#ltcounter-function"><code
-   class=css>&lt;counter-function></code></a>’ represents the string
-   obtained when one <a href="#generate-a-counter-representation"><i
-   title=generate-a-counter>generates a counter representation</i></a> of 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 ‘<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
-   class=css>&lt;counter-function></code></a>’ instead represents the empty
-   string.
+  <p> A <a href="#counter-function"><code
+   title=counter-function>&lt;counter-function></code></a> represents a <code
+   title="">&lt;string></code>, obtained as follows:
+
+  <ul>
+   <li> If the second argument to the function is ‘<a
+    href="#list-style-type-none"><code class=css><i
+    title="">none</i></code></a>’, the function represents the empty
+    string.
+
+   <li> Otherwise, the function represents the string returned when one <a
+    href="#generate-a-counter-representation"><i
+    title=generate-a-counter>generates a counter representation</i></a> for
+    the value of the innermost counter of that name on the element (or
+    ‘<code class=css>0</code>’ if the element has no counter of that
+    name) using the <code>&lt;counter-style></code> specified by the second
+    argument.
+  </ul>
 
   <div class=example>
    <pre>
-H1:before        { content: counter(chno, upper-latin) ". " }
+H1::before        { content: counter(chno, upper-latin) ". " }
 /* Generates headings like "A. A History of Discontent" */
 
-H2:before        { content: counter(section, upper-roman) " - " }
+H2::before        { content: counter(section, upper-roman) " - " }
 /* Generates headings like "II - The Discontent Part" */
 
-BLOCKQUOTE:after { content: " [" counter(bq, decimal) "]" }
+BLOCKQUOTE::after { content: " [" counter(bq, decimal) "]" }
 /* Generates blockquotes that end like "... [3]" */
 
-DIV.note:before  { content: counter(notecntr, disc) " " }
+DIV.note::before  { content: counter(notecntr, disc) " " }
 /* Simply generates a bullet before every div.note */
 
-P:before         { content: counter(p, none) } 
+P::before         { content: counter(p, none) } 
 /* inserts nothing */</pre>
   </div>
 
-  <p>A ‘<a href="#ltcounters-function"><code
-   class=css>&lt;counters-function></code></a>’ represents the string
-   obtained by the following algorithm:
+  <p> A <a href="#counters-function"><code
+   title=counters-function>&lt;counters-function></code></a> represents a
+   <code title="">&lt;string></code>, obtained as follows:
 
-  <ol>
-   <li>Collect all counters of the given name that are in scope for the
-    elements on which ‘<code class=css>counters()</code>’ appears, sorted
-    by document-order of each scope's scoping element. If there are no such
-    counters, run the rest of this algorithm as if there were a single
-    counter with the value ‘<code class=css>0</code>’.
+  <ul>
+   <li> If the third argument to the function is ‘<a
+    href="#list-style-type-none"><code class=css><i
+    title="">none</i></code></a>’, the function represents the empty
+    string.
 
-   <li>Render each counter as a string by <a
+   <li> Otherwise, if the element has no counters of that name, the function
+    represents the string returned when one <a
     href="#generate-a-counter-representation"><i
-    title=generate-a-counter>generating a counter representation</i></a> of
-    the counter's value using the function's &lt;counter-style>. If ‘<a
-    href="#list-style-type-none"><code class=css>none</code></a>’ is
-    provided as the third argument, instead render each counter as the empty
-    string.
+    title=generate-a-counter>generates a counter representation</i></a> for
+    ‘<code class=css>0</code>’ using the <code>&lt;counter-style></code>
+    specified by the third argument.
 
-   <li>Concatenate all of the counter representations in order, placing a
-    copy of the string provided as the second argument between each adjacent
-    pair, and return the resulting string.
-  </ol>
+   <li> Otherwise, if the element has a single counter of that name, the
+    function represents the string returned when one <a
+    href="#generate-a-counter-representation"><i
+    title=generate-a-counter>generates a counter representation</i></a> for
+    that counter's value using the <code>&lt;counter-style></code> specified
+    by the third argument.
+
+   <li> Otherwise, <a href="#generate-a-counter-representation"><i
+    title=generate-a-counter>generate a counter representation</i></a> for
+    the values of all counters of the given name on the element using the
+    <code>&lt;counter-style></code> specified by the third argument. Sort the
+    resulting strings by the nesting depth of the counters they were
+    generated from, with the outermost counter first and the innermost last.
+    Join the list into a single string, inserting the <code
+    title="">&lt;string></code> specified by the second argument between each
+    item in the list. The function represents the string thus produced.
+  </ul>
 
   <div class=example>
-   <p>The following example shows a simple use of the ‘<code
-    class=css>counters()</code>’ function:
+   <p>The following example shows a simple use of the <a
+    href="#counters-function"><code
+    title=counters-function>counters()</code></a> function:
 
    <pre>
 &lt;ul>
@@ -2038,11 +2059,13 @@ <h2 id=counter-function><span class=secno>9. </span> Printing Counters: the
   </div>
 
   <div class=example>
-   <p>Because counter scopes extend to siblings as well, they can be used to
+   <p> Because counters inherit to siblings as well, they can be used to
     number headings and subheadings, which aren't nested within each other.
-    Unfortunately, this precludes the use of ‘<code
-    class=css>counters()</code>’ as the scopes of siblings won't nest, but
-    one can create multiple counters and manually reference them instead:
+    Unfortunately, this prevents the use of <a
+    href="#counters-function"><code
+    title=counters-function>counters()</code></a> as counters from siblings
+    don't nest, but one can create multiple counters and manually concatenate
+    them instead:
 
    <pre>
 &lt;h1>First H1&lt;/h1>
@@ -2104,9 +2127,10 @@ <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 ‘<a href="#counter0"><code
-   class=css>counter()</code></a>’ and ‘<code
-   class=css>counters()</code>’ functions.
+   property or in 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.
 
   <p>A <dfn id=counter-style0>counter style</dfn> defines how to construct
    the representation of a counter value. Counter styles are composed of:
@@ -3693,8 +3717,8 @@ <h2 class=no-num id=index>Index</h2>
    <li>counter-fallback, <a href="#fallback-style"
     title=counter-fallback><strong>10.</strong></a>
 
-   <li>&lt;counter-function>, <a href="#ltcounter-function"
-    title="&lt;counter-function>"><strong>9.</strong></a>
+   <li>counter-function, <a href="#counter-function"
+    title=counter-function><strong>9.</strong></a>
 
    <li>counter-increment, <a href="#counter-increment"
     title=counter-increment><strong>8.1.</strong></a>
@@ -3717,8 +3741,8 @@ <h2 class=no-num id=index>Index</h2>
    <li>counter-set, <a href="#counter-set"
     title=counter-set><strong>8.1.</strong></a>
 
-   <li>&lt;counters-function>, <a href="#ltcounters-function"
-    title="&lt;counters-function>"><strong>9.</strong></a>
+   <li>counters-function, <a href="#counters-function"
+    title=counters-function><strong>9.</strong></a>
 
    <li>counter style, <a href="#counter-style0"
     title="counter style"><strong>10.</strong></a>