Swap placement of note and normative prose around flex item generation, so that normative prose doesn't get lost after the example. Fix up abspos section to correctly reflect atomic-ness of placeholders.

Author: fantasai

css3-flexbox/Overview.html

@@ -40,11 +40,11 @@
 
    <h1 id=head-box-flexible>CSS Flexible Box Layout Module</h1>
 
-   <h2 class="no-num no-toc" id=w3c-working>Editor's Draft, 18 May 2012</h2>
+   <h2 class="no-num no-toc" id=w3c-working>Editor's Draft, 22 May 2012</h2>
 
    <dl>
     <dt>This version:
-     <!--<dd><a href="http://www.w3.org/TR/2012/ED-css3-flexbox-20120518/">http://www.w3.org/TR/2012/WD-css3-flexbox-20120518/</a>-->
+     <!--<dd><a href="http://www.w3.org/TR/2012/ED-css3-flexbox-20120522/">http://www.w3.org/TR/2012/WD-css3-flexbox-20120522/</a>-->
 
 
     <dd><a
@@ -204,14 +204,16 @@ <h2 class="no-num no-toc" id=table>Table of contents</h2>
 
    <li><a href="#flex-items"><span class=secno>4. </span> Flex Items</a>
     <ul class=toc>
-     <li><a href="#abspos-flex-items"><span class=secno>4.1. </span>
-      Absolutely Positioned Flex Container Children</a>
+     <li><a href="#flex-item-margins"><span class=secno>4.1. </span> Flex
+      Item Margins</a>
 
-     <li><a href="#visibility-collapse"><span class=secno>4.2. </span>
-      Effects of ‘<code class=css>visibility:collapse</code>’ on Flex
-      Items</a>
+     <li><a href="#abspos-flex-items"><span class=secno>4.2. </span>
+      Out-of-flow Items</a>
 
-     <li><a href="#min-size-auto"><span class=secno>4.3. </span> Implied
+     <li><a href="#visibility-collapse"><span class=secno>4.3. </span>
+      Collapsed Items</a>
+
+     <li><a href="#min-size-auto"><span class=secno>4.4. </span> Implied
       Minimum Size of Flex Items</a>
     </ul>
 
@@ -626,9 +628,13 @@ <h2 id=flex-items><span class=secno>4. </span> Flex Items</h2>
    <em>before</em> a flex container's contents are checked to see if it's
    necessary to generate anonymous flex items.
 
-  <p class=note> Future display types may generate anonymous containers (e.g.
-   ruby) or otherwise mangle the box tree (e.g. run-ins). It is intended that
-   flex item determination run after these operations.
+  <p> The computed value for ‘<code class=property>display</code>’ for
+   elements that are <a href="#flex-item"><i>flex items</i></a> must be
+   determined by applying the table in <a
+   href="http://www.w3.org/TR/CSS2/visuren.html#dis-pos-flo">CSS 2.1 Chapter
+   9.7</a>. <span class=note>This is expected to be superseded by a future
+   specification that defines a new ‘<code class=property>display</code>’
+   value for flex items.</span>
 
   <div class=example>
    <p>Examples of flex items:
@@ -686,30 +692,28 @@ <h2 id=flex-items><span class=secno>4. </span> Flex Items</h2>
     positioned children have special treatment.
   </div>
 
-  <p> The computed value for ‘<code class=property>display</code>’ for
-   elements that are <a href="#flex-item"><i>flex items</i></a> must be
-   determined by applying the table in <a
-   href="http://www.w3.org/TR/CSS2/visuren.html#dis-pos-flo">CSS 2.1 Chapter
-   9.7</a>. <span class=note>This is expected to be superseded by a future
-   specification that defines a new ‘<code class=property>display</code>’
-   value for flex items.</span>
+  <p class=note> Future display types may generate anonymous containers (e.g.
+   ruby) or otherwise mangle the box tree (e.g. run-ins). It is intended that
+   flex item determination run after these operations.
+
+  <h3 id=flex-item-margins><span class=secno>4.1. </span> Flex Item Margins</h3>
 
   <p> The margins of adjacent <a href="#flex-item"><i>flex items</i></a> do
