[css-lists-3] Rephrasing 'implicit list-item counter' 2nd pass. #4168

Author: fantasai

css-lists-3/Overview.bs

@@ -1066,34 +1066,49 @@ The Implicit ''list-item'' Counter</h3>
 	In addition to any explicitly defined [=counters=]
 	that authors write in their styles,
 	[=list items=] automatically increment
-	a special <dfn value for="counter-increment, counter-set, counter-reset, counter(), counters()">list-item</dfn> <a>counter</a>.
-
-	By default, the ''list-item'' counter
-	must be incremented by 1 on every [=list item=],
-	exactly as if the [=list item=] had ''list-item 1'' appended to their 'counter-increment' value
-	(including side-effects such as possibly [=instantiating=] a new [=counter=], etc).
-	This happens at the same time as when [=counters=] are normally incremented,
-	and does not affect the [=specified value|specified=] or [=computed value=] of 'counter-increment'.
-
-	This automatic increment <strong>does not</strong> happen
-	if the [=list item’s=] 'counter-increment'
-	explicitly mentions the ''list-item'' counter:
-	''li { counter-increment: list-item 2; }''
-	will increment ''list-item'' by 2,
-	not by 3 as would happen if you additionally appended ''list-item 1'' to that.
-
-	Host languages can additionally define more complex behavior
-	based on their own semantics.
-	For example, HTML lists can have a <{ol/reversed}> attribute,
-	which causes the ''list-item'' counter to count <em>down</em> instead on the list items belonging to that element.
-
-	Note: Per [[#text-markers]],
-	the ''list-item'' counter
-	is used to generate the [=marker string=] for [=list items=];
-	in other words,
-	it's the counter used when you set 'list-style-type'
-	to something that can show a counter's value,
-	like ''decimal''.
+	a special <dfn value for="counter-increment, counter-set, counter-reset, counter(), counters()">list-item</dfn> <a>counter</a>,
+	which is used when generating the default [=marker string=] on [=list items=]
+	(see 'list-style-type').
+
+	Specifically,
+	unless the 'counter-increment' property explicitly specifies
+	a different increment for the ''list-item'' counter,
+	it must be incremented by 1 on every [=list item=],
+	at the same time that <a>counters</a> are normally incremented
+	(exactly as if the [=list item=] had ''list-item 1'' appended to their 'counter-increment' value,
+	including side-effects such as possibly [=instantiating=] a new [=counter=], etc).
+	This does not affect the [=specified value|specified=] or [=computed values=]
+	of 'counter-increment'.
+
+	<div class="example">
+		Because each [=list item=] automatically increments
+		the ''counter-increment/list-item'' counter by 1,
+		consecutive [=list items=] with a numeric 'list-style-type'
+		will be consecutively numbered by default--
+		even if the author sets 'counter-increment' to another value
+		such as ''counter-increment: itemnumber'' or even ''counter-increment/none''.
+		This protects the automatic ''counter-increment/list-item'' counter
+		from inadvertently being overridden
+		by declarations intended to address other counters.
+
+		However, since the automatic ''counter-increment/list-item'' increment
+		<em>does not</em> happen
+		if the [=list item’s=] 'counter-increment'
+		explicitly mentions the ''list-item'' counter,
+		''li { counter-increment: list-item 2; }''
+		will increment ''list-item'' by 2 as specified,
+		not by 3 as would happen
+		if ''list-item 1'' were unconditionally appended.
+
+		This also allows to turn off the automatic ''list-item'' counter increment,
+		by overriding it explicitly, e.g. ''counter-increment: list-item 0;''.
+	</div>
+
+	In all other respects, the ''counter-increment/list-item'' [=counter=]
+	behaves like any other [=counter=]
+	and can be used and manipulated by authors
+	to adjust [=list item=] styling
+	or for other purposes.
 
 	<div class="example">
 
@@ -1113,11 +1128,13 @@ The Implicit ''list-item'' Counter</h3>
 		</pre>
 	</div>
 
-	Note: This means that ''counter-increment: none''
-	still lets the ''list-item'' counter increment on [=list items=].
-	If one wants to explicitly turn off the ''list-item'' counter as well
-	(perhaps because they are doing something more complicated with it themselves),
-	one must write ''counter-increment: list-item 0;''.
+	UAs and host languages should ensure
+	that the ''counter-increment/list-item'' counter values
+	by default
+	reflect the underlying numeric value dictated by host language semantics
+	when setting up list item styling
+	in their UA style sheet and presentational hint style mappings.
+	See, e.g. [[#ua-stylesheet]].
 
 	<!--
 	See old <a href="https://github.com/w3c/csswg-drafts/issues/2464#issuecomment-375492907">WG discussions</a>
@@ -1367,6 +1384,8 @@ Outputting Counters: the ''counter()'' and ''counters()'' functions</h3>
 <h2 id='ua-stylesheet'>
 Appendix A: Sample Style Sheet For HTML</h2>
 
+	Issue: Need to check this section for errors.
+
 	<em>This section is informative, not normative.
 	HTML itself defines the actual default properties that apply to HTML lists.</em>