Clarifications to common values of flex.

Author: fantasai

css3-flexbox/Overview.html

@@ -428,8 +428,8 @@ <h2 class="no-num no-toc" id=table>Table of contents</h2>
      <li><a href="#flex-property"><span class=secno>7.1. </span> The ‘<code
       class=property>flex</code>’ Shorthand</a>
 
-     <li><a href="#flex-examples"><span class=secno>7.2. </span> Common
-      Values of ‘<code class=property>flex</code>’</a>
+     <li><a href="#flex-common"><span class=secno>7.2. </span> Common Values
+      of ‘<code class=property>flex</code>’</a>
 
      <li><a href="#flex-components"><span class=secno>7.3. </span> Components
       of Flexibility</a>
@@ -1256,7 +1256,8 @@ <h3 id=min-size-auto><span class=secno>4.5. </span> Implied Minimum Size of
    <dt><dfn id=min-auto title="min-width/height:auto">auto</dfn>
 
    <dd> When used as the value of a flex item's min main size property, this
-    keyword indicates a minimum main size of the min-content size.
+    keyword indicates a minimum of the min-content size, to help ensure that
+    the item is large enough to fit its contents.
     <p class=note> It is intended that this will compute to the ‘<code
      class=css>min-content</code>’ keyword when the specification defining
      it (<a
@@ -1973,7 +1974,8 @@ <h3 id=flex-property><span class=secno>7.1. </span> The ‘<a
    not a <a href="#flex-item"><i>flex item</i></a>, ‘<a href="#flex"><code
    class=property>flex</code></a>’ has no effect.
 
-  <p> The <var>&lt;&apos;flex-basis&apos;></var> component sets the <dfn
+  <p> The <var>&lt;<a href="#flex-basis-property">‘<code
+   class=property>flex-basis</code>’</a>></var> component sets the <dfn
    id=flex-basis>flex basis</dfn>, which is the initial <a
    href="#main-size"><i>main size</i></a> of the <a href="#flex-item"><i>flex
    item</i></a>, before free space is distributed according to the flex
@@ -1986,8 +1988,10 @@ <h3 id=flex-property><span class=secno>7.1. </span> The ‘<a
    specified with a unit. Unitless zero will either be interpreted as one of
    the flex ratios, or will make the declaration invalid.
 
-  <p> The <var>&lt;&apos;flex-grow&apos;></var> and
-   <var>&lt;&apos;flex-shrink&apos;></var> components set the <dfn
+  <p> The <var>&lt;<a href="#flex-grow">‘<code
+   class=property>flex-grow</code>’</a>></var> and <var>&lt;<a
+   href="#flex-basis-property">‘<code
+   class=property>flex-shrink</code>’</a>></var> components set the <dfn
    id=flex-grow-ratio>flex grow ratio</dfn> and <dfn
    id=flex-shrink-ratio>flex shrink ratio</dfn>, which determine how much the
    <a href="#flex-item"><i>flex item</i></a> will grow or shrink relative to
@@ -2005,7 +2009,7 @@ <h3 id=flex-property><span class=secno>7.1. </span> The ‘<a
    basis of zero) and "relative" flex (starting from a basis of the item's
    content size). </figcaption> </figure>
 
-  <h3 id=flex-examples><span class=secno>7.2. </span> Common Values of ‘<a
+  <h3 id=flex-common><span class=secno>7.2. </span> Common Values of ‘<a
    href="#flex"><code class=property>flex</code></a>’</h3>
 
   <p><em>This section is informative.</em>
@@ -2018,48 +2022,44 @@ <h3 id=flex-examples><span class=secno>7.2. </span> Common Values of ‘<a
 
    <dt>‘<code class=css>flex: 0 auto</code>’
 
-   <dd> Equivalent to ‘<code class=css>flex: 0 1 auto</code>’. The value
-    sets the size of the item according to the ‘<code
+   <dd> Equivalent to ‘<code class=css>flex: 0 1 auto</code>’. (This is
+    the initial value.) Sizes the item based on the ‘<code
     class=property>width</code>’/‘<code class=property>height</code>’
-    properties and makes the flex item inflexible when there is positive free
-    space, but allows it to shrink to its <a
-    href="#min-size-auto">minimum</a> when there is insufficient space. (If
-    the ‘<code class=property>width</code>’/‘<code
-    class=property>height</code>’ used as the <a href="#flex-basis"><i>flex
-    basis</i></a> computes to ‘<code class=css>auto</code>’, this will
-    size the flex item based on its contents.) The <a
-    href="#alignment">alignment abilities</a> or <a
+    properties. (If the item's <a href="#main-size-property"><i>main size
+    property</i></a> computes to ‘<code class=css>auto</code>’, this will
+    size the flex item based on its contents.) Makes the flex item inflexible
+    when there is positive free space, but allows it to shrink to its <a
+    href="#min-size-auto">minimum</a> when there is insufficient space. The
+    <a href="#alignment">alignment abilities</a> or <a
     href="#auto-margins">‘<code class=css>auto</code>’ margins</a> can be
