Remove the section describing how to resolve flexible lengths, as its superfluous with the layout algorithm. Start replacing it with some examples of using flex().

Author: tabatkins

css3-flexbox/Overview.html

@@ -210,9 +210,6 @@ <h2 class="no-num no-toc" id=table>Table of contents</h2>
     <ul class=toc>
      <li><a href="#flex-notation"><span class=secno>4.1. </span> The
       &lsquo;<code class=css>flex()</code>&rsquo; notation</a>
-
-     <li><a href="#resolving-flexible-lengths"><span class=secno>4.2. </span>
-      Resolving Flexible Lengths</a>
     </ul>
 
    <li><a href="#alignment"><span class=secno>5. </span> Alignment</a>
@@ -1117,71 +1114,42 @@ <h3 id=flex-notation><span class=secno>4.1. </span> The &lsquo;<code
    positive and negative flexibility of zero and a preferred size of the
    length.
 
-  <p class=issue>Examples!
-
   <p class=issue>Transitioning to/from a &lt;length> (or to/from a &lt;flex>
    with 0 flexibility) doesn't work well if it's the only flexible item in
    the flexbox. Rather than smoothly transitioning, it suddenly jumps in size
    when the flexibility becomes non-zero. Can we fix this, perhaps with a
    value that represents a percentage of the free space or something?
 
-  <h3 id=resolving-flexible-lengths><span class=secno>4.2. </span> Resolving
-   Flexible Lengths</h3>
-
-  <p class=note>Note: This section is non-normative.
-
-  <p><a href="#flexible-length0"><i>Flexible lengths</i></a> are resolved
-   into normal, inflexible lengths by figuring out how large all of the <a
-   href="#flexible-length0"><i>flexible lengths</i></a> in the flexbox
-   <em>want</em> to be, then either growing or shrinking that <a
-   href="#preferred-size"><i>preferred size</i></a> so that the <a
-   href="#flexbox-item"><i>flexbox items</i></a> exactly fill the flexbox,
-   neither overflowing nor leaving extra unfilled space.
-
-  <p><a href="#flexible-length0"><i>Flexible lengths</i></a> are resolved
-   into normal inflexible lengths based on their <a
-   href="#preferred-size"><i>preferred size</i></a>, their flexibility, and
-   the amount of free space in the flexbox. The exact algorithm is described
-   in <a href="#layout-algorithm">a later section of this spec</a>, but in
-   general, it works like this:
-
-  <ol>
-   <li>First, set all the <a href="#flexible-length0"><i>flexible
-    lengths</i></a> to their <a href="#preferred-size"><i>preferred
-    size</i></a>.
-
-   <li>Then, lay out the flexbox, and see if there is free space left, or if
-    the flexbox is overflowing.
-
-   <li>If there's free space, distribute it among the <a
-    href="#flexible-length0"><i>flexible lengths</i></a> in proportion to
-    their <a href="#positive-flexibility"><i>positive flexibility</i></a>. If
-    the flexbox is overflowing, shrink the <a
-    href="#flexible-length0"><i>flexible lengths</i></a> in proportion to
-    their <a href="#negative-flexibility"><i>negative flexibility</i></a>.
-
-   <li>If there's free space and any <a href="#flexible-length0"><i>flexible
-    lengths</i></a> are violating a max width or height constraint, change
-    them into the largest inflexible length that doesn't violate their
-    constraint and return to step 2. If the flexbox is overflowing and any <a
-    href="#flexible-length0"><i>flexible lengths</i></a> are violating a min
-    width or height constraint, change them into the smallest inflexible
-    length that doesn't violate their constraint and return to step 2.
-
-   <li>If there's free space and any <a href="#flexible-length0"><i>flexible
-    lengths</i></a> are violating a min width or height constraint, change
-    them into the smallest inflexible length that doesn't violate their
-    constraint and return to step 2. If the flexbox is overflowing and any <a
-    href="#flexible-length0"><i>flexible lengths</i></a> are violating a max
-    width or height constraint, change them into the largest inflexible
-    length that doesn't violate their constraint and return to step 2.
-  </ol>
-
-  <p class=issue>This is too much detail for a non-normative section. This is
-   living here only until I flesh out the layout algorithm section. Then this
-   can return to being a fairly simple explanation of what goes on.
+  <div class=example>
+   <p>The &lsquo;<code class=css>flex()</code>&rsquo; notation allows
+    elements to respond directly to the available space, in ways that are
+    difficult or impossible in normal CSS. One common example is a page with
+    one segment intended to stay on screen, and another section which may be
+    long but which shouldn't scroll the page, like a chat room:</p>
 
