[css-lists] Rename marker-side values and clean up prose.

Author: tabatkins

css-lists-3/Overview.bs

@@ -571,40 +571,47 @@ Marker Positioning</h2>
 <h3 id='marker-side'>
 The 'marker-side' property</h3>
 
-	By default, elements or ''::marker'' pseudo-elements with ''position:marker''
-	position themselves according to their list item's directionality.
-	However, if the list item is grouped with several other list items which may have different directionality
-	(for example, multiple &lt;li>s with different "dir" attributes in an &lt;ol> in HTML),
-	it is sometimes more useful to have all the markers line up on one side,
-	so the author can specify a single "gutter" on that side
-	and be assured that all the markers will lie in that gutter and be visible.
-	The 'marker-side' property defined in this section allows an author to control this,
-	switching list items to positioning their markers based off the list container's directionality instead.
-
 	<pre class='propdef'>
 	Name: marker-side
-	Value: list-item | list-container
-	Initial: list-item
+	Value: match-self | match-parent
+	Initial: match-self
 	Applies to: <a>list items</a>
 	Inherited: yes
 	Percentages: n/a
 	Computed value: specified keyword
 	Animation type: discrete
 	</pre>
 
+	The 'marker-side' property specifies
+	whether the ''::marker'' is positioned
+	based on the directionality of the list item itself (i.e. its [=originating element=])
+	or the directionality of the list container (i.e. the [=originating element=]’s parent).
+	In the first case, the position of the marker can vary across items in the same list,
+	based on the directionality assigned to each list item individually;
+	in the second case they will all align on the same side,
+	as determined by the directionality assigned to the list as a whole.
+
 	<dl dfn-type=value dfn-for=marker-side>
-		<dt><dfn>list-item</dfn>
+		<dt><dfn>match-self</dfn>
 		<dd>
-			Any <a>associated markers</a> base their positioning off of the directionality of the list item.
+			The ''::marker'' pseudo-element is positioned
+			using the directionality of the ''::marker''’s [=originating element=].
 
-		<dt><dfn>list-container</dfn>
+		<dt><dfn>match-parent</dfn>
 		<dd>
-			The <a>associated markers</a> instead base their positioning off of the directionality of the list item's parent element.
-			The normative meaning of this is specified in the section defining <a href="#position-marker">position:marker</a>.
+			The ''::marker'' pseudo-element is positioned
+			using the directionality of the ''::marker''’s [=originating element’s=] parent element.
 	</dl>
 
 	<div class='example'>
-		Here is an example of the effect that 'marker-side' can have on a list.
+		By default, elements or ''::marker'' pseudo-elements
+		position themselves according to their list item's directionality.
+		However, if the list item is grouped with several other list items which may have different directionality
+		(for example, multiple &lt;li>s with different "dir" attributes in an &lt;ol> in HTML),
+		it is sometimes more useful to have all the markers line up on one side,
+		so the author can specify a single "gutter" on that side
+		and be assured that all the markers will lie in that gutter and be visible.
+
 		Both of the following example renderings are generated from the following HTML,
 		with the only difference being the value of 'marker-side' on the list:
 
@@ -620,8 +627,8 @@ The 'marker-side' property</h3>
 		<table class=data style="width: 35em;">
 			<thead>
 				<tr>
-					<th>list-item
-					<th>list-container
+					<th>''match-self''
+					<th>''match-parent''
 			<tbody>
 				<tr>
 					<td style="border-right: thin solid">
@@ -1307,7 +1314,6 @@ Appendix A: Sample Style Sheet For HTML</h2>
 			display: inline;
 			text-align: end;
 			unicode-bidi: isolate;
-			/* 'position' computes to "static" or "marker" depending on list-style-position */
 		}
 	</pre>