-    used to align flex items within the flex container.
+    used to align flex items along the <a href="#main-axis"><i>main
+    axis</i></a>.
 
    <dt>‘<code class=css>flex: auto</code>’
 
-   <dd> Equivalent to ‘<code class=css>flex: 1 1 auto</code>’. This value
-    makes the flex item flexible, and sets the <a href="#flex-basis"><i>flex
-    basis</i></a> according to the ‘<code
-    class=property>width</code>’/‘<code class=property>height</code>’
-    properties. If all items are either ‘<code class=css>flex:
-    auto</code>’ or ‘<code class=css>flex: none</code>’, any free space
-    after the items have been sized will be distributed evenly to the items
-    with ‘<code class=css>flex: auto</code>’.
+   <dd> Equivalent to ‘<code class=css>flex: 1 1 auto</code>’. Sizes the
+    item based on the ‘<code class=property>width</code>’/‘<code
+    class=property>height</code>’ properties, but makes them fully
+    flexible, so that they absorb any free space along the <a
+    href="#main-axis"><i>main axis</i></a>. If all items are either ‘<code
+    class=css>flex: auto</code>’, ‘<code class=css>flex:
+    initial</code>’, or ‘<code class=css>flex: none</code>’, any
+    positive free space after the items have been sized will be distributed
+    evenly to the items with ‘<code class=css>flex: auto</code>’.
 
    <dt>‘<code class=css>flex: none</code>’
 
    <dd> Equivalent to ‘<code class=css>flex: 0 0 auto</code>’. This value
-    makes the flex item inflexible, and sets the size of the item according
-    to the ‘<code class=property>width</code>’/‘<code
-    class=property>height</code>’ properties. To size things normally but
-    still use the <a href="#alignment">alignment abilities</a> of flex
-    layout, set all the flex items to ‘<code class=css>flex: none</code>’
-    and then use ‘<code class=css>auto</code>’ margins or the alignment
-    properties. This is similar to <a href="#flex-initial">‘<code
-    class=css>initial</code>’</a>, except that flex items are not allowed
-    to shrink, even in overflow situations.
+    sizes the item according to the ‘<code
+    class=property>width</code>’/‘<code class=property>height</code>’
+    properties, but makes the flex item fully inflexible. This is similar to
+    <a href="#flex-initial">‘<code class=css>initial</code>’</a>, except
+    that flex items are not allowed to shrink, even in overflow situations.
 
    <dt>‘<code class=css>flex: &lt;positive-number></code>’
 
    <dd> Equivalent to ‘<code class=css>flex: &lt;positive-number> 1
-    0%</code>’. This value makes the flex item flexible, and sets the <a
+    0px</code>’. Makes the flex item flexible and sets the <a
     href="#flex-basis"><i>flex basis</i></a> to zero, resulting in an item
     that receives the specified proportion of the free space in the flex
     container. If all items in the flex container use this pattern, their
@@ -2069,7 +2069,8 @@ <h3 id=flex-examples><span class=secno>7.2. </span> Common Values of ‘<a
   <p> By default, flex items won't shrink below their minimum content size
    (the length of the longest word or fixed-size element). To change this,
    set the ‘<code class=property>min-width</code>’ or ‘<code
-   class=property>min-height</code>’ property.
+   class=property>min-height</code>’ property. (See <a
+   href="#min-size-auto">Implied Minimum Size of Flex Items</a>.)
 
   <h3 id=flex-components><span class=secno>7.3. </span> Components of
    Flexibility</h3>

css3-flexbox/Overview.src.html

@@ -898,7 +898,8 @@ <h3 id='min-size-auto'>
 		<dt><dfn title="min-width/height:auto" id='min-auto'>auto</dfn>
 		<dd>
 			When used as the value of a flex item's min main size property,
-			this keyword indicates a minimum main size of the min-content size.
+			this keyword indicates a minimum of the min-content size,
+			to help ensure that the item is large enough to fit its contents.
 
 			<p class='note'>
 				It is intended that this will compute to the ''min-content'' keyword
@@ -1468,7 +1469,7 @@ <h3 id='flex-property'>
 		'flex' has no effect.
 
 	<p>
-		The <var>&lt;&apos;flex-basis&apos;></var> component sets the <dfn>flex basis</dfn>,
+		The <var>&lt;<a href="#flex-basis-property">'flex-basis'</a>></var> component sets the <dfn>flex basis</dfn>,
 		which is the initial <i>main size</i> of the <i>flex item</i>,
 		before free space is distributed according to the flex ratios.
 		If omitted, the <i>flex basis</i> defaults to the length zero. 
@@ -1478,7 +1479,7 @@ <h3 id='flex-property'>
 		or will make the declaration invalid.
 
 	<p>
