w3c
diff --git a/‎css-display/Overview.bs‎
Lines changed: 107 additions & 88 deletions b/‎css-display/Overview.bs‎
Lines changed: 107 additions & 88 deletions
@@ -93,25 +93,19 @@ Values</h3>
 
 	This specification follows the
 	<a href="http://www.w3.org/TR/CSS21/about.html#property-defs">CSS property
-	definition conventions</a> from [[!CSS21]]. Value types not defined in
-	this specification are defined in CSS Level 2 Revision 1 [[!CSS21]].
-	Other CSS modules may expand the definitions of these value types.
+	definition conventions</a> from [[!CSS21]].
 
 	In addition to the property-specific values listed in their definitions,
 	all properties defined in this specification also accept the
 	<a href="http://www.w3.org/TR/css3-values/#common-keywords">CSS-wide keywords</a>
 	as their property value. For readability it has not been repeated explicitly.
 
 <h2 id='the-display-properties'>
-Controlling Layout Modes: the 'display' property</h2>
-
-	The 'display' property controls the layout mode of elements
-	(how the element determines the sizes and positions of itself and its descendants),
-	and what boxes they and their descendants generate.
+Box Layout Modes: the 'display' property</h2>
 
 	<pre class="propdef">
 	Name: display
-	Value: [ <<display-inside>> || <<display-outside>> ] | <<display-listitem>> | <<display-internal>> | <<display-box>> | <<display-legacy>>
+	Value: [ <<display-outside>> || <<display-inside>> ] | <<display-listitem>> | <<display-internal>> | <<display-box>> | <<display-legacy>>
 	Initial: inline
 	Applies to: all elements
 	Inherited: no
@@ -120,123 +114,151 @@ Controlling Layout Modes: the 'display' property</h2>
 	Media: all
 	</pre>
 
-	The 'display' property, introduced in CSS 2.1,
-	defines what kind of boxes an element generates
-	(and whether it generates boxes at all),
-	and how it lays out its contents.
+	The 'display' property defines two basic qualities
+	of how an element generates boxes:
+
+	* the <dfn export local-lt="inner">inner display type</dfn>,
+		which defines the kind of <a>formatting context</a> it generates,
+		dictating how its descendant boxes are laid out.
+	* the <dfn export local-lt="outer">outer display type</dfn>,
+		which dictates how the box participates in its parent formatting context.
+
+	Some 'display' values have additional side-effects:
+	such as ''list-item'', which also generates a ''::marker'' pseudo-element,
+	and ''none'', which causes the element's entire subtree to be left out of the box tree.
+
+	Values are defined as follows:
 
 	<pre class='prod'>
-	<dfn>&lt;display-inside></dfn>   = flow | flow-root | table | flex | grid | ruby ;
 	<dfn>&lt;display-outside></dfn>  = block | inline | run-in ;
+	<dfn>&lt;display-inside></dfn>   = flow | flow-root | table | flex | grid | ruby ;
 	<dfn>&lt;display-listitem></dfn> = list-item && <<display-outside>>? && [ flow | flow-root ]?
-	<dfn>&lt;display-box></dfn> = contents | none ;
 	<dfn>&lt;display-internal></dfn> = table-row-group | table-header-group |
 	                     table-footer-group | table-row | table-cell |
 	                     table-column-group | table-column | table-caption |
 	                     ruby-base | ruby-text | ruby-base-container |
 	                     ruby-text-container ;
+	<dfn>&lt;display-box></dfn>      = contents | none ;
 	<dfn>&lt;display-legacy></dfn>   = inline-block | inline-list-item |
 	                     inline-table | inline-flex | inline-grid ;
 	</pre>
 
-	The 'display' property defines two basic qualities
-	of how an element generates boxes:
+<h3 id="outer-role">
+Outer Display Roles for Flow Layout: the ''block'', ''inline'', and ''run-in'' keywords</h3>
 
-	* the <dfn export local-lt="inner">inner display type</dfn>,
-		which defines the kind of <a>formatting context</a> it generates,
-		dictating how its descendant boxes are laid out.
-	* the <dfn export local-lt="outer">outer display type</dfn>,
-		which dictates how the box participates in its parent formatting context.
+	The <<display-outside>> keywords specify the element's <a>outer display type</a>,
+	which is essentially its role in <a>flow layout</a>.
+	They are defined as follows:
 
-	Additionally, it controls some other box-generation details,
-	such as whether an element is a <a>list item</a> that generates a ''::marker'' pseudo-element.
+	<dl dfn-type="value" dfn-for="display, <display-outside>">
+		<dt><dfn>block</dfn>
+		<dd>
+			The element generates a <dfn dfn>block-level box</dfn>. [[!CSS21]]
 
-<h3 id="major-layout-modes">
-The Major Layout Modes</h3>
+		<dt><dfn>inline</dfn>
+		<dd>
+			The element generates an <dfn dfn>inline-level box</dfn>. [[!CSS21]]
 
