editorial

--HG--
extra : rebase_source : 741b0249f82f301637a5a0688475c59459fd8e64

Author: tabatkins

css3-flexbox/Overview.html

@@ -231,17 +231,17 @@ <h2 class="no-num no-toc" id=table>Table of contents</h2>
 
    <li><a href="#alignment"><span class=secno>8. </span> Alignment</a>
     <ul class=toc>
-     <li><a href="#flex-pack"><span class=secno>8.1. </span> Axis Alignment:
+     <li><a href="#auto-margins"><span class=secno>8.1. </span> Aligning with
+      &lsquo;<code class=css>auto</code>&rsquo; margins</a>
+
+     <li><a href="#flex-pack"><span class=secno>8.2. </span> Axis Alignment:
       the &lsquo;<code class=property>flex-pack</code>&rsquo; property</a>
 
-     <li><a href="#flex-align"><span class=secno>8.2. </span> Cross-axis
+     <li><a href="#flex-align"><span class=secno>8.3. </span> Cross-axis
       Alignment: the &lsquo;<code class=property>flex-align</code>&rsquo; and
       &lsquo;<code class=property>flex-item-align</code>&rsquo;
       properties</a>
 
-     <li><a href="#auto-margins"><span class=secno>8.3. </span> Resolving
-      &lsquo;<code class=css>auto</code>&rsquo; margins</a>
-
      <li><a href="#flex-line-pack"><span class=secno>8.4. </span>
       &lsquo;<code class=property>flex-line-pack</code>&rsquo; property</a>
     </ul>
@@ -1392,8 +1392,8 @@ <h2 id=flexibility><span class=secno>7. </span> Flexibility: the &lsquo;<a
   <h2 id=alignment><span class=secno>8. </span> Alignment</h2>
 
   <p> After a flexbox's contents have finished their flexing and the
-   dimensions of margin boxes of all flexbox items are finalized, they can be
-   aligned along the <a href="#main-axis"><i>main axis</i></a> with &lsquo;<a
+   dimensions of all flexbox items are finalized, they can be aligned along
+   the <a href="#main-axis"><i>main axis</i></a> with &lsquo;<a
    href="#flex-pack0"><code class=property>flex-pack</code></a>&rsquo; and
    the <a href="#cross-axis"><i>cross axis</i></a> with &lsquo;<a
    href="#flex-align0"><code class=property>flex-align</code></a>&rsquo; and
@@ -1402,7 +1402,62 @@ <h2 id=alignment><span class=secno>8. </span> Alignment</h2>
    many common types of alignment trivial, including some things that were
    very difficult in CSS 2.1, like horizontal and vertical centering.
 
-  <h3 id=flex-pack><span class=secno>8.1. </span> Axis Alignment: the
+  <h3 id=auto-margins><span class=secno>8.1. </span> Aligning with
+   &lsquo;<code class=css>auto</code>&rsquo; margins</h3>
+
+  <p> Margins on flexbox items that are &lsquo;<code
+   class=css>auto</code>&rsquo; have an effect very similar to auto margins
+   in normal flow:
+
+  <ul>
+   <li> During calculations of preferred sizes and flexible lengths, auto
+    margins are treated as &lsquo;<code class=css>0</code>&rsquo;.
+
+   <li> Prior to alignment via &lsquo;<a href="#flex-pack0"><code
+    class=property>flex-pack</code></a>&rsquo; and &lsquo;<a
+    href="#flex-item-align"><code
+    class=property>flex-item-align</code></a>&rsquo;, any positive free space
+    is distributed to auto margins in that dimension.
+
+   <li> Margin-based alignment has no effect on overflowing elements.
+  </ul>
+
+  <p class=note> Note that, if free space is distributed to auto margins, the
+   alignment properties will have no effect in that dimension.
+
+  <div class=example>
+   <p>Auto margins can be used for simple alignment or for fine control.
+
+   <p>Note that auto margins work consistently in both dimensions, so a
+    simple markup like this
+
+   <pre>
+div { 	display:flexbox;
+	width:4em; height:4em; background:silver;
+}
+p { margin:auto; }
+&lt;div&gt;&lt;p&gt;OK&lt;/p&gt;&lt;/div&gt;</pre>
+
+   <p>will center the single child: <img alt="image of square OK button"
+    height=82 src="images/OK.png" width=82>
+
+   <p>And this
+
+   <pre>
+div {	display:flexbox;
+	width:calc(100% - 4em); height:calc(100% - 4em);
+	border: 1em solid blue; border-radius:50%;
+	margin:auto;
+}
+div#demo { width:9em; height:9em; }
+
+&lt;div id="demo">&lt;div>&lt;div>&lt;/div>&lt;/div>&lt;/div></pre>
+
+   <p> will produce nested centered boxes: <img alt="concentric blue circles"
+    height=191 src="images/target.png" width=210>
+  </div>
+
+  <h3 id=flex-pack><span class=secno>8.2. </span> Axis Alignment: the
    &lsquo;<a href="#flex-pack0"><code
    class=property>flex-pack</code></a>&rsquo; property</h3>
 