-		The <var>&lt;&apos;flex-grow&apos;></var> and <var>&lt;&apos;flex-shrink&apos;></var> components
+		The <var>&lt;<a href="#flex-grow">'flex-grow'</a>></var> and <var>&lt;<a href="#flex-basis-property">'flex-shrink'</a>></var> components
 		set the <dfn>flex grow ratio</dfn> and <dfn>flex shrink ratio</dfn>,
 		which determine how much the <i>flex item</i> will grow or shrink
 		relative to the rest of the <i>flex items</i> in the flex container
@@ -1487,7 +1488,7 @@ <h3 id='flex-property'>
 		<span class='note'>Note that this is different from the initial value of 'flex-grow', which is ''0''.</span>
 
 	<p id="flex-none">
-		The keyword 'none' computes to ''0 0 auto''. 
+		The keyword 'none' computes to ''0 0 auto''.
 
 	<figure>
 		<img src='images/rel-vs-abs-flex.svg' width='504' height='240'>
@@ -1500,7 +1501,7 @@ <h3 id='flex-property'>
 	</figure>
 
 
-<h3 id='flex-examples'>
+<h3 id='flex-common'>
 Common Values of 'flex'</h3>
 
 	<p><em>This section is informative.</em>
@@ -1512,40 +1513,37 @@ <h3 id='flex-examples'>
 		<dt id="flex-initial">''flex: initial''
 		<dt>''flex: 0 auto''
 		<dd>
-			Equivalent to ''flex: 0 1 auto''.
-			The value sets the size of the item according to the 'width'/'height' properties
-			and  makes the flex item inflexible when there is positive free space,
-			but allows it to shrink to its <a href="#min-size-auto">minimum</a> when there is insufficient space.
-			(If the 'width'/'height' used as the <i>flex basis</i> computes to ''auto'',
+			Equivalent to ''flex: 0 1 auto''. (This is the initial value.)
+			Sizes the item based on the 'width'/'height' properties.
+			(If the item's <i>main size property</i> computes to ''auto'',
 			this will size the flex item based on its contents.)
+			Makes the flex item inflexible when there is positive free space,
+			but allows it to shrink to its <a href="#min-size-auto">minimum</a> when there is insufficient space.
 			The <a href="#alignment">alignment abilities</a> or <a href="#auto-margins">''auto'' margins</a>
-			can be used to align flex items within the flex container.
+			can be used to align flex items along the <i>main axis</i>.
 
 		<dt>''flex: auto''
 		<dd>
 			Equivalent to ''flex: 1 1 auto''.
-			This value makes the flex item flexible,
-			and sets the <i>flex basis</i> according to the 'width'/'height' properties. 
-			If all items are either ''flex: auto'' or ''flex: none'',
-			any free space after the items have been sized will be distributed evenly to the items with ''flex: auto''.
+			Sizes the item based on the 'width'/'height' properties,
+			but makes them fully flexible, so that they absorb any free space along the <i>main axis</i>.
+			If all items are either ''flex: auto'', ''flex: initial'', or ''flex: none'',
+			any positive free space after the items have been sized will be distributed evenly to the items with ''flex: auto''.
 
 		<dt>''flex: none''
 		<dd>
 			Equivalent to ''flex: 0 0 auto''.
-			This value makes the flex item inflexible,
-			and sets the size of the item according to the 'width'/'height' properties.
-			To size things normally but still use the <a href="#alignment">alignment abilities</a> of flex layout,
-			set all the flex items to ''flex: none''
-			and then use ''auto'' margins or the alignment properties.
+			This value sizes the item according to the 'width'/'height' properties,
+			but makes the flex item fully inflexible.
 			This is similar to <a href="#flex-initial">''initial''</a>,
 			except that flex items are not allowed to shrink,
 			even in overflow situations.
 
 		<dt>''flex: &lt;positive-number>''
 		<dd>
-			Equivalent to ''flex: &lt;positive-number> 1 0%''.
-			This value makes the flex item flexible,
-			and sets the <i>flex basis</i> to zero, resulting in an item that receives the specified proportion of the free space in the flex container.
+			Equivalent to ''flex: &lt;positive-number> 1 0px''.
+			Makes the flex item flexible and sets the <i>flex basis</i> to zero,
+			resulting in an item that receives the specified proportion of the free space in the flex container.
 			If all items in the flex container use this pattern,
 			their sizes will be proportional to the specified flex ratio.
 	</dl>
@@ -1554,6 +1552,7 @@ <h3 id='flex-examples'>
 		By default, flex items won't shrink below their minimum content size
 		(the length of the longest word or fixed-size element).
 		To change this, set the 'min-width' or 'min-height' property.
+		(See <a href="#min-size-auto">Implied Minimum Size of Flex Items</a>.)
 
 <h3 id='flex-components'>
 Components of Flexibility</h3>