-	The most common values of display correspond directly to the major layout algorithms in CSS.
+		<dt><dfn>run-in</dfn>
+			The element generates a <a>run-in box</a>.
+			Run-in elements act like inlines or blocks,
+			depending on the surrounding elements.
+			See [[#run-in]] for details.
+	</dl>
+
+	If a <<display-outside>> value is specified but <<display-inside>> is omitted,
+	the element's <a>inner display type</a> defaults to ''flow''.
+
+<h3 id="inner-model">
+Inner Display Layout Models: the ''flow'', ''flow-root'', ''table'', ''grid'', and ''ruby'' keywords</h3>
 
 	The <<display-inside>> keywords specify the element's <a>inner display type</a>,
-	and are defined as follows:
+	which defines the type of formatting context that lays out its contents.
+	They are defined as follows:
 
 	<dl dfn-type="value" dfn-for="display, <display-inside>">
 		<dt><dfn>flow</dfn>
 		<dd>
-			The element lays out its contents using flow layout.
-			(Also known as "block" or "inline" layout.) [[!CSS21]]
+			The element lays out its contents using <dfn dfn>flow layout</dfn>
+			(<a href="http://www.w3.org/TR/CSS21/visuren.html">block-and-inline layout</a>).
+
+			If its <a>outer display type</a> is ''inline'' or ''run-in'',
+			and it is participating in a
+			<a href="http://www.w3.org/TR/CSS21/visuren.html#inline-formatting">block</a>
+			or <a href="http://www.w3.org/TR/CSS21/visuren.html#inline-formatting">inline</a>
+			formatting context,
+			then it generates an <a href="http://www.w3.org/TR/CSS21/visuren.html#inline-box">inline box</a>.
+
+			Otherwise it generates a <a>block container</a> box.
+
+			Depending on the value of other properties (such as 'position', 'float', or 'overflow')
+			and whether it is itself participating in a block or inline <a>formatting context</a>,
+			it either establishes a new <a href="http://www.w3.org/TR/CSS21/visuren.html#block-formatting">block formatting context</a> for its contents
+			or integrates its contents into its parent <a>formatting context</a>.
+			See <a href="http://www.w3.org/TR/CSS21/visuren.html">CSS2.1 Chapter 9</a>. [[!CSS21]]
 
 		<dt><dfn>flow-root</dfn>
 		<dd>
-			The element lays out its contents using flow layout,
-			and establishes a <a>block formatting context</a>. [[!CSS21]]
+			The element generates a <a>block container</a> box,
+			and lays out its contents using <a>flow layout</a>.
+			It always establishes a new <a href="http://www.w3.org/TR/CSS21/visuren.html#block-formatting">block formatting context</a> for its contents. [[!CSS21]]
 
 		<dt><dfn>table</dfn>
 		<dd>
-			The element lays out its contents using table layout. [[!CSS21]]
+			The element generates a principal <i>table wrapper box</i>
+			containing an additionally-generated <i>table box</i>,
+			and establishes a <i>table formatting context</i>. [[!CSS21]]
 
 		<dt><dfn>flex</dfn>
 		<dd>
-			The element lays out its contents using flex layout. [[!CSS3-FLEXBOX]]
+			The element generates a principal <a>flex container</a> box
+			and establishes a <a>flex formatting context</a>. [[!CSS3-FLEXBOX]]
 
 		<dt><dfn>grid</dfn>
 		<dd>
-			The element lays out its contents using grid layout. [[!CSS3-GRID-LAYOUT]]
+			The element generates a principal <a>grid container</a> box,
+			and establishes a <a>grid formatting context</a>. [[!CSS3-GRID-LAYOUT]]
 
 		<dt><dfn>ruby</dfn>
 		<dd>
-			The element lays out its contents using ruby layout. [[!CSS3RUBY]]
+			The element generates a principal <a>ruby container</a> box,
+			and establishes a <a>ruby formatting context</a>. [[!CSS3RUBY]]
 	</dl>
 
-	The <<display-outside>> keywords specify the element's <a>outer display type</a>,
-	and are defined as follows:
+	If a <<display-inside>> value is specified but <<display-outside>> is omitted,
+	the element's <a>outer display type</a> defaults to ''block''--
+	except for ''ruby'', which defaults to ''inline''.
 
-	<dl dfn-type="value" dfn-for="display, <display-outside>">
-		<dt><dfn>block</dfn>
-		<dd>
-			The element generates a <dfn dfn>block-level box</dfn>,
-			and participates in a block formatting context.
-			Other formatting contexts,
-			such as flex formatting contexts,
-			may also work with block-level elements. [[!CSS21]]
-
-		<dt><dfn>inline</dfn>
-		<dd>
-			The element generates an <dfn dfn>inline-level box</dfn>. [[!CSS21]]
-
-		<dt><dfn>run-in</dfn>
-		<dd>
-			The element generates a <a>run-in box</a>.
-			Run-in elements act like inlines or blocks,
-			depending on the surrounding elements.
-			See [[#run-in]] for details.
-	</dl>
-
-	If a <<display-inside>> is specified but <<display-outside>> is omitted,
-	the element's <a>outer display type</a> defaults to ''block'',
-	except for ''ruby'' it defaults to ''inline''.
-
-	If a <<display-outside>> is specified but <<display-inside>> is omitted,
-	the element's <a>inner display type</a> defaults to ''flow''.
+<h3 id="list-items">
+Generating Marker Boxes: the ''list-item'' keyword</h3>
 
 	The <dfn value for="display, <display-list-item>">list-item</dfn> keyword
-	makes the element generate a principal box of the specified type
-	together with a ''::marker'' pseudo-element box
-	(see <a href="http://www.w3.org/TR/CSS21/generate.html#lists">CSS 2.1§12.5 Lists</a>).
-	If neither ''flow'' nor ''flow-root'' is specified,
+	causes the element to generate a ''::marker'' pseudo-element box [[!CSS-PSEUDO-4]]
+	with the content specified by its 'list-style' properties
+	(<a href="http://www.w3.org/TR/CSS21/generate.html#lists">CSS 2.1§12.5 Lists</a>) [[!CSS21]]
+	together with a principal box of the specified type for its own contents.
+
+	If no <<display-inside>> value is specified,
 	the principal box's <a>inner display type</a> defaults to ''flow''.
-	If <<display-outside>> is unspecified,
+	If no <<display-outside>> value is specified,
 	the principal box's <a>outer display type</a> defaults to ''block''.
 
-	Issue: Update Lists module to be referenceable here instead.
+	Note: In this level, as restricted in the grammar,
+	a list-item can only be a block box,
+	a block formatting context root box,
+	an inline box,
+	or an inline-block box.
+	This restriction may be relaxed in a future level of this module.
 
 <h3 id="layout-specific-display">
-Layout-Specific Display Types</h3>
+Layout-Internal Display Types: the ''table-*'' and ''ruby-*'' keywords</h3>
 
-	Some layout modes, such as ''table'' and ''ruby'',
+	Some layout models, such as ''table'' and ''ruby'',
 	have a complex internal structure,
 	with several different roles that their children and descendants can fill.
-	which only have meaning within a particular layout mode.
+	which only have meaning within that particular layout mode.
 
 	Unless otherwise specified,
 	both the <a>inner display type</a> and the <a>outer display type</a>
@@ -258,15 +280,15 @@ Layout-Specific Display Types</h3>
 			The element is an <dfn dfn>internal ruby element</dfn>,
 			and participates in a ruby layout context. [[!CSS3RUBY]]
 
-			''ruby-base'' and ''ruby-text'' have a ''flow-root'' <a>inner display type</a>.
+			''ruby-base'' and ''ruby-text'' have a ''flow'' <a>inner display type</a>.
 	</dl>
 
 	Boxes with layout-specific display types generate anonymous wrapper boxes around themselves
 	when placed in an incompatible parent,
 	as defined by their respective specifications.
 
 	<div class='example'>
-		For example, Table Layout defines that a ''table-cell'' box
+		For example, Table Layout requires that a ''table-cell'' box
 		must have a ''table-row'' parent box.
 
 		If it is misparented, like so:
@@ -310,18 +332,15 @@ Layout-Specific Display Types</h3>
 		  └table-cell box
 		</pre>
 
-		This "fix-up" ensures that the  Table Layout has a predictable structure to operate on.
+		This "fix-up" ensures that table layout has a predictable structure to operate on.
 	</div>
 
 <h3 id="box-generation">
-Box Generation</h3>
+Box Generation: the ''none'' and ''contents'' keywords</h3>
 
 	While 'display' can control the <em>types</em> of boxes an element will generate,
 	it can also control whether an element will generate any boxes at all.
 
-	Elements with either of these values do not have <a>inner</a> or <a>outer display types</a>,
-	because they don't generate any boxes at all.
-
 	The <<display-box>> keywords are defined as follows:
 
 	<dl dfn-type=value dfn-for="display, <display-box>">
@@ -345,15 +364,15 @@ Box Generation</h3>
 			for when it's no longer suppressed.
 	</dl>
 
-<h3 id='legacy-display'>
-Legacy Display Values</h3>
+	Elements with either of these values do not have <a>inner</a> or <a>outer display types</a>,
+	because they don't generate any boxes at all.
 
-	CSS level 2 conflated the concepts of <a>inner</a> and <a>outer display types</a>,
-	so that block-level and inline-level variants of the same layout mode were given separate names.
-	Now that 'display' separates those,
-	these legacy values can be mapped into the separate concepts they represent.
+<h3 id='legacy-display'>
+Precomposed Inline-level Display Values</h3>
 
-	The <<display-legacy>> keywords are defined as follows:
+	CSS level 2 used a single-keyword syntax for 'display',
+	requiring separate keywords for block-level and inline-level variants of the same layout mode.
+	These <<display-legacy>> keywords map as follows:
 
 	<dl dfn-type=value dfn-for="display, <display-legacy>">
 		<dt><dfn>inline-block</dfn>