Rewrite the position:marker section.

Author: tabatkins

css3-lists/Overview.html

@@ -1196,26 +1196,18 @@ <h3 id=content-property><span class=secno>6.1. </span> Generating the value
 
   <h2 id=positioning-markers><span class=secno>7. </span> Positioning Markers</h2>
 
-  <p>This section introduces a new positioning scheme, designed to model the
-   way in which "outside" list markers were traditionally positioned in CSS
-   2.1. Outside list markers now have their positioning defined in terms of
-   this new value.
+  <p> This section introduces a new positioning scheme, designed to model the
+   way in which ‘<code class=css>list-style-position:outside</code>’ list
+   markers were traditionally positioned in CSS 2.1. Outside list markers now
+   have their positioning defined in terms of this new value.
 
-  <p>The new positioning scheme defined in this section can be used on all
+  <p> The new positioning scheme defined in this section can be used on all
    elements, not just ‘<code class=css>::marker</code>’ pseudo-elements.
-   In some situations, such as legal proceedings or official minutes, the
-   precise form that the list marker takes is a vital part of the content.
-   It's not acceptable for the marker to change (from a custom-defined marker
-   to a default bullet or alpha marker) just because the UA is not rendering
-   CSS, or a server error is temporarily preventing the CSS file from being
-   loaded, as the precise form of the marker is used to officially refer to
-   that segment. The only way to guarantee that the marker will be rendered
-   correctly, regardless of whether CSS is applied, is to specify the marker
-   outside of CSS, directly in the document's markup. However, the page
-   author may still want to style the marker in many of the ways that are
-   available to them when using ordinary CSS-generated markers. To accomodate
-   this, the new positioning scheme can be used to position the
-   marker-in-content as if it were an ordinary CSS-generated marker.
+   For example, this can be used to position explicit elements serving as
+   markers in a legal document, so that the list item has a marker whose
+   value is guaranteed to be correct regardless of whether the CSS is applied
+   (often a requirement in legal documents), but which is positioned like a
+   native CSS marker.
 
   <h3 id=position-marker><span class=secno>7.1. </span> The ‘<code
    class=css>marker</code>’ value for ‘<code
@@ -1231,7 +1223,7 @@ <h3 id=position-marker><span class=secno>7.1. </span> The ‘<code
     <tr>
      <th>New Value:
 
-     <td>‘<code class=css>marker</code>’
+     <td>marker
 
     <tr>
      <th>Initial:
@@ -1264,18 +1256,19 @@ <h3 id=position-marker><span class=secno>7.1. </span> The ‘<code
      <td>see prose, otherwise same as CSS2.1
   </table>
 
-  <p>The ‘<code class=css>marker</code>’ value for ‘<code
+  <p> The ‘<code class=css>marker</code>’ value for ‘<code
    class=property>position</code>’ depends on the element it is set on
-   having a list item ancestor. If the specified value of ‘<code
-   class=property>position</code>’ is ‘<code class=css>marker</code>’
-   and the element does not have a list item ancestor, ‘<code
+   having a <a href="#list-item"><i>list item</i></a> ancestor. If the
+   specified value of ‘<code class=property>position</code>’ is ‘<code
+   class=css>marker</code>’ and the element does not have a <a
+   href="#list-item"><i>list item</i></a> ancestor, ‘<code
    class=property>position</code>’ must compute to ‘<code
-   class=property>relative</code>’ on the element. An element with <code
-   class=css>position:marker</code> counts as <a
+   class=property>relative</code>’ on the element. An element with ‘<code
+   class=css>position:marker</code>’ counts as <a
    href="http://www.w3.org/TR/CSS21/visuren.html#absolutely-positioned">absolutely
    positioned</a>.
 
-  <p>To calculate the marker's position, we must first define a few terms:
+  <p> To calculate the marker's position, we must first define a few terms:
 
   <dl>
    <dt><dfn id=ancestor-list-item
@@ -1288,118 +1281,137 @@ <h3 id=position-marker><span class=secno>7.1. </span> The ‘<code
     reference element</dfn>
 
    <dd>
-    <p>If the <a href="#ancestor-list-item"><i>ancestor list item</i></a> has
-     ‘<code class=css>marker-attachment:list-item</code>’, the <a
+    <p> If the <a href="#ancestor-list-item"><i>ancestor list item</i></a>
+     has ‘<code class=css>marker-attachment:list-item</code>’, the <a
      href="#marker-positioning-reference-element"><i>marker positioning
      reference element</i></a> is the <a
      href="#ancestor-list-item"><i>ancestor list item</i></a>.
 
