Rearrangements of prose in 'flex' definition, to use <dl> and put everything interesting all in one place for authors.

Author: fantasai

css3-flexbox/Overview.html

@@ -206,11 +206,11 @@
 
    <h1 id=head-box-flexible>CSS Flexible Box Layout Module</h1>
 
-   <h2 class="no-num no-toc" id=w3c-working>Editor's Draft, 6 August 2012</h2>
+   <h2 class="no-num no-toc" id=w3c-working>Editor's Draft, 7 August 2012</h2>
 
    <dl>
     <dt>This version:
-     <!--<dd><a href="http://www.w3.org/TR/2012/ED-css3-flexbox-20120806/">http://www.w3.org/TR/2012/WD-css3-flexbox-20120806/</a>-->
+     <!--<dd><a href="http://www.w3.org/TR/2012/ED-css3-flexbox-20120807/">http://www.w3.org/TR/2012/WD-css3-flexbox-20120807/</a>-->
 
 
     <dd><a
@@ -1974,40 +1974,87 @@ <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;<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
-   ratios. If omitted, the <a href="#flex-basis"><i>flex basis</i></a>
-   defaults to the length zero. <span class=note>Note that this is different
-   from the initial value of ‘<a href="#flex-basis0"><code
-   class=property>flex-basis</code></a>’, which is <a
-   href="#flex-basis-auto">‘<code class=css>auto</code>’</a>.</span> Zero
-   values for the <var>&lt;&apos;flex-basis&apos;></var> component must be
-   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;<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
-   the rest of the <a href="#flex-item"><i>flex items</i></a> in the flex
-   container when free space is distributed. When omitted, they are set to
-   ‘<code class=css>1</code>’. <span class=note>Note that this is
-   different from the initial value of ‘<a href="#flex-grow"><code
-   class=property>flex-grow</code></a>’, which is ‘<code
-   class=css>0</code>’.</span>
-
-  <p id=flex-none> The keyword ‘<code class=property>none</code>’
-   computes to ‘<code class=css>0 0 auto</code>’. <figure> <img
-   height=240 src="images/rel-vs-abs-flex.svg" width=504> <figcaption> A
-   diagram showing the difference between "absolute" flex (starting from a
-   basis of zero) and "relative" flex (starting from a basis of the item's
-   content size). </figcaption> </figure>
+  <dl>
+   <dt><var>&lt;‘<a href="#flex-grow"><code
+    class=property>flex-grow</code></a>’></var>
+
+   <dd>
+    <p> This <var>&lt;number></var> component sets ‘<a
+     href="#flex-grow"><code class=property>flex-grow</code></a>’ <a
+     href="#flex-components">longhand</a> and specifies the <dfn
+     id=flex-grow-ratio>flex grow ratio</dfn>, which determines how much the
+     <a href="#flex-item"><i>flex item</i></a> will grow relative to the rest
+     of the <a href="#flex-item"><i>flex items</i></a> in the flex container
+     when positive free space is distributed. When omitted, it is set to
+     ‘<code class=css>1</code>’.
+
+   <dt><var>&lt;‘<a href="#flex-shrink"><code
+    class=property>flex-shrink</code></a>’></var>
+
+   <dd>
+    <p> This <var>&lt;number></var> component sets ‘<a
+     href="#flex-shrink"><code class=property>flex-shrink</code></a>’ <a
+     href="#flex-components">longhand</a> and specifies the <dfn
+     id=flex-shrink-ratio>flex shrink ratio</dfn>, which determines how much
+     the <a href="#flex-item"><i>flex item</i></a> will shrink relative to
+     the rest of the <a href="#flex-item"><i>flex items</i></a> in the flex
+     container when negative free space is distributed. When omitted, it is
+     set to ‘<code class=css>1</code>’.
+
+   <dt><var>&lt;‘<a href="#flex-basis-propdef"><code
+    class=property>flex-basis</code></a>’></var>
+
+   <dd>
+    <p> This component, which takes the same values as the ‘<code
+     class=property>width</code>’ property, sets the ‘<a
+     href="#flex-basis-propdef"><code class=property>flex-basis</code></a>’
+     <a href="#flex-components">longhand</a> and specifies the <dfn
+     id=flex-basis>flex basis</dfn>: 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 ratios. When omitted
+     from the ‘<a href="#flex"><code class=property>flex</code></a>’
+     shorthand, its specified value is the length zero.
+
+    <p class=note> If not omitted, a zero
+     <var>&lt;&apos;flex-basis&apos;></var> component must be either
+     specified with a unit or preceded by both flex ratios. Otherwise it will
+     either be interpreted as one of the flex ratios, or will make the
+     declaration invalid.
+
+    <p> If the specified ‘<a href="#flex-basis-propdef"><code
+     class=property>flex-basis</code></a>’ is <a
+     href="#flex-basis-auto">‘<code class=css>auto</code>’</a>, the used
+     <a href="#flex-basis"><i>flex basis</i></a> is the value of the
+     element's <a href="#main-size-property"><i>main size property</i></a>.
+     (This can itself be the keyword ‘<code class=css>auto</code>’, which
+     sizes the element based on its contents.) <figure> <img height=240
+     src="images/rel-vs-abs-flex.svg" width=504> <figcaption> A diagram
+     showing the difference between "absolute" flex (starting from a basis of
+     zero) and "relative" flex (starting from a basis of the item's content
+     size). The three items have flex ratios of ‘<code
+     class=css>1</code>’, ‘<code class=css>1</code>’, and ‘<code
+     class=css>2</code>’, respectively. </figcaption> </figure>
+
+   <dt><dfn id=flex-none>‘<code class=css>none</code>’</dfn>
+
+   <dd>
+    <p>The keyword ‘<a href="#flex-none"><code
+     class=property>none</code></a>’ computes to ‘<code class=css>0 0
+     auto</code>’.
+  </dl>
+
+  <p> The initial values of the ‘<a href="#flex"><code
+   class=property>flex</code></a>’ components are equivalent to <a
+   href="#flex-initial">‘<code class=css>flex: 0 1 auto</code>’</a>.
+
+  <p class=note> Note that the initial values of ‘<a
+   href="#flex-grow"><code class=property>flex-grow</code></a>’ and ‘<a
+   href="#flex-basis-propdef"><code class=property>flex-basis</code></a>’
+   are different from their defaults when omitted in the ‘<a
+   href="#flex"><code class=property>flex</code></a>’ shorthand. This so
+   that the ‘<a href="#flex"><code class=property>flex</code></a>’
+   shorthand can better accommodate the most <a href="#flex-common">common
+   cases</a>.
 
   <h3 id=flex-common><span class=secno>7.2. </span> Common Values of ‘<a
    href="#flex"><code class=property>flex</code></a>’</h3>