-  <p class=issue>Examples!
+   <pre>
+&lt;!DOCTYPE html>
+&lt;body>
+  &lt;header>Channel: #csswg  Topic: CSS IS AWE    SOME&lt;/header>
+  &lt;article id='messages'>
+  	&lt;p>&lt;b>Tab Atkins:&lt;/b> 
+  	  I think the layout algorithm is done.&lt;/p>
+  	&lt;p>&lt;b>Fantasai:&lt;/b> 
+  	  SUBMIT BEFORE ZOD.&lt;/p>
+  	...
+  &lt;/article>
+  &lt;form>
+  	&lt;input name='message'>
+  	&lt;button type='submit'>Send&lt;/button>
+  &lt;/form>
+ &lt;/body>
+ &lt;style>
+ body { display:flexbox; flex-flow: column; }
+ #messages { height: flex(1); }
+ &lt;/style></pre>
+
+   <p class=issue>Illustrate this example.</p>
+  </div>
 
   <h2 id=alignment><span class=secno>5. </span> Alignment</h2>
 

css3-flexbox/Overview.src.html

@@ -516,36 +516,34 @@ <h3 id='flex-notation'>
 
 	<p>A ''&lt;flex>'' value is transitionable, by transitioning the <i>preferred size</i>, <i>positive flexibility</i>, and <i>negative flexibility</i> independently.  ''&lt;flex>'' can also transition to and from a &lt;length>, by treating the length as if it were a flexible length with a positive and negative flexibility of zero and a preferred size of the length.</p>
 
-	<p class='issue'>Examples!</p>
-
 	<p class='issue'>Transitioning to/from a &lt;length> (or to/from a &lt;flex> with 0 flexibility) doesn't work well if it's the only flexible item in the flexbox.  Rather than smoothly transitioning, it suddenly jumps in size when the flexibility becomes non-zero.  Can we fix this, perhaps with a value that represents a percentage of the free space or something?</p>
 
+	<div class='example'>
+		<p>The ''flex()'' notation allows elements to respond directly to the available space, in ways that are difficult or impossible in normal CSS.  One common example is a page with one segment intended to stay on screen, and another section which may be long but which shouldn't scroll the page, like a chat room:</p>
 
-<h3 id='resolving-flexible-lengths'>
-Resolving Flexible Lengths</h3>
-
-	<p class='note'>Note: This section is non-normative.</p>
-
-	<p><i>Flexible lengths</i> are resolved into normal, inflexible lengths by figuring out how large all of the <i>flexible lengths</i> in the flexbox <em>want</em> to be, then either growing or shrinking that <i>preferred size</i> so that the <i>flexbox items</i> exactly fill the flexbox, neither overflowing nor leaving extra unfilled space.</p>
-	
-	<p><i>Flexible lengths</i> are resolved into normal inflexible lengths based on their <i>preferred size</i>, their flexibility, and the amount of free space in the flexbox.  The exact algorithm is described in <a href="#layout-algorithm">a later section of this spec</a>, but in general, it works like this:</p>
-
-	<ol>
-		<li>First, set all the <i>flexible lengths</i> to their <i>preferred size</i>.</li>
-
-		<li>Then, lay out the flexbox, and see if there is free space left, or if the flexbox is overflowing.</li>
-
-		<li>If there's free space, distribute it among the <i>flexible lengths</i> in proportion to their <i>positive flexibility</i>.  If the flexbox is overflowing, shrink the <i>flexible lengths</i> in proportion to their <i>negative flexibility</i>.</li>
-
-		<li>If there's free space and any <i>flexible lengths</i> are violating a max width or height constraint, change them into the largest inflexible length that doesn't violate their constraint and return to step 2.  If the flexbox is overflowing and any <i>flexible lengths</i> are violating a min width or height constraint, change them into the smallest inflexible length that doesn't violate their constraint and return to step 2.</li>
-
-		<li>If there's free space and any <i>flexible lengths</i> are violating a min width or height constraint, change them into the smallest inflexible length that doesn't violate their constraint and return to step 2.  If the flexbox is overflowing and any <i>flexible lengths</i> are violating a max width or height constraint, change them into the largest inflexible length that doesn't violate their constraint and return to step 2.</li>
-	</ol>
-
-	<p class='issue'>This is too much detail for a non-normative section.  This is living here only until I flesh out the layout algorithm section.  Then this can return to being a fairly simple explanation of what goes on.</p>
-
-	<p class='issue'>Examples!</p>
-
+		<pre>
+&lt;!DOCTYPE html>
+&lt;body>
+  &lt;header>Channel: #csswg  Topic: CSS IS AWE    SOME&lt;/header>
+  &lt;article id='messages'>
+  	&lt;p>&lt;b>Tab Atkins:&lt;/b> 
+  	  I think the layout algorithm is done.&lt;/p>
+  	&lt;p>&lt;b>Fantasai:&lt;/b> 
+  	  SUBMIT BEFORE ZOD.&lt;/p>
+  	...
+  &lt;/article>
+  &lt;form>
+  	&lt;input name='message'>
+  	&lt;button type='submit'>Send&lt;/button>
+  &lt;/form>
+ &lt;/body>
+ &lt;style>
+ body { display:flexbox; flex-flow: column; }
+ #messages { height: flex(1); }
+ &lt;/style></pre>
+
+		<p class='issue'>Illustrate this example.</p>
+	</div> 
 
 <h2 id='alignment'>
 Alignment</h2>