-    <p>Otherwise, if the <a href="#ancestor-list-item"><i>ancestor list
+    <p> Otherwise, if the <a href="#ancestor-list-item"><i>ancestor list
      item</i></a> has ‘<code
      class=css>marker-attachment:list-container</code>’ and has a parent
      element, the <a href="#marker-positioning-reference-element"><i>marker
      positioning reference element</i></a> is the <a
      href="#ancestor-list-item"><i>ancestor list item's</i></a> parent.
 
-    <p>Otherwise, the <a
+    <p> Otherwise, the <a
      href="#marker-positioning-reference-element"><i>marker positioning
      reference element</i></a> is the <a
      href="#ancestor-list-item"><i>ancestor list item</i></a>.
 
    <dt><dfn id=list-item-positioning-edge>list item positioning edge</dfn>
 
-   <dd>The border edge of the <a href="#ancestor-list-item"><i>ancestor list
-    item</i></a> corresponding to the "start" or "before" edge of the <a
+   <dd> The border edge of the <a href="#ancestor-list-item"><i>ancestor list
+    item</i></a> corresponding to the "start" or "head" edge of the <a
     href="#marker-positioning-reference-element"><i>marker positioning
     reference element</i></a>, whichever is in the <a
     href="#ancestor-list-item"><i>ancestor list item's</i></a> inline axis.
 
    <dt><dfn id=marker-positioning-edge>marker positioning edge</dfn>
 
-   <dd>The opposing edge relative to the <a
-    href="#list-item-positioning-edge"><i>list item positioning edge</i></a>
-    on the marker's margin box. For example, if the <i>list item positioning
-    edge ended up being the left border edge of the <a
-    href="#ancestor-list-item"><i>ancestor list item</i></a>, the <a
-    href="#marker-positioning-edge"><i>marker positioning edge</i></a> would
-    be the right margin edge of the marker. </i>
+   <dd> The outer edge of the marker that's on the opposite side from the <a
+    href="#list-item-positioning-edge"><i>list item positioning edge</i></a>.
+    For example, if the <i>list item positioning edge ended up being the left
+    border edge of the <a href="#ancestor-list-item"><i>ancestor list
+    item</i></a>, the <a href="#marker-positioning-edge"><i>marker
+    positioning edge</i></a> would be the right margin edge of the marker.
+    </i>
   </dl>
 
-  <p>The marker's position in the <a href="#ancestor-list-item"><i>ancestor
+  <p> The marker's position in the <a href="#ancestor-list-item"><i>ancestor
    list item's</i></a> block axis is calculated according to the <a
    href="http://www.w3.org/TR/CSS21/visuren.html#normal-flow">normal
-   flow</a>. <span class=note>In the Positioned Layout Module this will be
-   defined more precisely in terms of placeholders.</span>
+   flow</a>.
 
-  <p>The marker's position in the <a href="#ancestor-list-item"><i>ancestor
+  <p> The marker's position in the <a href="#ancestor-list-item"><i>ancestor
    list item's</i></a> inline axis must be set such that the <a
    href="#marker-positioning-edge"><i>marker positioning edge</i></a> is
    flush with the <a href="#list-item-positioning-edge"><i>list item
    positioning edge</i></a>.
 
-  <p class=note>The purpose of this somewhat convoluted definition is to
-   position the marker flush against its list item, and then when
+  <p class=note> Note: The purpose of this somewhat convoluted definition is
+   to position the marker flush against its list item, and then when
    "marker-attachment:list-container", keep all the markers for a given list
    on the same side of their list items even in mixed-direction text, so that
-   authors can specify padding on only one side and still ensure their
-   markers are visible. And on top of all that, do something sane in the face
-   of potentially differing writing-modes on the marker, list item, and
-   container.
+   authors can specify padding on only one side of the list container and
+   still ensure their markers are visible. And on top of all that, do
+   something sane in the face of potentially differing writing-modes on the
+   marker, list item, and container.
 
-  <p>All elements or pseudo-elements with <code
-   class=css>"position:marker"</code> that share a common <a
+  <p> All elements or pseudo-elements with ‘<code
+   class=css>position:marker</code>’ that share a common <a
    href="#ancestor-list-item"><i>ancestor list item</i></a> are known as <dfn
    id=markers-associated-with-that-list-item title=associated-marker>markers
    associated with that list item</dfn>.
 
