[css-lists] How does the list-item counter affect display?

[domenic]

https://drafts.csswg.org/css-lists-3/#list-item-counter

In the following example, the list is modified to count by twos:

ol.evens { counter-increment: list-item 2; }

A three-item list would be rendered as

2. First Item
4. Second Item
6. Third Item

I can't find a normative requirement to support this rendering. The normative requirements I can find are all about the value of the list-item counter (although I think there are contradictions; see #4167). There is nothing in the spec that says that the list-item counter is to be used in rendering.

Perhaps the example is missing a ol.evens::marker { content: counters(list-item,'.') '.'; }, similar to the following Example 17?

[MatsPalmgren]

Well, we have:
"A list item is any element with its display property set to list-item. List items generate ::marker pseudo-elements"
https://drafts.csswg.org/css-lists-3/#list-item

"list-style-type on the originating element defines a marker string "
https://drafts.csswg.org/css-lists-3/#content-property

"<counter-style>
Specifies the element’s marker string as the value of the list-item counter represented using the specified <counter-style>. "
https://drafts.csswg.org/css-lists-3/#marker-string

So, if the UA sheet contains ol { list-style-type: decimal; } then the rendering you suggest is normative, right? (I don't think it's normative to have that rule, but it's informatively defined in the appendix)

Perhaps the spec should say upfront that all examples assumes an UA sheet similar to the one in the appendix? It'd be rather tedious to list complete markup+style for each example, and it would make them less informative since the reader might not know which rules are necessary for the example to work in a web browser and might start adding lot's of redundant styles. (It looks like most examples assumes existing (UA) style on ol/ul/li elements, fwiw.)

[domenic]

Right, if there were a normative statement that UAs had such a rule, then the OP's example would make sense. The fact that there is no such statement is why I find the example confusing.

I don't think it would be that tedious to list such a rule for the 1 example where it is necessary. (I believe there are only 2 examples in the spec that use the list-item counter, one of which already has such a rule.) I think it would be more informative, since adding such a rule would be necessary in a web browser, not redundant. (Unless the browser introduces UA styles based on no normative spec, I suppose, but I don't think we should be writing spec examples catering to such situations.)

[MatsPalmgren]

I believe there are only 2 examples in the spec that use the list-item counter

Actually, there are many more. Also, there are other UA style assumptions: example 3, 4, 6 and 10 are missing li { display: list-item; }, example 17 and 19 are missing various styles on o/ul/li and example 17 is also missing attribute mappings for start and reversed. Just to mention a few issues I found at first glance...

Making the examples complete in the sense that they work with an empty UA sheet might be good for implementors, but I think it makes the examples less informative for authors since it's less clear which declarations they need to include for the example to work and which are simply copies from the UA sheet. It would be unfortunate if the spec mislead authors to include li { display: list-item; } etc in their sheets.
If we make the examples complete, could we at least make two sections of rules, like so:

li { display: list-item; }  /* in UA sheet */
ol { counter-reset: list-item; list-style-type: decimal; }  /* in UA sheet */

li::marker { content: "(" counter(list-item, lower-roman) ")"; }
... other non-UA sheet rules needed for the example ...

[domenic]

I think we're talking past each other. I'm not talking about making the examples complete with an empty UA stylesheet. I'm talking about making the examples complete with the UA stylesheet. That seems important for authors. I agree it's of dubious value to duplicate the relevant UA stylesheet rules in every example in the spec; we should not need to spell out that li has display: list-item.

But, given that there is no UA stylesheet rule that li's render using the list-item counter, it seems like the two examples in the spec (16 and 17) which relate to the behavior of the list-item counter should probably make that counter render. Otherwise they're just confusing. (Especially since example 17 does include such a rule; we're just discussing whether to make example 16 consistent with that.)

An example such as example 3 works fine with the UA stylesheet rules that exist today, so it doesn't need any additions.

Note: perhaps the confusion is that when I say "UA stylesheet", I mean the one normatively specified to apply to UAs (in the HTML spec), whereas you might be referring to the non-normative example UA stylesheet appendix? I think the one that applies to UAs is more relevant when we're talking about usefulness to authors (and implementers!), than the example appendix one.

[MatsPalmgren]

But, given that there is no UA stylesheet rule that li's render using the list-item counter

It renders because the other CSS properties implies a generated marker that is using the list-item counter value. As I outlined in my first reply: if we assume the UA sheet contains ol { list-style-type: decimal; } then example 16 needs no additional rules since it's the default rendering for list-style-type: decimal. The marker box and its contents is generated by the CSS properties in the sections I indicated. There is no need to have an explicit ::marker rule. (Btw, there seems to be a typo in this example: I'm assuming the counter-increment: list-item 2 was intended for the list items, not the <ol> as the selector suggests.)

This also implies that a ::marker rule can be used to style that implicit marker (again, without specifying a content property), for example (in Firefox):

<style>::marker{color:red}</style><li>Hi

makes the bullet red.

The ::marker rule in example 17 is needed though, because it demonstrates a non-default marker string (it renders the ordinal number of every level in each marker which is not the default rendering for decimal). (Again, there's a typo: the selector ol::marker should be li::marker, and there's a missing </ol> before the last <li>, but with those fixes I get the desired rendering in Firefox.)