@@ -1461,8 +1516,8 @@ <h3 id=flex-pack><span class=secno>8.1. </span> Axis Alignment: the
    This is done <em title="">after</em> any flexible lengths and any auto
    margins have been resolved. Typically it helps distribute extra free space
    leftover when either all the <a href="#flexbox-item"><i>flexbox
-   items</i></a> on a line are inflexible, or are flexible but have reach
-   their maximum size, but it also exerts some control over the alignment of
+   items</i></a> on a line are inflexible, or are flexible but have reached
+   their maximum size. It also exerts some control over the alignment of
    items when they overflow the line.
 
   <dl>
@@ -1540,7 +1595,7 @@ <h3 id=flex-pack><span class=secno>8.1. </span> Axis Alignment: the
     keywords and their effects on a flexbox with three colored items.
   </div>
 
-  <h3 id=flex-align><span class=secno>8.2. </span> Cross-axis Alignment: the
+  <h3 id=flex-align><span class=secno>8.3. </span> Cross-axis Alignment: the
    &lsquo;<a href="#flex-align0"><code
    class=property>flex-align</code></a>&rsquo; and &lsquo;<a
    href="#flex-item-align"><code
@@ -1656,11 +1711,11 @@ <h3 id=flex-align><span class=secno>8.2. </span> Cross-axis Alignment: the
    href="#flex-item-align"><code
    class=property>flex-item-align</code></a>&rsquo; allows this default
    alignment to be overridden for individual <a
-   href="#flexbox-item"><i>flexbox items</i></a> (for anonymous flexbox
+   href="#flexbox-item"><i>flexbox items</i></a>. (For anonymous flexbox
    items, &lsquo;<a href="#flex-item-align"><code
    class=property>flex-item-align</code></a>&rsquo; always matches the value
    of &lsquo;<a href="#flex-align0"><code
-   class=property>flex-align</code></a>&rsquo; on their associated flexbox).
+   class=property>flex-align</code></a>&rsquo; on their associated flexbox.)
 
   <p> A value of <dfn id=flex-item-align-auto>&lsquo;<code
    class=css>auto</code>&rsquo;</dfn> for &lsquo;<a
@@ -1698,15 +1753,14 @@ <h3 id=flex-align><span class=secno>8.2. </span> Cross-axis Alignment: the
     class=css>baseline</code>&rsquo;</dfn>
 
    <dd>
-    <p> If the <a href="#flexbox-item"><i>flexbox item's</i></a> inline-axis
-     is the same as the <i>cross-axis</i>, this value is identical to
-     &lsquo;<code class=css>start</code>&rsquo;.
-
-    <p> Otherwise, all <a href="#flexbox-item"><i>flexbox items</i></a> on
-     the line with an alignment of &lsquo;<code
-     class=css>baseline</code>&rsquo; that don't run afoul of the previous
-     paragraph are aligned such that their baselines align, and the item with
-     the largest distance between its baseline and its <a
+    <p> If the <a href="#flexbox-item"><i>flexbox item's</i></a> inline axis
+     is the same as the <a href="#cross-axis"><i>cross axis</i></a>, this
+     value is identical to &lsquo;<code class=css>start</code>&rsquo;.
+
+    <p> Otherwise, it participates in baseline alignment: all participating
+     <a href="#flexbox-item"><i>flexbox items</i></a> on the line are aligned
+     such that their baselines align, and the item with the largest distance
+     between its baseline and its <a
      href="#cross-start"><i>cross-start</i></a> margin edge is placed flush
      against the <a href="#cross-start"><i>cross-start</i></a> edge of the
      line.