@@ -2018,9 +2065,9 @@ <h3 id=flex-common><span class=secno>7.2. </span> Common Values of ‘<a
    href="#flex"><code class=property>flex</code></a>’ values:
 
   <dl>
-   <dt id=flex-initial>‘<code class=css>flex: initial</code>’
+   <dt id=flex-initial>‘<code class=css>flex: 0 auto</code>’
 
-   <dt>‘<code class=css>flex: 0 auto</code>’
+   <dt>‘<code class=css>flex: initial</code>’
 
    <dd> Equivalent to ‘<code class=css>flex: 0 1 auto</code>’. (This is
     the initial value.) Sizes the item based on the ‘<code
@@ -2075,13 +2122,14 @@ <h3 id=flex-common><span class=secno>7.2. </span> Common Values of ‘<a
   <h3 id=flex-components><span class=secno>7.3. </span> Components of
    Flexibility</h3>
 
-  <p> Individual components of flexibility can be controlled by separate
-   properties.
+  <p> Individual components of flexibility can be controlled by independent
+   longhand properties.
 
   <p class=note> Authors are encouraged to control flexibility using the
    ‘<a href="#flex"><code class=property>flex</code></a>’ shorthand
    rather than with component properties, as the shorthand correctly resets
-   any unspecified components to accommodate common uses.
+   any unspecified components to accommodate <a href="#flex-common">common
+   uses</a>.
 
   <h4 id=flex-grow-property><span class=secno>7.3.1. </span> The ‘<a
    href="#flex-grow"><code class=property>flex-grow</code></a>’ property</h4>
@@ -2199,14 +2247,15 @@ <h4 id=flex-shrink-property><span class=secno>7.3.2. </span> The ‘<a
    are invalid.
 
   <h4 id=flex-basis-property><span class=secno>7.3.3. </span> The ‘<a
-   href="#flex-basis0"><code class=property>flex-basis</code></a>’ property</h4>
+   href="#flex-basis-propdef"><code class=property>flex-basis</code></a>’
+   property</h4>
 
   <table class=propdef>
    <tbody>
     <tr>
      <th>Name:
 
-     <td><dfn id=flex-basis0>flex-basis</dfn>
+     <td><dfn id=flex-basis-propdef>flex-basis</dfn>
 
     <tr>
      <th><a href="#values">Value</a>:
@@ -2257,32 +2306,23 @@ <h4 id=flex-basis-property><span class=secno>7.3.3. </span> The ‘<a
       grammar</abbr>
   </table>
 