-   not collapse.
+   not collapse. Auto margins absorb extra space in that dimension and can be
+   used for alignment and to push adjacent flex items apart; see <a
+   href="#auto-margins">Aligning with ‘<code class=css>auto</code>’
+   margins</a>.
 
-  <h3 id=abspos-flex-items><span class=secno>4.1. </span> Absolutely
-   Positioned Flex Container Children</h3>
+  <h3 id=abspos-flex-items><span class=secno>4.2. </span> Out-of-flow Items</h3>
 
-  <p> Absolutely positioned children of a flex container are not <a
-   href="#flex-item"><i>flex items</i></a>, but they leave behind
+  <p> Absolutely positioned children of a flex container are not themselves
+   <a href="#flex-item"><i>flex items</i></a>, but they leave behind
    "placeholders" in their normal position in the box tree. These
-   placeholders are anonymous atomic inline boxes with a width and height of
-   ‘<code class=css>0</code>’, and they interact normally with the flex
-   layout algorithm. In particular, they'll trigger the creation an anonymous
-   flex item wrapper boxes, or join neighboring inline elements in
-   <em>their</em> anonymous flex item wrapper boxes.
+   placeholders are atomic inline boxes with a width, height, and flex of
+   ‘<code class=css>0</code>’, becoming zero-sized flex items that
+   otherwise interact normally with the flex layout algorithm.
 
-  <p> The "static position" of an absolutely positioned child of a flex
+  <p> The <i>static position</i> of an absolutely positioned child of a flex
    container (the position when the ‘<code
    class=property>top</code>’/‘<code
    class=property>right</code>’/‘<code
@@ -718,18 +722,14 @@ <h3 id=abspos-flex-items><span class=secno>4.1. </span> Absolutely
    class=css>auto</code></a>’), then, is the final position of its
    corresponding placeholder, after flex layout has been performed.
 
-  <p class=note> Note: In most cases, this means that absolutely positioned
-   items will have no effect on flex layout, even if they force the
-   generation of an anonymous flex item wrapper, because those wrapper items
-   will also collapse to zero size and have no effect. The only exceptions
-   are when the flex container has ‘<code
-   class=css>flex-pack:justify</code>’ or ‘<code
-   class=css>flex-pack:distribute</code>’, in which case the anonymous flex
-   item will cause there to be two packing spaces where there would otherwise
-   be only one, resulting in a double-size space between two "real" items.
+  <p class=note> Note: In most cases, this means that absolutely-positioned
+   items have no effect on flex layout. However, when the flex container has
+   ‘<code class=css>flex-pack:justify</code>’ or ‘<code
+   class=css>flex-pack:distribute</code>’, each placeholder flex item will
+   cause there to be two packing spaces where there would otherwise be only
+   one, possibly resulting in increased space between two "real" items.
 
-  <h3 id=visibility-collapse><span class=secno>4.2. </span> Effects of
-   ‘<code class=css>visibility:collapse</code>’ on Flex Items</h3>
+  <h3 id=visibility-collapse><span class=secno>4.3. </span> Collapsed Items</h3>
 
   <p> Using ‘<code class=css>visibility:collapse</code>’ on a flex item
    produces an effect similar to ‘<code
@@ -766,7 +766,7 @@ <h3 id=visibility-collapse><span class=secno>4.2. </span> Effects of
    algorithm is defined <a href="#layout-algorithm">later in this
    specification</a>.
 
-  <h3 id=min-size-auto><span class=secno>4.3. </span> Implied Minimum Size of
+  <h3 id=min-size-auto><span class=secno>4.4. </span> Implied Minimum Size of
    Flex Items</h3>
 
   <p> To provide a more reasonable default minimum size for flex containers,
@@ -3645,7 +3645,7 @@ <h2 class=no-num id=index>Index</h2>
     title=main-start><strong>2.</strong></a>
 
    <li>min-width/height:auto, <a href="#min-auto"
-    title="min-width/height:auto"><strong>4.3.</strong></a>
+    title="min-width/height:auto"><strong>4.4.</strong></a>
 
    <li>multi-line, <a href="#multi-line"
     title=multi-line><strong>6.</strong></a>

css3-flexbox/Overview.src.html