@@ -1765,57 +1819,6 @@ <h3 id=flex-align><span class=secno>8.2. </span> Cross-axis Alignment: the
    </div>
   </div>
 
-  <h3 id=auto-margins><span class=secno>8.3. </span> Resolving &lsquo;<code
-   class=css>auto</code>&rsquo; margins</h3>
-
-  <p>Margins on flexbox items can be set to &lsquo;<code
-   class=css>auto</code>&rsquo;, with effect very similar to auto margins in
-   normal flow.
-
-  <ul>
-   <li>Through calculations of preferred sizes and flexible lengths, auto
-    margins are considered to be zero.
-
-   <li>Immediately <em>before</em> pack and align steps, if there are any
-    auto margins on items in the direction of alignment and there is positive
-    free space, the free space is distributed equally to the auto margins.
-
-   <li>If free space was distributed to auto margins, the following pack or
-    align step has no effect.
-  </ul>
-
-  <div class=example>
-   <p>Auto margins can be used for simple alignment or for fine control.
-
-   <p>Note that auto margins work consistently in both dimensions, so a
-    simple markup like this
-
-   <pre>
-div { 	display:flexbox;
-	width:4em; height:4em; background:silver;
-}
-p { margin:auto; }
-&lt;div&gt;&lt;p&gt;OK&lt;/p&gt;&lt;/div&gt;</pre>
-
-   <p>will center the single child: <img alt="image of square OK button"
-    height=82 src="images/OK.png" width=82>
-
-   <p>And this
-
-   <pre>
-div {	display:flexbox;
-	width:calc(100% - 4em); height:calc(100% - 4em);
-	border: 1em solid blue; border-radius:50%;
-	margin:auto;
-}
-div#demo { width:9em; height:9em; }
-
-&lt;div id="demo">&lt;div>&lt;div>&lt;/div>&lt;/div>&lt;/div></pre>
-
-   <p> will produce nested centered boxes: <img alt="concentric blue circles"
-    height=191 src="images/target.png" width=210>
-  </div>
-
   <h3 id=flex-line-pack><span class=secno>8.4. </span> &lsquo;<a
    href="#flex-line-pack0"><code
    class=property>flex-line-pack</code></a>&rsquo; property</h3>
@@ -2885,22 +2888,22 @@ <h2 class=no-num id=index>Index</h2>
     title="authoring tool"><strong>12.2.</strong></a>
 
    <li>&lsquo;<code class=css>auto</code>&rsquo;, <a
-    href="#flex-item-align-auto" title="''auto''"><strong>8.2.</strong></a>
+    href="#flex-item-align-auto" title="''auto''"><strong>8.3.</strong></a>
 
    <li>&lsquo;<code class=css>baseline</code>&rsquo;, <a
     href="#flex-align-baseline"
-    title="''baseline''"><strong>8.2.</strong></a>
+    title="''baseline''"><strong>8.3.</strong></a>
 
    <li>break inside a flexbox item is considered, <a
     href="#break-inside-a-flexbox-item-is-considere"
     title="break inside a flexbox item is considered"><strong>10.</strong></a>
 
 
    <li>&lsquo;<code class=css>center</code>&rsquo;, <a
-    href="#flex-align-center" title="''center''"><strong>8.2.</strong></a>,
+    href="#flex-align-center" title="''center''"><strong>8.3.</strong></a>,
     <a href="#flex-line-pack-center"
     title="''center''"><strong>8.4.</strong></a>, <a href="#flex-pack-center"