-  <p> The ‘<a href="#flex-basis0"><code
+  <p> The ‘<a href="#flex-basis-propdef"><code
    class=property>flex-basis</code></a>’ property sets the <a
    href="#flex-basis"><i>flex basis</i></a>. Negative lengths are invalid.
 
-  <p> If the computed value is <dfn id=flex-basis-auto
-   title="flex-basis: auto">‘<code class=css>auto</code>’</dfn> on a <a
-   href="#flex-item"><i>flex item</i></a>, the used value of ‘<a
-   href="#flex-basis0"><code class=property>flex-basis</code></a>’ is the
-   used value of the element's <a href="#main-size-property"><i>main size
-   property</i></a>. Otherwise, the used value of ‘<a
-   href="#flex-basis0"><code class=property>flex-basis</code></a>’ is
-   resolved the same way as the <a href="#main-size-property"><i>main size
-   property</i></a>.
-
-  <p> As with ‘<code class=property>width</code>’, percentage values of
-   ‘<a href="#flex-basis0"><code class=property>flex-basis</code></a>’
-   are resolved against the flex item's containing block, i.e. its flex
-   container. And <a
-   href="http://www.w3.org/TR/CSS21/visudet.html#propdef-width">as with
-   ‘<code class=property>width</code>’</a> in <a href="#CSS21"
-   rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>, if that containing block's
-   size is indefinite, the result is undefined.
-
-  <p> Like the ‘<code class=property>width</code>’ and ‘<code
-   class=property>height</code>’ properties, ‘<a
-   href="#flex-basis0"><code class=property>flex-basis</code></a>’
+  <p> Except for <dfn id=flex-basis-auto title="flex-basis: auto">‘<code
+   class=css>auto</code>’</dfn>, which retrieves the value of the <a
+   href="#main-size-property"><i>main size property</i></a>, ‘<a
+   href="#flex-basis-propdef"><code class=property>flex-basis</code></a>’
+   is resolved the same way as <a
+   href="http://www.w3.org/TR/CSS21/visudet.html#propdef-width">‘<code
+   class=property>width</code>’</a> in horizontal writing modes <a
+   href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>: percentage
+   values of ‘<a href="#flex-basis-propdef"><code
+   class=property>flex-basis</code></a>’ are resolved against the flex
+   item's containing block, i.e. its flex container, and if that containing
+   block's size is indefinite, the result is undefined. Similarly, ‘<a
+   href="#flex-basis-propdef"><code class=property>flex-basis</code></a>’
    determines the size of the content box, unless otherwise specified such as
    by ‘<code class=property>box-sizing</code>’ <a href="#CSS3UI"
    rel=biblioentry>[CSS3UI]<!--{{CSS3UI}}--></a>.
@@ -3899,11 +3939,13 @@ <h2 class=no-num id=changes>Changes</h2>
    <li>Defined <a href="#painting">painting behavior of flex items</a>.
 
    <li>Made ‘<code class=property>z-index</code>’ automatically apply to
-    flex items. <!-- 
-		<li>Defined which properties affect placeholders.
-		<li>Defined which properties apply to the table wrapper box vs. the table box of a table element.
--->
-    
+    flex items.
+
+   <li>Changed how absolutely-positioned flex container children are handled
+    so that they don't impact layout.
+
+   <li>Defined which properties apply to the table wrapper box vs. the table
+    box of a table element.
 
    <li>Defined interaction of ‘<a href="#order"><code
     class=property>order</code></a>’ and <a
@@ -4015,7 +4057,7 @@ <h2 class=no-num id=property>Property index</h2>
      <td>visual
 
     <tr>
-     <th><a class=property href="#flex-basis0">flex-basis</a>
+     <th><a class=property href="#flex-basis-propdef">flex-basis</a>
 
      <td>&lt;&apos;width&apos;>
 
@@ -4228,7 +4270,7 @@ <h2 class=no-num id=index>Index</h2>
    <li>flex basis, <a href="#flex-basis"
     title="flex basis"><strong>7.1.</strong></a>
 
-   <li>flex-basis, <a href="#flex-basis0"
+   <li>flex-basis, <a href="#flex-basis-propdef"
     title=flex-basis><strong>7.3.3.</strong></a>
 
    <li>flex-basis: auto, <a href="#flex-basis-auto"
@@ -4335,6 +4377,9 @@ <h2 class=no-num id=index>Index</h2>
    <li>multi-line, <a href="#multi-line"
     title=multi-line><strong>6.</strong></a>
 
+   <li>‘<a href="#flex-none"><code class=css>none</code></a>’, <a
+    href="#flex-none" title="''none''"><strong>7.1.</strong></a>
+
    <li>‘<a href="#flex-flow-nowrap"><code class=css>nowrap</code></a>’,
     <a href="#flex-flow-nowrap" title="''nowrap''"><strong>5.2.</strong></a>