@@ -314,9 +314,10 @@ <h2 id='flex-items'>
 		For example, a ''table-cell'' child of a block container is fixed up by generating ''table'' and ''table-row'' elements around it.  
 		This fixup must occur <em>before</em> a flex container's contents are checked to see if it's necessary to generate anonymous flex items.
 
-	<p class='note'>
-		Future display types may generate anonymous containers (e.g. ruby) or otherwise mangle the box tree (e.g. run-ins).
-		It is intended that flex item determination run after these operations.
+	<p>
+		The computed value for 'display' for elements that are <i>flex items</i> 
+		must be determined by applying the table in <a href="http://www.w3.org/TR/CSS2/visuren.html#dis-pos-flo">CSS 2.1 Chapter 9.7</a>.
+		<span class='note'>This is expected to be superseded by a future specification that defines a new 'display' value for flex items.</span>
 
 	<div class="example">
 		<p>Examples of flex items:
@@ -375,43 +376,43 @@ <h2 id='flex-items'>
 			because absolutely positioned children have special treatment.
 	</div>
 
-	<p>
-		The computed value for 'display' for elements that are <i>flex items</i> 
-		must be determined by applying the table in <a href="http://www.w3.org/TR/CSS2/visuren.html#dis-pos-flo">CSS 2.1 Chapter 9.7</a>.
-		<span class='note'>This is expected to be superseded by a future specification that defines a new 'display' value for flex items.</span>
+	<p class='note'>
+		Future display types may generate anonymous containers (e.g. ruby) or otherwise mangle the box tree (e.g. run-ins).
+		It is intended that flex item determination run after these operations.
+
+<h3 id=flex-item-margins>
+Flex Item Margins</h3>
 
 	<p>
 		The margins of adjacent <i>flex items</i> do not collapse.
+		Auto margins absorb extra space in that dimension and can be used for alignment
+		and to push adjacent flex items apart;
+		see <a href="#auto-margins">Aligning with ''auto'' margins</a>.
 
 <h3 id='abspos-flex-items'>
-Absolutely Positioned Flex Container Children</h3>
+Out-of-flow Items</h3>
 
 	<p>
-		Absolutely positioned children of a flex container are not <i>flex items</i>, 
-		but they leave behind "placeholders" in their normal position in the box tree.  
-		These placeholders are anonymous atomic inline boxes with a width and height of ''0'', 
-		and they interact normally with the flex layout algorithm.  
-		In particular, 
-		they'll trigger the creation an anonymous flex item wrapper boxes, 
-		or join neighboring inline elements in <em>their</em> anonymous flex item wrapper boxes.
+		Absolutely positioned children of a flex container are not themselves <i>flex items</i>, 
+		but they leave behind "placeholders" in their normal position in the box tree. 
+		These placeholders are atomic inline boxes with a width, height, and flex of ''0'', 
+		becoming zero-sized flex items that otherwise interact normally with the flex layout algorithm.
 
 	<p>
-		The "static position" of an absolutely positioned child of a flex container 
-		(the position when the 'top'/'right'/'bottom'/'left' properties are ''auto''), 
-		then, 
+		The <i>static position</i> of an absolutely positioned child of a flex container 
+		(the position when the 'top'/'right'/'bottom'/'left' properties are ''auto''), then, 
 		is the final position of its corresponding placeholder, after flex layout has been performed.
 
 	<p class='note'>
 		Note: In most cases, 
-		this means that absolutely positioned items will have no effect on flex layout, 
-		even if they force the generation of an anonymous flex item wrapper, 
-		because those wrapper items will also collapse to zero size and have no effect.  
-		The only exceptions are when the flex container has ''flex-pack:justify'' or ''flex-pack:distribute'', 
-		in which case the anonymous flex item will cause there to be two packing spaces where there would otherwise be only one, 
-		resulting in a double-size space between two "real" items.
+		this means that absolutely-positioned items have no effect on flex layout.
+		However, when the flex container has ''flex-pack:justify'' or ''flex-pack:distribute'', 
+		each placeholder flex item will cause there to be two packing spaces
+		where there would otherwise be only one, 
+		possibly resulting in increased space between two "real" items.
 
 <h3 id='visibility-collapse'>
-Effects of ''visibility:collapse'' on Flex Items</h3>
+Collapsed Items</h3>
 
 	<p>
 		Using ''visibility:collapse'' on a flex item