8000 csswg-drafts/css-counter-styles/Overview.src.html at a14d899dab626e5cb21b63a1abf5519953d61d57 · xfq/csswg-drafts · GitHub
Skip to content

Overview.src.html

Latest commit

 

History

History
2402 lines (2030 loc) · 84.1 KB

Overview.src.html

File metadata and controls

2402 lines (2030 loc) · 84.1 KB
<h1>CSS Counter Styles Level 3</h1>
<pre class=metadata>
Shortname: css-counter-styles
Level: 3
Status: ED
ED: http://dev.w3.org/csswg/css-counter-styles/
TR: http://w3.org/TR/css-counter-styles-3/
Previous Version: http://www.w3.org/TR/2012/WD-css-counter-styles-3-20121009/
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/
Abstract: This module introduces the ‘@counter-style’ rule, which allows authors to define their own custom counter styles for use with CSS list-marker and generated-content counters [[CSS3LIST]]. It also predefines a set of common counter styles, including the ones present in CSS2 and CSS2.1.
Issue Tracking: <a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=CSS&component=Counter%20Styles&resolution=---">Bugzilla</a>
At Risk: the counter styles ''cjk-decimal'', ''hebrew'', ''hiragana'', ''hiragana-iroha'', ''katakana'', ''katakana-iroha'', ''japanese-informal'', ''japanese-formal'', ''korean-hangul-formal'', ''korean-hanja-informal'', ''korean-hanja-formal'', ''simp-chinese-informal'', ''simp-chinese-formal'', ''trad-chinese-informal'', ''trad-chinese-formal'', and ''ethiopic-numeric''.
Ignored Properties: content, list-style-type, list-style
Ignored Terms: <image>, <integer>, <string>
</pre>
<style>
pre.stylesheet { white-space: pre-wrap; }
</style>
<h2 id='intro'>
Introduction</h2>
CSS 1 defined a handful of useful counter styles based on the styles that HTML traditionally allowed on ordered and unordered lists.
While this was expanded slightly by CSS2.1,
it doesn't address the needs of worldwide typography.
This module introduces the ''@counter-style'' rule which 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.
It also defines some additional predefined counter styles,
particularly ones which are common but complicated to represent with ''@counter-style''.
<h2 id='counter-styles'>
Counter Styles</h2>
A <dfn>counter style</dfn> defines how to convert a counter value into a string.
Counter styles are composed of:
<ul>
<li>
a name,
to identify the style
<li>
an algorithm,
which transforms integer counter values into a basic string representation
<li>
a negative sign,
which is prepended or appended to the representation of a negative counter value.
<li>
a prefix,
to prepend to the representation
<li>
a suffix
to append to the representation
<li>
a range,
which limits the values that a counter style handles
<li>
a spoken form,
which describes how to read out the counter style in a speech synthesizer
<li>
and a fallback style,
to render the representation with when the counter value is outside the counter style's range
or the counter style otherwise can't render the counter value
</ul>
When asked to <dfn title='generate a counter|generate a counter representation'>generate a counter representation</dfn>
using a particular counter style for a particular counter value,
follow these steps:
<ol>
<li>
If the counter value is outside the <i>range</i> of the counter style,
exit this algorithm and instead <i>generate a counter representation</i>
using the counter style's fallback style and the same counter value.
<li>
Using the counter value and the counter algorithm for the counter style,
generate an initial representation for the counter value.
If the counter value is negative
and the counter style is <i>negative-capable</i>,
instead generate an initial representation using the absolute value of the counter value.
<li>
If the representation uses less symbols than specified in the counter style's 'fill' descriptor,
prepend symbols to the representation as specified in the 'fill' descriptor.
<li>
If the counter value is negative
and the counter style is <i>negative-capable</i>,
wrap the representation in the counter style's negative sign
as specified in the 'negative' descriptor.
<li>
Return the representation.
</ol>
Note: the prefix and suffix don't play a part in this algorithm.
This is intentional;
the prefix and suffix aren't part of the string returned by the counter() or counters() functions.
Instead, the prefix and suffix are added by the algorithm that constructs the value of the 'content' property for the ''::marker'' pseudo-element.
This also implies that the prefix and suffix always come from the specified counter-style,
even if the actual representation is constructed by a fallback style.
<h2 id='the-counter-style-rule'>
Defining Custom Counter Styles: the ''@counter-style'' rule</h2>
The <dfn id='at-counter-style'>''@counter-style''</dfn> rule allows authors to define a custom <i>counter style</i>.
The components of a <i>counter style</i> are specified by descriptors in the ''@counter-style'' rule.
The algorithm is specified implicitly by a combination of the ''system'', ''symbols'', and ''additive-symbols'' properties.
The general form of an ''@counter-style'' rule is:
<pre>
@counter-style <i>&lt;counter-style-name></i> {
[ descriptor: value; ]+
}
</pre>
The <i>&lt;counter-style-name></i> must be be a valid identifier
and must not be ''decimal'' or ''none'',
or else the rule is invalid.
(Note, however, that some names, like ''inside'' or ''initial'',
might conflict with the existing values of properties like 'list-style',
and thus won't be usable there.)
Counter style names are case-sensitive.
However, the names defined in this specification are ASCII lower-cased on parse
wherever they are used as counter styles, e.g.
in the 'list-style' set of properties,
in the ''@counter-style'' rule,
and in the ''counter()'' functions.
Each ''@counter-style'' rule specifies a value for every counter-style descriptor,
either implicitly or explicitly.
Those not given explicit value in the rule take the initial value listed with each descriptor in this specification.
These descriptors apply solely within the context of the ''@counter-style'' rule in which they are defined,
and do not apply to document language elements.
There is no notion of which elements the descriptors apply to or whether the values are inherited by child elements.
When a given descriptor occurs multiple times in a given ''@counter-style'' rule,
only the last specified value is used;
all prior values for that descriptor must be ignored.
Defining a ''@counter-style'' makes it available to the entire document in which it is included.
If multiple ''@counter-style'' rules are defined with the same name,
only one wins,
according to standard cascade rules.
''@counter-style'' rules cascade "atomically":
if one replaces another of the same name,
it replaces it <em>entirely</em>,
rather than just replacing the specific descriptors it specifies.
This at-rule conforms with the forward-compatible parsing requirement of CSS;
conformant parsers that don't understand these rules will ignore them without error.
Any descriptors that are not recognized or implemented by a given user agent must be ignored in their entirety;
they do not make the ''@counter-style'' rule invalid.
<h3 id='counter-style-system'>
Counter algorithms: the 'system' descriptor</h3>
<table class='descdef'>
<tr>
<th>Name:
<td><dfn>system</dfn>
<tr>
<th>Value:
<td>cyclic | numeric | alphabetic | symbolic | additive | <span class=nobr>[fixed &lt;integer>?]</span> | <span class=nobr>[ override &lt;counter-style-name> ]</span>
<tr>
<th>Initial:
<td>symbolic
</table>
The 'system' descriptor specifies which algorithm will be used to construct
the counter's representation based on the counter value. For example,
''cyclic'' counter styles just cycle through their symbols repeatedly,
while ''numeric'' counter styles interpret their symbols as digits and
build their representation accordingly. The systems are defined as follows:
<h4 id="cyclic-system">
Cycling Symbols: the ''cyclic'' system</h4>
The <dfn>''cyclic''</dfn> counter system cycles repeatedly through its provided symbols,
looping back to the beginning when it reaches the end of the list.
It can be used for simple bullets
(just provide a single <i>counter symbol</i>),
or for cycling through multiple symbols.
The first <i>counter symbol</i> is used as the representation of the value 1,
the second <i>counter symbol</i> (if it exists) is used as the representation of the value 2, etc.
If the system is ''cyclic'',
the 'symbols' descriptor must contain at least one <i>counter symbol</i>,
or else the ''@counter-style'' rule is invalid.
This system is defined over all counter values.
<div class=example>
A "triangle bullet" counter style can be defined as:
<pre>
@counter-style <dfn>triangle</dfn> {
system: cyclic;
symbols: ‣;
suffix: "";
}
</pre>
It will then produce lists that look like:
<pre>
‣ One
‣ Two
‣ Three
</pre>
</div>
If there are <var>N</var> <i>counter symbols</i>
and a representation is being constructed for the integer <var>value</var>,
the representation is the <i>counter symbol</i>
at index ( (<var>value</var>-1) mod <var>N</var>)
of the list of <i>counter symbols</i> (0-indexed).
<h4 id="fixed-system">
Exhaustible Symbols: the ''fixed'' system</h4>
The <dfn>''fixed''</dfn> counter system runs through its list of counter symbols once,
then falls back.
It is useful 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.
If the system is ''fixed'',
the 'symbols' descriptor must contain at least one <i>counter symbol</i>,
or else the ''@counter-style'' rule is invalid.
This system is defined over counter values in a finite range,
starting with the <i>first symbol value</i> and having a length equal to the length of the list of <i>counter symbols</i>.
When this system is specified,
it may optionally have an integer provided after it,
which sets the <dfn>first symbol value</dfn>.
If it is omitted, the <i>first symbol value</i> is 1.
<div class=example>
A "box-corner" counter style can be defined as:
<pre>
@counter-style <dfn>box-corner</dfn> {
system: fixed;
symbols: ◰ ◳ ◲ ◱;
suffix: ':';
}
</pre>
It will then produce lists that look like:
<pre>
◰: One
◳: Two
◲: Three
◱: Four
5: Five
6: Six
</pre>
</div>
The first <i>counter symbol</i> is the representation for the <i>first symbol value</i>,
and subsequent counter values are represented by subsequent <i>counter symbols</i>.
Once the list of <i>counter symbols</i> is exhausted,
further values cannot be represented by this counter style,
and must instead be represented by the fallback counter style.
<h4 id="symbolic-system">
Repeating Symbols: the ''symbolic'' system</h4>
The ''symbolic'' counter system cycles repeatedly through its provided symbols,
doubling, tripling, etc. the symbols on each successive pass through the list.
For example, if the original symbols were "*" and "†",
then on the second pass they would instead be "**" and "††",
while on the third they would be "***"and "†††", etc.
It can be used for footnote-style markers,
and is also sometimes used for alphabetic-style lists for a slightly different presentation than what the ''alphabetic'' system presents.
If the system is <dfn>''symbolic''</dfn>,
the 'symbols' descriptor must contain at least one <i>counter symbol</i>,
or else the ''@counter-style'' rule is invalid.
This system is defined only over strictly positive counter values.
<div class=example>
An "footnote" counter style can be defined as:
<pre>
@counter-style <dfn>footnote</dfn> {
system: symbolic;
symbols: '*' ⁑ † ‡;
suffix: "";
}
</pre>
It will the 1898 n produce lists that look like:
<pre>
* One
⁑ Two
† Three
‡ Four
** Five
⁑⁑ Six
</pre>
</div>
<div class=example>
Some style guides mandate a list numbering that looks similar to ''upper-alpha'',
but repeats differently after the first 26 values,
instead going "AA", "BB", "CC", etc.
This can be achieved with the symbolic system:
<pre>
@counter-style <dfn>upper-alpha-legal</dfn> {
system: symbolic;
symbols: A B C D E F G H I J K L M
N O P Q R S T U V W X Y Z;
}
</pre>
This style is identical to ''upper-alpha'' through the first 27 values,
but they diverge after that, with ''upper-alpha'' going "AB", "AC", "AD", etc.
Starting at the 53rd value, ''upper-alpha'' goes "BA", "BB", "BC", etc.,
while this style jumps into triple digits with "AAA", "BBB", "CCC", etc.
</div>
To construct the representation, run the following algorithm:
Let <var>N</var> be the length of the list of <i>counter symbols</i>,
<var>value</var> initially be the counter value,
<var>S</var> initially be the empty string,
and <var>symbol(n)</var> be the nth <i>counter symbol</i> in the list of <i>counter symbols</i> (0-indexed).
<ol>
<li>Let the <var>chosen symbol</var> be <code class='inline'>symbol(<var>value</var> mod <var>N</var>)</code>.
<li>Let the <var>representation length</var> be <code class='inline'>floor( (<var>value</var> - 1) / <var>N</var> )</code>.
<li>Append the <var>chosen symbol</var> to <var>S</var> a number of times equal to the <var>representation length</var>.
</ol>
Finally, return <var>S</var>.
The ''symbolic'' system will produce representations with sizes that are linear in the magnitude of the counter value.
This can potentially be abused to generate excessively large representations
and consume undue amounts of the user's memory or even hang their browser.
User agents must support representations at least 20 characters long,
but they may choose to instead use the fallback style for representations that would be longer than 20 characters.
<h4 id="alphabetic-system">
Bijective Numerals: the ''alphabetic'' system</h4>
The ''alphabetic'' counter system interprets the list of <i>counter symbols</i> as digits to an <em title=''>alphabetic</em> numbering system,
similar to the default ''lower-alpha'' counter style,
which wraps from "a", "b", "c", to "aa", "ab", "ac".
Alphabetic numbering systems do not contain a digit representing 0;
so the first value when a new digit is added is composed solely of the first digit.
Alphabetic numbering systems are commonly used for lists,
and also appear in many spreadsheet programs to number columns.
The first <i>counter symbol</i> in the list is interpreted as the digit 1,
the second as the digit 2,
and so on.
If the system is <dfn>''alphabetic''</dfn>,
the 'symbols' descriptor must contain at least two <i>counter symbols</i>,
or else the ''@counter-style'' rule is invalid.
This system is defined only over strictly positive counter values.
<div class=example>
A counter style using go stones can be defined as:
<pre>
@counter-style <dfn>go</dfn> {
system: alphabetic;
symbols: url(white.svg) url(black.svg);
suffix: "";
}
</pre>
It will then produce lists that look like:
<div class='alphabetic-example'>
<span><img src=images/white.svg alt=""></span> One<br>
<span><img src=images/black.svg alt=""></span> Two<br>
<span><img src=images/white.svg alt=""><img src=images/white.svg alt=""></span> Three<br>
<span><img src=images/white.svg alt=""><img src=images/black.svg alt=""></span> Four<br>
<span><img src=images/black.svg alt=""><img src=images/white.svg alt=""></span> Five<br>
<span><img src=images/black.svg alt=""><img src=images/black.svg alt=""></span> Six<br>
<span><img src=images/white.svg alt=""><img src=images/white.svg alt=""><img src=images/white.svg alt=""></span> Seven
</div>
Note: This example requires support for SVG images to display correctly.
</div>
If there are <var>N</var> <i>counter symbols</i>,
the representation is a base <var>N</var> alphabetic number using the <i>counter symbols</i> as digits.
To construct the representation, run the following algorithm:
Let <var>N</var> be the length of the list of <i>counter symbols</i>,
<var>value</var> initially be the counter value,
<var>S</var> initially be the empty string,
and <var>symbol(n)</var> be the nth <i>counter symbol</i> in the list of <i>counter symbols</i> (0-indexed).
While <var>value</var> is not equal to 0:
<ol>
<li>Set <var>value</var> to <code><var>value</var> - 1</code>.
<li>Prepend <var>symbol( <var>value</var> mod <var>N</var> )</var>
to <var>S</var>.
<li>Set <var>value</var> to <code>floor( <var>value</var> / <var>N</var> )</code>.
</ol>
Finally, return <var>S</var>.
<h4 id="numeric-system">
Positional Numerals: the ''numeric'' system</h4>
The <dfn>numeric</dfn> counter system interprets the list of <i>counter symbols</i>
as digits to a "place-value" numbering system,
similar to the default ''decimal'' counter style.
The first <i>counter symbol</i> in the list is interpreted as the digit 0,
the second as the digit 1,
and so on.
If the system is ''numeric'',
the 'symbols' descriptor must contain at least two <i>counter symbols</i>,
or else the ''@counter-style'' rule is invalid.
This system is defined over all counter values.
<div class=example>
A "trinary" counter style can be defined as:
<pre>
@counter-style <dfn>trinary</dfn> {
system: numeric;
symbols: '0' '1' '2';
}
</pre>
It will then produce lists that look like:
<pre>
1. One
2. Two
10. Three
11. Four
12. Five
20. Six
</pre>
</div>
If there are <var>N</var> <i>counter symbols</i>,
the representation is a base <var>N</var> number using the <i>counter symbols</i> as digits.
To construct the representation, run the following algorithm:
Let <var>N</var> be the length of the list of <i>counter symbols</i>,
<var>value</var> initially be the counter value,
<var>S</var> initially be the empty string,
and <var>symbol(n)</var> be the nth <i>counter symbol</i> in the list of <i>counter symbols</i> (0-indexed).
<ol>
<li>If <var>value</var> is 0, append <var>symbol(0)</var> to
<var>S</var> and return <var>S</var>.
<li>While <var>value</var> is not equal to 0:
<ol>
<li>Prepend <var>symbol( <var>value</var> mod <var>N</var> )</var>
to <var>S</var>.
<li>Set <var>value</var> to <code>floor( <var>value</var> / <var>N</var> )</code>.
</ol>
<li>Return <var>S</var>.
</ol>
<h4 id="additive-system">
Accumulating Numerals: the ''additive'' system</h4>
The <dfn>''additive''</dfn> counter system is used to represent "sign-value" numbering systems,
which, rather than using reusing digits in different positions to change their value,
define additional digits with much larger values,
so that the value of the number can be obtained by adding all the digits together.
This is used in Roman numerals
and other numbering systems around the world.
If the system is ''additive'',
the 'additive-symbols' descriptor must contain at least one <i>additive tuple</i>,
or else the ''@counter-style'' rule is invalid.
This system is nominally defined over all counter values
(see algorithm, below, for exact details).
<div class=example>
A "dice" counter style can be defined as:
<pre>
@counter-style <dfn>dice</dfn> {
system: additive;
additive-symbols: 6 ⚅, 5 ⚄, 4 ⚃, 3 ⚂, 2 ⚁, 1 ⚀;
suffix: "";
}
</pre>
It will then produce lists that look like:
<pre>
⚀ One
⚁ Two
⚂ Three
...
⚅⚄ Eleven
⚅⚅ Twelve
⚅⚅⚀ Thirteen
</pre>
</div>
To construct the representation, run this algorithm:
Let <var>value</var> initially be the counter value,
<var>S</var> initially be the empty string,
and <var>symbol list</var> initially be the list of <i>additive tuples</i>.
<ol>
<li>If <var>value</var> is initially 0, and there is an <i>additive tuple</i> with a weight of 0, append that tuple's <i>counter symbol</i> to S and return S.
<li>While <var>value</var> is greater than 0 and there are elements left in the <var>symbol list</var>:
<ol>
<li>Pop the first <i>additive tuple</i> from the <var>symbol list</var>.
This is the <dfn title="current tuple|current tuple's">current tuple</dfn>.
<li>Append the <i>current tuple</i>&apos;s <i>counter symbol</i> to <var>S</var>
<code>floor( <var>value</var> / <var><i>current tuple's</i> weight</var> )</code>
times (this may be 0).
<li>Decrement <var>value</var> by the <var><i>current tuple's</i></var> weight multiplied
by the number of times the <i>current tuple</i> was appended to <var>S</var>
in the previous step.
</ol>
<li>If the loop ended because <var>value</var> is 0, return S. Otherwise, the given counter value cannot be represented by this counter style, and must instead be represented by the fallback counter style.
</ol>
The ''additive'' system will produce representations with sizes that are linear in the magnitude of the counter value.
This can potentially be abused to generate excessively large representations and consume undue amounts of the user's memory or even hang their browser.
User agents must support representations at least 20 characters long,
but they may choose to instead use the fallback style for representations that would be longer than 20 characters.
<h4 id="override-system">
Tweaking Existing Counter Styles: the ''override'' system</h4>
The <dfn>''override''</dfn> system allows an author to use the algorithm of another counter style,
but alter other aspects,
such as the negative sign or the suffix.
If a counter style uses the ''override'' system,
any unspecified descriptors must be taken from the overridden counter style specified,
rather than taking their initial values.
If a @counter-style uses the ''override'' system,
it must not contain a 'symbols' or 'additive-symbols' descriptor,
or else the ''@counter-style'' rule is invalid.
If the specified counter style name isn't the name of any currently-defined counter style,
it must be treated as if it was overriding the ''decimal'' counter style.
<h3 id='counter-style-negative'>
Formatting negative values: the 'negative' descriptor</h3>
<pre class='descdef'>
Name: negative
Value: <<symbol>> <<symbol>>?
Initial: "\2D" ("-" hyphen-minus)
</pre>
The 'negative' descriptor defines how to alter the representation when
the counter value is negative.
The first <var>&lt;symbol></var> in the value is prepended to the representation when the
counter value is negative. The second <var>&lt;symbol></var>, if specified, is appended
to the representation when the counter value is negative.
<div class='example'>
For example, specifying ''negative: "(" ")";'' will make negative
values be wrapped in parentheses, which is sometimes used in financial
contexts, like "(2) (1) 0 1 2 3...".
</div>
Not all 'system' values use a negative sign.
In particular, a counter style is <dfn>negative-capable</dfn>
is one where its 'system' value is
''symbolic'',
''alphabetic'',
''numeric'',
''additive'',
or ''override'' if the overridden counter style is itself <i>negative-capable</i>.
If a counter style is not <i>negative-capable</i>,
it ignores the negative sign when <i title="generate a counter representation">generating a counter representation</i>.
<h3 id='counter-style-prefix'>
Symbols before the marker: the 'prefix' descriptor</h3>
<pre class='descdef'>
Name: prefix
Value: <<symbol>>
Initial: "" (the empty string)
</pre>
The 'prefix' descripter specifies a <var>&lt;symbol></var> that is prepended to the
marker representation. Prefixes are only added by the algorithm for constructing
the default contents of the ''::marker'' pseudo-element; the prefix is not
added automatically when the counter() or counters() functions are used.
Prefixes come before any negative sign.
<h3 id='counter-style-suffix'>
Symbols after the marker: the 'suffix' descriptor</h3>
<table class='descdef'>
<tr>
<th>Name:
<td><dfn>suffix</dfn>
<tr>
<th>Value:
<td><var>&lt;symbol></var>
<tr>
<th>Initial:
<td>"\2E" ("." full stop)
</table>
The 'suffix' descripter specifies a <var>&lt;symbol></var> that is appended to the
marker representation. Suffixes are only added by the algorithm for constructing
the default contents of the ''::marker'' pseudo-element; the suffix is not
added automatically when the counter() or counters() functions are used.
Suffixes are added to the representation after negative signs.
<h3 id='counter-style-range'>
Limiting the counter scope: the 'range' descriptor</h3>
<table class='descdef'>
<tr>
<th>Name:
<td><dfn>range</dfn>
<tr>
<th>Value:
<td>[ [ &lt;integer> | infinite ]{2} ]# | auto
<tr>
<th>Initial:
<td>auto
</table>
The 'range' descriptor defines the ranges over which the counter style is defined.
If a counter style is used to represent a counter value outside of its ranges,
the counter style instead drops down to its fallback counter style.
<dl>
<dt>auto
<dd>
The range depends on the counter system.
For ''cyclic'', ''numeric'', and ''fixed'' systems,
the range is negative infinity to positive infinity.
For ''alphabetic'' and ''symbolic'' systems,
the range is 1 to positive infinity.
For ''additive'' systems,
the range is 0 to positive infinity.
For ''override'' systems,
the range is identical to the overridden system.
<dt>[ [ &lt;integer> | infinite ]{2} ]#
<dd>
This defines a comma-separated list of ranges.
For each individual range,
the first value is the lower bound
and the second value is the upper bound.
This range is inclusive - it contains both the lower and upper bound numbers.
If ''infinite'' is used as the first value in a range,
it represents negative infinity;
if used as the second value,
it represents positive infinity.
The range of the counter style is the union of all the ranges defined in the list.
If the lower bound of any range is higher than the upper bound,
the entire descriptor is invalid and must be ignored.
</dl>
Implementations must support ranges with a lower bound of at least -2<sup>15</sup>
and an upper bound of at least 2<sup>15</sup>-1
(the range of a signed 2-byte int).
They may support higher ranges.
If any specified bound is outside of the implementation's supported bounds,
it must be treated as the closest bound that the implementation does support.
<h3 id='counter-style-fill'>
Zero-Padding and Constant-Width Representations: the 'fill' descriptor</h3>
<table class='descdef'>
<tr>
<th>Name:
<td><dfn>fill</dfn>
<tr>
<th>Value:
<td><var>&lt;integer></var> &amp;&amp; <var>&lt;symbol></var>
<tr>
<th>Initial:
<td>0 ""
</table>
The 'fill' descriptor allows an author to specify a "fixed-width" counter style,
where representations shorter than the fill are padded with a particular <<symbol>>.
Representations larger than the specified fill are constructed as normal.
<dl>
<dt><<integer>> &amp;&amp; <<symbol>>
<dd>
The <<integer>> specifies a minimum number of <<symbol>>s that all counter representations must reach.
If a counter representation would be generated using less <<symbol>>s than the specified <<integer>>
(before adding prefixes/suffixes/negatives),
prepend copies of the specified <<symbol>> to the representation
until the number of symbols reaches the specified fill.
The <<integer>> must be non-negative.
A negative value is a syntax error.
If the counter value is negative
and the counter style is <i>negative-capable</i>,
treat the minimum number of <<symbol>>s as being one or two smaller when determining how many copies to prepend,
depending on whether the 'negative' descriptor's value is one or two <var>&lt;symbol></var>s.
</dl>
<div class='example'>
The most common example of "fixed-width" numbering is zero-padded decimal numbering.
If an author knows that the numbers used will be less than a thousand, for example,
it can be zero-padded with a simple ''width: 3 "0";'' descriptor,
ensuring that all of the representations are 3 digits wide.
This will cause, for example,
1 to be represented as "001",
20 to be represented as "020",
300 to be represented as "300",
4000 to be represented as "4000",
and -5 to be represented as "-05".
</div>
Note: The 'fill' descriptor counts the number of <em><<symbol>>s</em> used to construct the representation,
not the number of characters,
and also pads the representation with <<symbol>>s.
For many styles, the distinction is irrelevant,
as all the <<symbol>>s are single-chararacter,
but if a style uses multi-character <<symbol>>s,
care must be taken not to accidentally specify 'fill' in terms of characters.
<h3 id='counter-style-fallback'>
Defining fallback: the 'fallback' descriptor</h3>
<table class='descdef'>
<tr>
<th>Name:
<td><dfn>fallback</dfn>
<tr>
<th>Value:
<td>&lt;counter-style-name>
<tr>
<th>Initial:
<td>decimal
</table>
The 'fallback' descriptor specifies a fallback counter style to be used
when the current counter style can't create a representation for a given
counter value. For example, if a counter style defined with a range of 1-10
is asked to represent a counter value of 11, the counter value's representation
is instead constructed with the fallback counter style (or possibly the
fallback style's fallback style, if the fallback style can't represent that
value, etc.).
If the value of the 'fallback' descriptor isn't the name of any
currently-defined counter style, the used value of the 'fallback' descriptor
is <i>decimal</i> instead. Similarly, while following fallbacks to find
a counter style that can render the given counter value, if a loop in the
specified fallbacks is detected, the <i>decimal</i> style must be used instead.
<p class='note'>Note that it is not necessarily an error to specify fallback
loops. For example, if an author desires a counter style with significantly
different representations for even and odd counter values, they may find it
easiest to define one style that can only represent odd values and one that
can only represent even values, and specify each as the fallback for the
other one. Though the fallback graph is circular, at no point do you encounter
a loop while following these fallbacks - every counter value is represented
by one or the other counter style.
<h3 id='counter-style-symbols'>
Marker characters: the 'symbols' and 'additive-symbols' descriptors</h3>
<table class='descdef'>
<tr>
<th>Name:
<td><dfn id="descdef-symbols">symbols</dfn>
<tr>
<th>Value:
<td><var>&lt;symbol></var>+
<tr>
<th>Initial:
<td>N/A
</table>
<table class='descdef'>
<tr>
<th>Name:
<td><dfn id="descdef-additive-symbols">additive-symbols</dfn>
<tr>
<th>Value:
<td>[ <var>&lt;integer></var> &amp;&amp; <var>&lt;symbol></var> ]#
<tr>
<th>Initial:
<td>N/A
</table>
<pre class='prod'><dfn>&lt;symbol></dfn> = &lt;string> | &lt;image> | &lt;identifier></pre>
The 'symbols' and &# 8812 039;additive-symbols' descriptors specify the symbols
used by the marker-construction algorithm specified by the 'system' descriptor.
The 'symbols' descriptor must be specified if the counter system is ''cyclic'',
''numeric'', ''alphabetic'', ''symbolic'', or ''fixed'', and the
'additive-symbols' descriptor must be specified if the counter system is
''additive''; otherwise, the ''@counter-style'' is invalid and must be ignored.
Some counter systems specify that the 'symbols' descriptor must have at
least two entries. If the counter style's system is such, and the 'symbols'
descriptor has only a single entry, the counter style is invalid and must
be ignored.
Each entry in the 'symbols' descriptor's value defines a <dfn>counter symbol</dfn>,
which is interpreted differently based on the counter style's system. Each
entry in the 'additive-symbols' descriptor's value defines an <dfn>additive tuple</dfn>,
which consists of a <i>counter symbol</i> and a non-negative integer weight.
Each weight must be a non-negative integer, and the <i>additive tuples</i>
must be specified in order of descending weight; otherwise, the @counter-style
is invalid and must be ignored.
<i>Counter symbols</i> may be strings, images, or identifiers,
and the three types can be mixed in a single descriptor.
Counter representations are constructed by concatenating counter symbols together.
Identifiers are rendered as strings containing the same characters.
Images are rendered as inline replaced elements.
The <a href="http://dev.w3.org/csswg/css3-images/#default-object-size">default object size</a> of an image <i>counter symbol</i> is a 1em by 1em square.
Note: If using identifiers rather than strings to define the symbols,
be aware of the syntax of identifiers.
In particular, ascii non-letters like "*" are not identifiers,
and so must be quoted in a string.
Hex escapes,
used in several of the counter styles defined in this specification,
"eat" the following space
(to allow a digit to follow a hex escape without ambiguity),
so two spaces must be put after a hex escape
to separate it from the following one,
or else they'll be considered adjacent,
and part of the same identifier.
<h3 id='counter-style-speak-as'>
Speech Synthesis: the 'speak-as' descriptor</h3>
<table class='descdef'>
<tr>
<th>Name:
<td><dfn id='descdef-speak-as'>speak-as</dfn>
<tr>
<th>Value:
<td>auto | numeric | alphabetic | bullet | &lt;counter-style-name>
<tr>
<th>Initial:
<td>auto
</table>
A counter style can be constructed with a meaning that is obvious visually,
but impossible to meaningfully represent via a speech synthesizer,
or possible but nonsensical when naively read out.
The 'speak-as' descriptor describes how to synthesize the spoken form of a counter formatted with the given counter style.
Values have the following meanings:
<dl>
<dt><dfn id='speak-as-auto'>''auto''</dfn>
<dd>
If the counter style's 'system' is ''alphabetic'', this value computes to ''alphabetic''.
If the 'system' is ''cyclic'', this value computes to ''bullet''.
Otherwise, this value computes to ''numeric''.
<dt><dfn id='speak-as-numeric' title="speak as: numeric">''numeric''</dfn>
<dd>
The counter's value is spoken as a number in the document language.
<dt><dfn id='speak-as-alphabetic' title="speak as: alphabetic">''alphabetic''</dfn>
<dd>
<i>Generate a counter representation</i> for the value as normal,
then spell it out letter-by-letter in the document language.
If the UA does not know how to pronounce the symbols,
it may handle it as ''numeric''.
For example, ''lower-greek'' in English would be read out as "alpha", "beta", "gamma", etc.
Conversely, ''upper-latin'' in French would be read out as (in phonetic notation) /a/, /be/, /se/, etc.
<dt><dfn id='speak-as-symbolic'>''bullet''</dfn>
<dd>
The UA speaks a UA-defined phrase or audio cue that represents a list item being read out.
<dt><dfn id='speak-as-counter-style'><var>&lt;counter-style-name></var></dfn>
<dd>
The counter's value is instead spoken out in the specific style.
If the specified style does not exist,
this value is treated as ''auto''.
</dl>
<div class='example'>
The ability to defer pronunciation to another counter style can help when the symbols being used aren't actually letters.
For example, here's a possible definition of a ''circled-lower-latin'' counter-style, using some special unicode characters:
<pre class='stylesheet'>
@counter-style <dfn>circled-lower-latin</dfn> {
system: alphabetic;
speak-as: lower-latin;
symbols: ⓐ ⓑ ⓒ ⓓ ⓔ ⓕ ⓖ ⓗ ⓘ ⓙ ⓚ ⓛ ⓜ ⓝ ⓞ ⓟ ⓠ ⓡ ⓢ ⓣ ⓤ ⓥ ⓦ ⓧ ⓨ ⓩ;
suffix: "";
}
</pre>
Setting its 'system' to ''alphabetic'' would normally make the UA try to read out the names of the characters,
but in this case that might be something like "Circled Letter A",
which is unlikely to make sense.
Instead, explicitly setting 'speak-as' to ''lower-latin'' ensures that they get read out as their corresponding latin letters, as intended.
</div>
<!-- ====================================================================== -->
<h2 id='symbols-function'>
Defining Anonymous Counter Styles: the ''symbols()'' function</h2>
The ''symbols()'' function allows a <i>counter style</i> to be defined inline in a property value,
for when a style is used only once in a stylesheet and defining a full ''@counter-style'' rule would be overkill.
It does not provide the full feature-set of the ''@counter-style'' rule,
but provides a sufficient subset to still be useful.
The syntax of the ''symbols()'' rule is:
<pre><dfn id='type-symbols-function'>&lt;symbols-function></dfn> = symbols( &lt;symbols-type>? [ &lt;string> | &lt;image> 4EAA ]+ )</pre>
Where &lt;symbols-type> is one of the following keywords:
''cyclic'', ''numeric'', ''alphabetic'', ''symbolic'', or ''fixed''.
The ''symbols()'' function defines an anonymous counter style
with no name,
a 'prefix' and 'suffix' of ''""'' (the empty string),
a 'range' of ''auto'',
a 'fallback' of ''decimal'',
and a 'negative' of "\2D" ("-" hyphen-minus).
The counter style's algorithm is constructed
by consulting the previous chapter using the provided system&nbsp;&mdash;
or ''symbolic'' if the system was omitted&nbsp;&mdash;
and the provided <<string>>s and <<image>>s as the value of the 'symbols' property.
If the system is ''fixed'', the <i>first symbol value</i> is ''1''.
<div class='example'>
This code:
<pre>ol { list-style: symbols("*" "\2020" "\2021" "\A7"); }</pre>
will produce lists that look like:
<pre>
* One
† Two
‡ Three
§ Four
** Five
†† Six
View remainder of file in raw view