-    title="''center''"><strong>8.1.</strong></a>
+    title="''center''"><strong>8.2.</strong></a>
 
    <li>&lsquo;<code class=css>column</code>&rsquo;, <a
     href="#flex-flow-column" title="''column''"><strong>6.1.</strong></a>
@@ -2930,17 +2933,17 @@ <h2 class=no-num id=index>Index</h2>
     href="#flex-line-pack-distribute"
     title="''distribute''"><strong>8.4.</strong></a>, <a
     href="#flex-pack-distribute"
-    title="''distribute''"><strong>8.1.</strong></a>
+    title="''distribute''"><strong>8.2.</strong></a>
 
    <li>&lsquo;<code class=css>end</code>&rsquo;, <a href="#flex-align-end"
-    title="''end''"><strong>8.2.</strong></a>, <a href="#flex-line-pack-end"
+    title="''end''"><strong>8.3.</strong></a>, <a href="#flex-line-pack-end"
     title="''end''"><strong>8.4.</strong></a>, <a href="#flex-pack-end"
-    title="''end''"><strong>8.1.</strong></a>
+    title="''end''"><strong>8.2.</strong></a>
 
    <li>flex, <a href="#flex" title=flex><strong>7.</strong></a>
 
    <li>flex-align, <a href="#flex-align0"
-    title=flex-align><strong>8.2.</strong></a>
+    title=flex-align><strong>8.3.</strong></a>
 
    <li>flexbox, <a href="#display-flexbox"
     title=flexbox><strong>3.</strong></a>, <a href="#flexbox"
@@ -2974,7 +2977,7 @@ <h2 class=no-num id=index>Index</h2>
     title="flexible length's"><strong>7.</strong></a>
 
    <li>flex-item-align, <a href="#flex-item-align"
-    title=flex-item-align><strong>8.2.</strong></a>
+    title=flex-item-align><strong>8.3.</strong></a>
 
    <li>flex-line-pack, <a href="#flex-line-pack0"
     title=flex-line-pack><strong>8.4.</strong></a>
@@ -2983,7 +2986,7 @@ <h2 class=no-num id=index>Index</h2>
     title=flex-order><strong>6.4.</strong></a>
 
    <li>flex-pack, <a href="#flex-pack0"
-    title=flex-pack><strong>8.1.</strong></a>
+    title=flex-pack><strong>8.2.</strong></a>
 
    <li>flex-wrap, <a href="#flex-wrap0"
     title=flex-wrap><strong>6.2.</strong></a>
@@ -3001,7 +3004,7 @@ <h2 class=no-num id=index>Index</h2>
    <li>&lsquo;<code class=css>justify</code>&rsquo;, <a
     href="#flex-line-pack-justify"
     title="''justify''"><strong>8.4.</strong></a>, <a
-    href="#flex-pack-justify" title="''justify''"><strong>8.1.</strong></a>
+    href="#flex-pack-justify" title="''justify''"><strong>8.2.</strong></a>
 
    <li>main axis, <a href="#main-axis"
     title="main axis"><strong>2.</strong></a>
@@ -3046,12 +3049,12 @@ <h2 class=no-num id=index>Index</h2>
     title=single-line><strong>5.</strong></a>
 
    <li>&lsquo;<code class=css>start</code>&rsquo;, <a
-    href="#flex-align-start" title="''start''"><strong>8.2.</strong></a>, <a
+    href="#flex-align-start" title="''start''"><strong>8.3.</strong></a>, <a
     href="#flex-line-pack-start" title="''start''"><strong>8.4.</strong></a>,
-    <a href="#flex-pack-start" title="''start''"><strong>8.1.</strong></a>
+    <a href="#flex-pack-start" title="''start''"><strong>8.2.</strong></a>
 
    <li>&lsquo;<code class=css>stretch</code>&rsquo;, <a
-    href="#flex-align-stretch" title="''stretch''"><strong>8.2.</strong></a>,
+    href="#flex-align-stretch" title="''stretch''"><strong>8.3.</strong></a>,
     <a href="#flex-line-pack-stretch"
     title="''stretch''"><strong>8.4.</strong></a>