- From: Tab Atkins Jr.. via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 10 Mar 2011 19:54:17 +0000
- To: public-css-commits@w3.org
Update of /sources/public/csswg/css3-lists
In directory hutz:/tmp/cvs-serv16525
Modified Files:
Overview.src.html
Log Message:
First draft of the @counter-style chapter.
Index: Overview.src.html
===================================================================
RCS file: /sources/public/csswg/css3-lists/Overview.src.html,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -d -r1.26 -r1.27
--- Overview.src.html 4 Mar 2011 03:44:56 -0000 1.26
+++ Overview.src.html 10 Mar 2011 19:54:15 -0000 1.27
@@ -1140,6 +1140,415 @@
<!-- ====================================================================== -->
+<h2 id=counter-style>
+Defining Custom Counter Styles: the ''@counter-style'' rule</h2>
+
+ <p>CSS 2.1 defined a handful of useful counter styles based on the styles that
+ HTML traditionally allowed on ordered and unordered lists. This tiny set, though,
+ is quite inadequate for modern web pages; displaying an ordered list with markers
+ based on the latin alphabet while the content is Arabic seems quite incongruous!</p>
+
+ <p>Unfortunately, the set of potentially useful list styles is too large to
+ specify ahead-of-time - the world contains thousands of languages and hundreds
+ of scripts, not to mention the near-infinite stylistic variations found on the
+ web that go beyond mere languaged-based variation. The ''@counter-style'' rule
+ allows CSS to address this in an open-ended manner, by allowing the author
+ to define their own counter styles. These styles can then be used in the
+ 'list-style-type' property or in the ''counter()'' and ''counters()'' functions,
+ exactly like the predefined counter styles in CSS.</p>
+
+<h3 id=counter-style-syntax>
+@counter-style Syntax</h3>
+
+ <p>The ''@counter-style'' rule is defined as:</p>
+
+ <xmp class=prod>
+@counter-style <counter-style-name> {
+ type:
+ range:
+ glyphs:
+ additive-glyphs:
+ cjk-glyphs:
+ prefix:
+ suffix:
+ fallback:
+}
+ </xmp>
+
+ <p class=issue>Copy the way other specs define new @-rules that contain decl
+ blocks, like @font-face.</p>
+
+ <p>The <counter-style-name> must be be a valid identifier, and must not be
+ ''decimal''; violating these rules is a syntax error and must cause the @counter-style
+ block to be ignored.</p>
+
+ <p>Omitting the 'type' property in a @counter-style block is a syntax error
+ and must cause the @counter-style block to be ignored. A @counter-style block
+ must contain exactly one of 'glyphs', 'additive-glyphs', or 'cjk-glyphs'; containing
+ none of them or more than one of them is a syntax error and must cause the
+ @counter-style block to be ignored. Further, which of those three is present
+ must match the 'type' value: if the type is ''additive'', the 'additive-glyphs'
+ property must be present; if the type is ''cjk'', the 'cjk-glyphs' property
+ must be present; if the type is any other valid type, the 'glyphs' property
+ must be present. Violating any of the conditions in the preceding sentence
+ is a syntax error and must cause the @counter-style block to be ignored.
+ Individual types may impose additional requirements on the value of the 'glyphs'
+ property; if so, violating these requirements is a syntax error and must cause
+ the @counter-style block to be ignored.</p>
+
+ <p>The meaning and values of each of the properties are defined in the following
+ section.</p>
+
+<h4 id=counter-style-type>
+The 'type' Property</h4>
+
+ <p>The 'type' property specifies which algorithm will be used to construct
+ the counter's representation based on the counter value. For example, ''repeating''
+ type counter styles just cycle through their glyphs repeatedly, while ''numeric''
+ type counter styles interpret their glyphs as digits and build their representation
+ accordingly. It is defined as:
+
+ <xmp class=prod>
+<counter-type> = repeating | numeric | alphabetic | symbolic | [ non-repeating <integer>? ] | cjk | additive
+ </xmp>
+
+ <dl>
+ <dt><dfn>repeating</dfn></dt>
+ <dd>
+ <p>If the type is ''repeating'', the 'glyphs' property must contain
+ at least one <i>counter glyph</i>. This type is defined over all counter
+ values.</p>
+
+ <p>The ''repeating'' counter type cycles repeatedly through its provided
+ glyphs, looping back to the beginning when it falls off the end of the
+ list. It can be used for simple bullets (just provide a single
+ <i>counter glyph</i>), or for cycling through multiple bullets. The
+ first <i>counter glyph</i> is used as the representation of the value
+ 1, the second <i>counter glyph</i> (if it exists) is used as the representation
+ of the value 2, etc.</p>
+
+ <p>In general, if there are <code>N</code> <i>counter glyphs</i> and
+ a representation is being constructed for the value <code>I</code>,
+ the representation is the <i>counter glyph</i> at index <code>I mod N</code>
+ of the list of <i>counter glyphs</i> (indexed from 0).
+ <span class=note>The <code>mod</code> must return a non-negative number
+ for these purposes. If an implementation of <code>mod</code> returns
+ a negative value for negative inputs, add <code>N</code> to the resultant
+ value to make it non-negative.</span></p>
+
+ <div class=example>
+ <p>A 'triangle bullet' list style can be defined with code like:</p>
+
+ <xmp>
+@counter-style triangle {
+ type: repeating;
+ glyphs: "▶";
+}
+ </xmp>
+
+ <p>It will then produce lists that look like:</p>
+
+ <pre>
+ ▶ First item
+ ▶ Second item
+ ▶ Third item
+ </pre>
+ </div>
+ </dd>
+
+ <dt><dfn>numeric</dfn></dt>
+ <dd>
+ <p>If the type is ''numeric'', the 'glyphs' property must contain at
+ least two <i>counter glyph</i>s. This type is defined over all counter
+ values.</p>
+
+ <p>The ''numeric'' counter type cycles interprets the list of
+ <i>counter glyphs</i> as digits to a number system.</p>
+
+ <p>The first <i>counter glyph</i> in the list is interpreted as the
+ digit 0, the second as the digit 1, and so on. If there are <var>N</var>
+ <i>counter glyph</i>s, the representation is a base <var>N</var>
+ number using the <i>counter glyph</i>s as digits.</p>
+
+ <p>To construct the representation, run the following algorithm. Let
+ <var>N</var> be the length of the list of <i>counter glyphs</i>,
+ <var>I</var> initially be the counter value, <var>S</var>
+ initially be the empty string, <var>negative</var> be a boolean flag
+ that is initially false, and <code>glyph(n)</code> be the nth
+ <i>counter glyph</i> in the list of <i>counter glyph</i>s (0-indexed).</p>
+
+ <ol>
+ <li>If <var>I</var> is 0, append <code>glyph(0)</code> to
+ <var>S</var> and return <var>S</var>.</li>
+
+ <li>If <var>I</var> is negative, set <var>negative</var> to
+ true and <var>I</var> to its absolute value.</li>
+
+ <li>While <var>I</var> is not equal to 0:
+
+ <ol>
+ <li>Prepend <code>glyph( <var>I</var> mod <var>N</var> )</code>
+ to <var>S</var>.</li>
+
+ <li>Set <var>I</var> to <code>floor( <var>I</var> / <var>N</var> )</code>.</li>
+ </ol>
+ </li>
+
+ <li>If <var>negative</var> is true, prepend "-" U+XXXX HYPHEN MINUS
+ to <var>S</var>.</li>
+
+ <li>Return <var>S</var>.</li>
+ </ol>
+
+ <div class=example>
+ <p class=issue>Example here.</p>
+ </div>
+ </dd>
+
+ <dt><dfn>alphabetic</dfn></dt>
+ <dd>
+ <p>If the type is ''alphabetic'', the 'glyphs' property must contain
+ at least two <i>counter glyph</i>s. This type is defined only over
+ positive counter values.</p>
+
+ <p>The ''alphabetic'' counter type interprets the list of <i>counter glyphs</i>
+ as digits to an <em>alphabetic</em> numbering system. Alphabetic
+ numbering systems do not contain a digit representing 0. Alphabetic
+ numbering systems are sometimes used, for example, to number spreadsheet
+ cells
+
+ <p>The first <i>counter glyph</i> in the list is interpreted as the
+ digit 1, the second as the digit 2, and so on. If there are <var>N</var>
+ <i>counter glyph</i>s, the representation is a base <var>N</var>
+ alphabetic number using the <i>counter glyph</i>s as digits.</p>
+
+ <p>To construct the representation, run the following algorithm. Let
+ <var>N</var> be the length of the list of <i>counter glyph</i>s,
+ <var>I</var> initially be the counter value, <var>S</var> initially
+ be the empty string, and <code>glyph(n)</code> be the nth <i>counter glyph</i>
+ in the list of <i>counter glyph</i>s (0-indexed).</p>
+
+ <p>While <var>I</var> is not equal to 0:</p>
+
+ <ol>
+ <li>Set <var>I</var> to <code><var>I</var> - 1</code>.</li>
+
+ <li>Prepend <code>glyph( <var>I</var> mod <var>N</var> )</code>
+ to <var>S</var>.</li>
+
+ <li>Set <var>I</var> to <code>floor( <var>I</var> / <var>N</var> )</code>.</li>
+ </ol>
+
+ <p>Finally, return <var>S</var>.</p>
+
+ <div class=example>
+ <p class=issue>Example here.</p>
+ </div>
+ </dd>
+
+ <dt><dfn>symbolic</dfn></dt>
+ <dd>
+ <p>If the type is ''symbolic'', the 'glyphs' property must contain at
+ least one <i>counter glyph</i>. This type is defined over positive
+ counter values.</p>
+
+ <p>The ''symbolic'' counter type is meant to simulate "footnote"-style
+ counters and similar. It cycles through its list of glyphs repeatedly,
+ first just presenting the glyph itself, then the glyph doubled, then
+ tripled, etc.</p>
+
+ <p>To construct the representation, let <var>N</var> be the length of
+ the list of <i>counter glyph</i>s,<var>I</var> initially be the counter
+ value, <var>S</var> initially be the empty string, and <code>glyph(n)</code>
+ be the nth <i>counter glyph</i> in the list of <i>counter glyph</i>s
+ (0-indexed). Append <code>glyph( <var>I</var> mod <var>N</var> )</code>
+ to <var>S</var> <code>floor( (<var>I</var> - 1) / <var>N</var> )</code>
+ times, then return <var>S</var>.</p>
+
+ <div class=example>
+ <p class=issue>Example here.</p>
+ </div>
+ </dd>
+
+ <dt><dfn>non-repeating</dfn></dt>
+ <dd>
+ <p>If the type is ''non-repeating'', the 'glyphs' property must contain
+ at least one <i>counter glyph</i>. This type is defined over counter
+ values in a finite range, starting with the <i>first glyph value</i>
+ and having a length equal to the length of the list of <i>counter glyph</i>s.</p>
+
+ <p>When this type is specified, it may optionally have an integer provided
+ after it, which sets the <dfn>first glyph value</dfn>. If it is omitted,
+ the <i>first glyph value</i> is 1.</p>
+
+ <p>The ''non-repeating'' counter type is for representing counter styles
+ that only have a finite number of representations. For example, Unicode
+ defines several limited-length runs of special characters meant for
+ lists, such as circled digits.</p>
+
+ <p>The first <i>counter glyph</i> is the representation for the
+ <i>first glyph value</i>, and subsequent counter values are represented
+ by subsequent <i>counter glyph</i>s. Once the list of <i>counter glyph</i>s
+ is exhausted, further values cannot be represented by this type, and
+ must drop down to the fallback counter style.</p>
+
+ <div class=example>
+ <p class=issue>Example here.</p>
+ </div>
+ </dd>
+
+ <dt><dfn>additive</dfn></dt>
+ <dd>
+ <p>If the type is ''additive'', the 'additive-glyphs' property must
+ contain at least one <i>additive tuple</i>. This type is nominally
+ defined over all positive counter values (see algorith, below, for
+ exact details)</p>
+
+ <p>The ''additive'' counter type can be used to implement roman numerals,
+ and additionally is used to represent the numbering system of several
+ languages which use different digits for each position in a number.
+
+ <p>To construct the representation, let <var>I</var> initially be the
+ counter value, <var>S</var> initially be the empty string, and
+ <var>glyph list</var> initially be the list of <i>additive tuple</i>s.
+
+ <p>If <var>I</var> is initially 0, and there is an <i>additive tuple</i>
+ with a weight of 0, append that tuple's <i>counter glyph</i> to S
+ and return S.</p>
+
+ <p>Otherwise, while <var>I</var> is greater than 0 and there are elements
+ left in the <var>glyph list</var>:</p>
+
+ <ol>
+ <li>Pop the first <i>additive tuple</i> from the <var>glyph list</var>.
+ This is the <dfn>current tuple</dfn>.</li>
+
+ <li>Append the <i>current tuple</i>'s <i>counter glyph</i> to <var>S</var>
+ <code>floor( <var>I</var> / <var><i>current tuple</i>'s weight</var> )</code>
+ times (this may be 0).</li>
+ </ol>
+
+ <p>If the loop ended because <var>I</var> is 0, return S. If the loop
+ ended because there were no elements left in the <var>glyph list</var> but
+ <var>I</var> is not 0, then the counter style cannot represent this
+ value, and must instead drop down to its <i>fallback</i> counter style.</p>
+
+ <div class=example>
+ <p class=issue>Example here.</p>
+ </div>
+ </dd>
+
+ <dt><dfn>cjk</dfn></dt>
+ <dd>
+ <p>The ''cjk'' counter type is defined for all counter values between
+ 1 and 10^XXX - 1. It is used to represent the counter styles commonly
+ used in Chinese, Japanese, and Korean script lists.</p>
+
+ <div class=issue>
+ <p>Describe the algorithm here. Apparently, the spec algorithm
+ is wrong for both japanese forms, and at least chinese-trad-informal.
+ I'll have to figure out if it's even possible to handle this with
+ a generic algorithm, or if I should just put them all in the special-case
+ list.</p>
+ </div>
+ </dd>
+ </dl>
+
+<h3 id=counter-style-range>
+The 'range' property</h3>
+
+ <p>The 'range' property defines the range over which the counter style is defined.
+ If a counter style is used to represent a counter value outside of its range,
+ the counter style instead drops down to its fallback counter style. The property
+ is defined as:</p>
+
+ <xmp class=prod>
+<counter-range> = [<integer> | infinite]{2}
+ </xmp>
+
+ <p>The first value represents the lower bound of the range (with 'infinite'
+ representing negative infinity), and the second value represents the upper bound
+ of the range (with 'infinite' representing positive infinity). This is an inclusive
+ range - it includes both the lower and upper bound numbers. It is a syntax
+ error for the lower bound to be higher than the upper bound, and must cause
+ the @counter-style block to be ignored.</p>
+
+ <p>Some counter style types have their own implicit ranges, specified above
+ in the individual descriptions for each type. The range specified by the 'range'
+ property is applied after the implicit type-based range, and can only tighten
+ the range (that is, make the lower bound higher or the upper bound lower).
+ It is not an error to specify a 'range' value larger than the implicit range;
+ the part of the range outside the implicit range simply has no effect.</p>
+
+<h3 id=counter-style-glyphs>
+The 'glyphs' property</h3>
+
+ <p>The 'glyphs' property specifies the <i>counter glyph</i>s used by several
+ of the counter style types to construct their representations. It is defined
+ as:</p>
+
+ <xmp class=prod>
+<counter-glyphs> = [ <string> | <image> ]+
+ </xmp>
+
+ <p>Some counter style types specify that the 'glyphs' property must have at
+ least two entries. If the counter style's type is set to such a type, it is
+ a syntax error to have less than two entries in the 'glyphs' property and must
+ cause the @counter-style block to be ignored.</p>
+
+ <p>Each entry in the 'glyphs' property is a <dfn>counter glyph</dfn>.</p>
+
+ <div class=example>
+ <p class=issue>Add example of string glyphs.</p>
+ <p class=issue>Add example of image glyphs.</p>
+ </div>
+
+<h3 id=counter-style-prefix>
+The 'prefix' property</h3>
+
+ <p>The 'prefix' property specifies a string that is placed before the representation
+ of the counter value when constructing the default contents of the ::marker
+ pseudo-element. It is defined as:</p>
+
+ <xmp class=prod>
+<counter-prefix> = <string>
+ </xmp>
+
+ <p>If the 'prefix' property is omitted or invalid, its initial value is ""
+ (the empty string).</p>
+
+<h3 id=counter-style-suffix>
+The 'suffix' property</h3>
+
+ <p>The 'suffix' property specifies a string that is placed after the representation
+ of the counter value when constructing the default contents of the ::marker
+ pseudo-element. It is defined as:</p>
+
+ <xmp class=prod>
+<counter-suffix> = <string>
+ </xmp>
+
+ <p>If the 'suffix' property is omitted or invalid, its initial value is "."
+ U+002E FULL STOP.</p>
+
+<h3 id=counter-style-fallback>
+The 'fallback' property</h3>
+
+ <p>The 'fallback' property specifies a fallback counter style. When the
+ given counter style cannot generate a representation for a counter value (for
+ example, if the counter value is outside the range for the counter style), the
+ representation is instead generated by the fallback counter style. It is defined
+ as:</p>
+
+ <xmp class=prod>
+<counter-style-fallback> = <counter-style-name>
+ </xmp>
+
+ <p>If the 'fallback' property is omitted, invalid, or refers to a non-existent
+ counter style, its initial value is 'decimal' (which is guaranteed to be defined).</p>
+
+<!-- ======================================================================= -->
+
<h2 id="profiles">
Profiles</h2>
Received on Thursday, 10 March 2011 19:54:19 UTC