I think the one that applies to UAs is more relevant when we're talking about usefulness to authors (and implementers!), than the example appendix one.

Well, the one in the css-lists spec is a lot closer to the actual UA sheet we have in Gecko than the "normative" rules in the HTML spec (which lacks counter-* properties!).

(I implemented HTML list numbering using a built-in list-item counter (with help from @emilio) and the ::marker pseudo in Gecko so I know a little bit about how it's implemented there.)

[domenic]

It renders because the other CSS properties implies a generated marker that is using the list-item counter value. As I outlined in my first reply: if we assume the UA sheet contains ol { list-style-type: decimal; } then example 16 needs no additional rules since it's the default rendering for list-style-type: decimal. The marker box and its contents is generated by the CSS properties in the sections I indicated.

Thank you! That was what I was missing. So there is a normative requirement in the spec, it's just in the list-style-type property section, not in the list-item section.

I know I could have clicked on the 'list-item' definition to see that, but may I suggest adding an explicit note explaining this connection? E.g. in the list-item counter section, something like

NOTE: The 'list-item' counter is automatically used to assemble the contents of the generated marker when certain 'list-style-type' values apply; see section 3.4.

---

Well, the one in the css-lists spec is a lot closer to the actual UA sheet we have in Gecko than the "normative" rules in the HTML spec (which lacks counter-* properties!).

(I implemented HTML list numbering using a built-in list-item counter and the ::marker pseudo in Gecko so I know a little bit about how it's implemented there.)

Right. I'm aware that Gecko implemented a UA stylesheet based on no normative spec. I'd hoped that as @dbaron asked, we'd see an update to the normative UA stylesheet at some point---at least in pull request form---but that hasn't materialized yet. As such I hesitate to take such unspecified, not-even-proposed UA stylesheets into account.

[tabatkins]

@MatsPalmgren So I see that gCS() reflects the list-item counter in ol's counter-reset, and <li value>'s counter-set, but I can't find any element that reflects it in counter-increment. Intentional divergence, or am I doing something wrong?

[MatsPalmgren]

@tabatkins It's intentional. We initially implemented the counter-increment for list items as a computed value but we changed it to used value magic instead per the resolution in #3686. <li value> is a simple attribute mapping that set the counter-set computed value. We discussed changing that to used-value time too, but decided not to since it's more complicated to implement for no real benefit. Ditto for <ol start>.

[tabatkins]

Ah yes, apologies, I remember that resolution. I've done some wording tweaks to make all this clearer.

@domenic, I also added the note you requested.

[fantasai]

@domenic

Right. I'm aware that Gecko implemented a UA stylesheet based on no normative spec.

Fwiw, the CSSWG resolutions on redefining HTML list numbering to integrate with CSS counters predate the HTML spec by quite a few years: https://www.w3.org/TR/2002/WD-css3-lists-20021107/#declaring Gecko's implementation is fulfilling a longstanding intention, and they have been coordinating with the CSSWG to work out missing details on how exactly to make it work.

I'd hoped that as @dbaron asked, we'd see an update to the normative UA stylesheet at some point---at least in pull request form---but that hasn't materialized yet. As such I hesitate to take such unspecified, not-even-proposed UA stylesheets into account.

You don't need to. As @MatsPalmgren points out, list-style-type is normatively defined to use the list-item counter in its markers, so all that needs to be taken into account to make the quoted example work is the definitions in the css-lists-3 spec together with the display: list-item and list-style-type: decimal declaration already in the HTML spec.

That said, yes, the HTML spec should be updated to hook into css-lists-3 for list numbering, as it currently doesn't define the rendering of list numbers for CSS UAs at all. (I'm guessing this is what the red-boxed note at the end of 14.3.8 Lists is about?) Thus, every browser's OL list marker implementation is based on no normative spec. Tab and I haven't made specific suggestions to HTML yet, because we needed to get css-lists-3 into a more solid state: besides needing to rewrite the list styling section, which we did in April, the counters section had enough CSS2.1 sync errors until last week that it wasn't legitimately referenceable. (As of this weekend, I think, it's cleaned up enough that we can republish a referenceable draft and take on edits to HTML as the next task on this topic.)

I know I could have clicked on the 'list-item' definition to see that, but may I suggest adding an explicit note explaining this connection? E.g. in the list-item counter section, something like

We've done one better, and revised the section overall to be a little clearer. :) There's now a cross-reference to the list-style-type behavior up front. You can see the results at https://drafts.csswg.org/css-lists-3/#list-item-counter Let us know if that works for you.

[domenic]

That said, yes, the HTML spec should be updated to hook into css-lists-3 for list numbering, as it currently doesn't define the rendering of list numbers for CSS UAs at all.

Good catch! The sentence that currently reads

When rendering li elements, non-CSS user agents are expected to use the ordinal value of the li element to render the counter in the list item marker.

was meant to read "user agents"; that was missed when we introduced the definition of "ordinal value".

That said, it sounds like perhaps that will be unnecessary soon, with proposals such as whatwg/html#4816, or the work you mentioned you and Tab intend to submit. (Assuming they gain the requisite multi-implementer interest.)

We've done one better, and revised the section overall to be a little clearer. :)

Yep, my OP request is definitely fulfilled; thank you for your work!