-  <p>The ‘<code class=property>top</code>’, ‘<code
+  <p> The ‘<code class=property>top</code>’, ‘<code
    class=property>right</code>’, ‘<code class=property>bottom</code>’,
    and ‘<code class=property>left</code>’ properties specify offsets
    relative to the top, right, bottom, and left edges (respectively) of the
    element itself, similar to how relative positioning works.
 
   <div class=example>
-   <p>‘<code class=css>position:marker</code>’ can be used when the
+   <p> ‘<code class=css>position:marker</code>’ can be used when the
     precise list marker is important for the content, not a stylistic choice,
     but the normal <em>appearance</em> of lists is still desired. For
     example, this trimmed snippet of the US Code of Laws may be marked up as
     the following in HTML:
 
-   <pre>
-&lt;style>
-ol { list-style: none; }
-.marker { position: marker; }
-&lt;/style>
-&lt;ol>
-   &lt;li>
-      &lt;span class='marker'>(a)&lt;/span> Definitions.— For purposes of this section—
-      &lt;ol>
-         &lt;li>&lt;span class='marker'>(1)&lt;/span> the term “agency” means agency as...&lt;/li>
-         &lt;li>&lt;span class='marker'>(2)&lt;/span> the term “individual” means a citizen...&lt;/li>
-      &lt;/ol>
-   &lt;/li>
-   &lt;li>
-      &lt;span class='marker'>(b)&lt;/span> Conditions of Disclosure.— No agency shall disclose...
-      &lt;ol>
-         &lt;li>&lt;span class='marker'>(1)&lt;/span> to those officers and employees of the agency which...&lt;/li>
-         &lt;li>&lt;span class='marker'>(2)&lt;/span> required under section 552 of this title;&lt;/li>
-      &lt;/ol>
-   &lt;/li>
-&lt;/ol></pre>
+   <pre><!--
+		-->&lt;style>
+<!--
+		-->ol { list-style: none; }
+<!--
+		-->.marker { position: marker; }
+<!--
+		-->&lt;/style>
+<!--
+		-->&lt;ol>
+<!--
+		-->  &lt;li>
+<!--
+		-->    &lt;span class='marker'>(a)&lt;/span> Definitions.— For purposes of this section—
+<!--
+		-->    &lt;ol>
+<!--
+		-->      &lt;li>&lt;span class='marker'>(1)&lt;/span> the term “agency” means agency as...
+<!--
+		-->      &lt;li>&lt;span class='marker'>(2)&lt;/span> the term “individual” means a citizen...
+<!--
+		-->    &lt;/ol>
+<!--
+		-->  &lt;li>
+<!--
+		-->    &lt;span class='marker'>(b)&lt;/span> Conditions of Disclosure.— No agency shall disclose...
+<!--
+		-->    &lt;ol>
+<!--
+		-->      &lt;li>&lt;span class='marker'>(1)&lt;/span> to those officers and employees of the agency...
+<!--
+		-->      &lt;li>&lt;span class='marker'>(2)&lt;/span> required under section 552 of this title;
+<!--
+		-->    &lt;/ol>
+<!--
+		-->&lt;/ol></pre>
 
-   <p>The preceding document should render something like this:
+   <p> The preceding document should render something like this:
 
-   <pre>
- (a) Definitions.— For purposes of this section—
-     (1) the term “agency” means agency as...
-     (2) the term “individual” means a citizen...
- (b) Conditions of Disclosure.— No agency shall disclose...
-     (1) to those officers and employees of the agency which...
-     (2) required under section 552 of this title;</pre>
-
-   <p>Importantly, it will <strong>always</strong> be presented something
-    like that, with those exact list markers, even if the stylesheet is
-    unavailable, so other documents can refer to those list markers and be
+   <pre><!--
+		-->(a) Definitions.— For purposes of this section—
+<!--
+		-->    (1) the term “agency” means agency as...
+<!--
+		-->    (2) the term “individual” means a citizen...
+<!--
+		-->(b) Conditions of Disclosure.— No agency shall disclose...
+<!--
+		-->    (1) to those officers and employees of the agency...
+<!--
+		-->    (2) required under section 552 of this title;</pre>
+
+   <p> Importantly, even if the stylesheet is unavailable, the list markers
+    will appear the same (though they will be positioned slightly
+    differently), so other documents can refer to those list markers and be
     confident that the reference will always be resolvable.
   </div>