- From: Tab Atkins Jr.. via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 07 Dec 2011 02:40:27 +0000
- To: public-css-commits@w3.org
Update of /sources/public/csswg/css3-lists
In directory hutz:/tmp/cvs-serv26853
Modified Files:
Overview.html Overview.src.html
Log Message:
Added the counter-* properties and the counter()/counters() functions.
Index: Overview.html
===================================================================
RCS file: /sources/public/csswg/css3-lists/Overview.html,v
retrieving revision 1.127
retrieving revision 1.128
diff -u -d -r1.127 -r1.128
--- Overview.html 6 Dec 2011 21:23:29 -0000 1.127
+++ Overview.html 7 Dec 2011 02:40:25 -0000 1.128
@@ -25,13 +25,13 @@
<h1>CSS Lists and Counters Module Level 3</h1>
- <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 6 December
+ <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 7 December
2011</h2>
<dl>
<dt>This version:
- <dd><!--<a href="http://www.w3.org/TR/2011/WD-css3-lists-20111206">http://www.w3.org/TR/2011/WD-css3-lists-20111206</a></dd>-->
[...1061 lines suppressed...]
- <li>type, <a href="#descdef-type" title=type><strong>8.1.</strong></a>
+ <li>type, <a href="#descdef-type" title=type><strong>10.1.</strong></a>
<li>upper-alpha, <a href="#upper-alpha"
- title=upper-alpha><strong>10.</strong></a>
+ title=upper-alpha><strong>12.</strong></a>
<li>upper-alpha-legal, <a href="#upper-alpha-legal"
- title=upper-alpha-legal><strong>8.1.4.</strong></a>
+ title=upper-alpha-legal><strong>10.1.4.</strong></a>
<li>upper-latin, <a href="#upper-latin"
- title=upper-latin><strong>10.</strong></a>
+ title=upper-latin><strong>12.</strong></a>
<li>upper-roman, <a href="#upper-roman"
- title=upper-roman><strong>10.</strong></a>
+ title=upper-roman><strong>12.</strong></a>
</ul>
<!--end-index-->
Index: Overview.src.html
===================================================================
RCS file: /sources/public/csswg/css3-lists/Overview.src.html,v
retrieving revision 1.174
retrieving revision 1.175
diff -u -d -r1.174 -r1.175
--- Overview.src.html 6 Dec 2011 21:23:29 -0000 1.174
+++ Overview.src.html 7 Dec 2011 02:40:25 -0000 1.175
@@ -814,6 +814,328 @@
<!-- ===================================================================== -->
+<h2 id='counter'>
+Automatic Counters and Numbering: the 'counter-increment', 'counter-set' and 'counter-reset' properties</h2>
+
+ <p>Automatic numbering in CSS2 is controlled with three properties: 'counter-increment', 'counter-set' and 'counter-reset'. The <dfn title="list counter">counters</dfn> defined by these properties are used with the ''counter()'' and ''counters()'' functions.
+
+ <table class="propdef">
+ <tr>
+ <th>Name:
+ <td><dfn>counter-increment</dfn>
+ <tr>
+ <th>Value:
+ <td>[ <identifier> <integer>? ]+ | none
+ <tr>
+ <th>Initial:
+ <td>none
+ <tr>
+ <th>Applies To:
+ <td>all elements
+ <tr>
+ <th>Inherited:
+ <td>no
+ <tr>
+ <th>Percentages:
+ <td>N/A
+ <tr>
+ <th>Media:
+ <td>all
+ <tr>
+ <th>Computed value:
+ <td>specified value
+ </table>
+
+ <table class="propdef">
+ <tr>
+ <th>Name:
+ <td><dfn>counter-set</dfn>
+ <tr>
+ <th>Value:
+ <td>[ <identifier> <integer>? ]+ | none
+ <tr>
+ <th>Initial:
+ <td>none
+ <tr>
+ <th>Applies To:
+ <td>all elements
+ <tr>
+ <th>Inherited:
+ <td>no
+ <tr>
+ <th>Percentages:
+ <td>N/A
+ <tr>
+ <th>Media:
+ <td>all
+ <tr>
+ <th>Computed value:
+ <td>specified value
+ </table>
+
+ <table class="propdef">
+ <tr>
+ <th>Name:
+ <td><dfn>counter-reset</dfn>
+ <tr>
+ <th>Value:
+ <td>[ <identifier> <integer>? ]+ | none
+ <tr>
+ <th>Initial:
+ <td>none
+ <tr>
+ <th>Applies To:
+ <td>all elements
+ <tr>
+ <th>Inherited:
+ <td>no
+ <tr>
+ <th>Percentages:
+ <td>N/A
+ <tr>
+ <th>Media:
+ <td>all
+ <tr>
+ <th>Computed value:
+ <td>specified value
+ </table>
+
+ <p>The 'counter-increment' 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 ''1''.</p>
+
+ <p>The 'counter-set' and 'counter-reset' 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 ''0''.</p>
+
+ <p>'counter-reset' always establishes a new <i>counter scope</i> on the element it's set on. 'counter-increment' and 'counter-set' sometimes establish a new <i>counter scope</i> on the element they're set on.</p>
+
+ <div class="example">
+ <p>This example shows a way to number chapters and sections with "Chapter 1", "1.1", "1.2", etc.
+
+ <pre>
+H1:before {
+ content: "Chapter " counter(chapter) ". ";
+ counter-increment: chapter; /* Add 1 to chapter */
+ counter-reset: section; /* Set section to 0 */
+}
+H2:before {
+ content: counter(chapter) "." counter(section) " ";
+ counter-increment: section;
+}</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 'content' property).</p>
+
+ <div class='note'>
+ <p>The counter properties follow the cascading rules as normal. Thus, due to cascading, the following style sheet:</p>
+
+ <div class='example'>
+ <pre>
+H1 { counter-reset: section -1 }
+H1 { counter-reset: imagenum 99 }</pre>
+ </div>
+
+ <p>will only reset 'imagenum'. To reset both counters, they have to be specified together:</p>
+
+ <div class='example'>
+ <pre>H1 { counter-reset: section -1 imagenum 99 }</pre>
+ </div>
+
+ <p>The same principles apply to the 'counter-set' and 'counter-increment' properties.</p>
+ </div>
+
+
+<h3 id="nested-counters">
+Nested counters and scope</h3>
+
+ <p>Counters are "self-nesting", in the sense that re-using 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 '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>
+ </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>
+
+ <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">
+
+ <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>
+<OL> <!-- (set item[0] to 0 -->
+ <LI>item <!-- increment item[0] to 1 -->
+ <LI>item <!-- increment item[0] to 2 -->
+ <OL> <!-- (set item[1] to 0 -->
+ <LI>item <!-- increment item[1] to 1 -->
+ <LI>item <!-- increment item[1] to 2 -->
+ <LI>item <!-- increment item[1] to 3 -->
+ <OL> <!-- (set item[2] to 0 -->
+ <LI>item <!-- increment item[2] to 1 -->
+ </OL> <!-- ) -->
+ <OL> <!-- (set item[3] to 0 -->
+ <LI> <!-- increment item[3] to 1 -->
+ </OL> <!-- ) -->
+ <LI>item <!-- increment item[0] to 3 -->
+ <LI>item <!-- increment item[0] to 4 -->
+</OL> <!-- ) -->
+<OL> <!-- (set item[4] to 0 -->
+ <LI>item <!-- increment item[4] to 1 -->
+ <LI>item <!-- increment item[4] to 2 -->
+</OL> <!-- ) --></pre>
+ </div>
+
+ <p>The 'counters()' function generates a string composed of the values of all counters with the same name, separated by a given string.
+
+ <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>
+ </div>
+
+
+<h3 id='counters-without-boxes'>
+Counters in elements that do not generate boxes</h3>
+
+ <p>An element that does not generate a box (for example, an element with 'display' set to ''none'', or a pseudo-element with 'content' set to ''none'') cannot set, reset, or increment a counter. The counter properties are still valid on such an element, they simply must have no effect.</p>
+
+ <div class="example">
+ <p>For example, with the following style sheet, H2s with class "secret" do not increment 'count2'.
+
+ <pre>
+h2 { counter-increment: count2; }
+h2.secret { display: none; }</pre>
+ </div>
+
+ <p>Other methods of "hiding" elements, such as setting 'visibility' to ''hidden'', must have no effect on counters.</p>
+
+
+<h2 id='counter-function'>
+Printing Counters: the ''counter()'' and ''counters()'' functions</h2>
+
+ <p>Counters have no visible effect by themselves, but their values can be used in the ''counter()'' and ''counters()'' functions to generate counter representations. This happens automatically in the default contents of ''::marker'' pseudo-elements, but can be used by an author anywhere that accepts a string. Their syntax is:</p>
+
+ <pre>
+<dfn><counter-function></dfn> = counter(name [, [ <counter-style> | none ] ]? )
+<dfn><counters-function></dfn> = counters(name, <string>[, [ <counter-style> | none ] ]? )</pre>
+
+ <p>For both functions, if the ''<counter-style>'' is omitted it defaults to ''decimal''.</p>
+
+ <p>A ''<counter-function>'' represents the string obtained when one <i title='generate-a-counter'>generates a counter representation</i> of the named counter's value using the function's ''<counter-style>''. 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 ''counter()'' appears is used. If there are no counters of that name in scope, use the value ''0'' to generate the counter representation. If ''none'' is provided as the second argument, the ''<counter-function>'' instead represents the empty string.</p>
+
+ <div class="example">
+ <pre>
+H1:before { content: counter(chno, upper-latin) ". " }
+/* Generates headings like "A. A History of Discontent" */
+
+H2:before { content: counter(section, upper-roman) " - " }
+/* Generates headings like "II - The Discontent Part" */
+
+BLOCKQUOTE:after { content: " [" counter(bq, decimal) "]" }
+/* Generates blockquotes that end like "... [3]" */
+
+DIV.note:before { content: counter(notecntr, disc) " " }
+/* Simply generates a bullet before every div.note */
+
+P:before { content: counter(p, none) }
+/* inserts nothing */</pre>
+ </div>
+
+ <p>A ''<counters-function>'' represents the string obtained by the following algorithm:</p>
+
+ <ol>
+ <li>Collect all counters of the given name that are in scope for the elements on which ''counters()'' 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 ''0''.</li>
+
+ <li>Render each counter as a string by <i title='generate-a-counter'>generating a counter representation</i> of the counter's value using the function's <counter-style>. If ''none'' is provided as the third argument, instead render each counter as the empty string.</li>
+
+ <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.</li>
+ </ol>
+
+ <div class='example'>
+ <p>The following example shows a simple use of the ''counters()'' function:</p>
+
+ <pre>
+<ul>
+ <li>one</li>
+ <li>two
+ <ul>
+ <li>nested one</li>
+ <li>nested two</li>
+ </ul>
+ </li>
+ <li>three</li>
+</ul>
+<style>
+ul { counter-reset: list-item; }
+li { counter-increment: list-item; }
+li::marker { content: '(' counters(list-item,'.') ') '; }
+</style></pre>
+
+ <p>The preceding document should render something like this:</p>
+
+ <pre>
+(1) one
+(2) two
+ (2.1) nested one
+ (2.2) nested two
+(3) three</pre>
+ </div>
+
+ <div class='example'>
+ <p>Because counter scopes extend 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 ''counters()'' as the scopes of siblings won't nest, but one can create multiple counters and manually reference them instead:</p>
+
+ <pre>
+<h1>First H1</h1>
+...
+<h2>First H2 in H1</h2>
+...
+<h2>Second H2 in H1</h2>
+...
+<h3>First H3 in H2</h3>
+...
+<h1>Second H1</h1>
+...
+<h2>First H2 in H1</h2>
+...
+<style>
+body { counter-reset: h1 h2 h3; }
+h1 { counter-increment: h1; counter-reset: h2 h3;}
+h2 { counter-increment: h2; counter-reset: h3; }
+h3 { counter-increment: h3; }
+h1::before { content: counter(h1,upper-alpha) ' '; }
+h2::before { content: counter(h1,upper-alpha) '.'
+ counter(h2,decimal) ' '; }
+h3::before { content: counter(h1,upper-alpha) '.'
+ counter(h2,decimal) '.'
+ counter(h3,lower-roman) ' '; }
+</style></pre>
+
+ <p>The preceding document should render something like this:</p>
+
+ <pre>
+A First H1
+...
+A.1 First H2 in H1
+...
+A.2 Second H2 in H1
+...
+A.2.i First H3 in H2
+...
+B Second H1
+...
+B.1 First H2 in H1
+...</pre>
+ </div>
+
+
<h2 id='counter-style'>
Defining Custom Counter Styles: the ''@counter-style'' rule</h2>
@@ -858,7 +1180,7 @@
instead have their algorithm explicitly defined in the
<a href='#predefined-counters'>Complex Counter Styles</a> section.</p>
- <p>When asked to <i title='generate-a-counter'>generate a counter representation</i>
+ <p>When asked to <dfn title='generate-a-counter'>generate a counter representation</dfn>
using a particular counter style for a particular counter value, follow these steps:</p>
<ol>
Received on Wednesday, 7 December 2011 02:40:29 UTC