w3c
diff --git a/‎css-display/Overview.bs‎
Lines changed: 137 additions & 80 deletions b/‎css-display/Overview.bs‎
Lines changed: 137 additions & 80 deletions
@@ -71,7 +71,7 @@ Controlling Layout Modes: the 'display' property</h2>
 
 	<pre class="propdef">
 	Name: display
-	Value: [ <<display-inside>> || <<display-outside>> || list-item ] <<display-box>> | <<display-internal>> | <<display-legacy>>
+	Value: [ <<display-inside>> || <<display-outside>> ] | <<display-listitem>> | <<display-internal>> | <<display-box>> | <<display-legacy>>
 	Initial: inline
 	Applies to: all elements
 	Inherited: no
@@ -82,7 +82,8 @@ Controlling Layout Modes: the 'display' property</h2>
 
 	<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-outside></dfn>  = block | inline | run-in ;
+	<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 |
@@ -93,25 +94,25 @@ Controlling Layout Modes: the 'display' property</h2>
 	                     inline-table | inline-flex | inline-grid ;
 	</pre>
 
-	The 'display' property defines how an element generates boxes,
-	and how its boxes interact with the layout of their ancestors.\
-	It defines two basic qualities of the boxes:
+	The 'display' property defines two basic qualities
+	of how an element generates boxes:
 
-	* the <dfn export>inner display type</dfn>,
+	* 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>outer display type</dfn>,
+	* the <dfn export local-lt="outer">outer display type</dfn>,
 		which dictates how the box participates in its parent formatting context.
 
-	Additional, it controls some other box-generation details,
+	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.
 
-<h3>
+<h3 id="major-layout-modes">
 The Major Layout Modes</h3>
 
 	The most common values of display correspond directly to the major layout algorithms in CSS.
 
-	The <<display-inside>> keywords are defined as follows:
+	The <<display-inside>> keywords specify the element's <a>inner display type</a>,
+	and are defined as follows:
 
 	<dl dfn-type="value" dfn-for="display, <display-inside>">
 		<dt><dfn>flow</dfn>
@@ -141,7 +142,8 @@ The Major Layout Modes</h3>
 			The element lays out its contents using ruby layout. [[!CSS3RUBY]]
 	</dl>
 
-	The <<display-outside>> keywords are defined as follows:
+	The <<display-outside>> keywords specify the element's <a>outer display type</a>,
+	and are defined as follows:
 
 	<dl dfn-type="value" dfn-for="display, <display-outside>">
 		<dt><dfn>block</dfn>
@@ -165,50 +167,36 @@ The Major Layout Modes</h3>
 	</dl>
 
 	If a <<display-inside>> is specified but <<display-outside>> is omitted,
-	<<display-outside>> defaults to ''block'',
-	except that ''ruby'' defaults to ''inline''.
+	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,
-	<<display-inside>> defaults to ''flow''.
-
-	The <dfn value for=display>list-item</dfn> keyword
-	makes the element a <a>list item</a>.
-	If <<display-inside>> is unspecified,
-	it defaults to ''flow''.
+	the element's <a>inner display type</a> defaults to ''flow''.
+
+	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,
+	the principal box's <a>inner display type</a> defaults to ''flow''.
 	If <<display-outside>> is unspecified,
-	it defaults to ''block''.
-
-<h3>
-Box Generation</h3>
-
-
-	<dl dfn-type=value dfn-for="display, <display-box>">
-		<dt><dfn>contents</dfn>
-		<dd>
-			The element itself does not generate any boxes,
-			but its children and pseudo-elements still generate boxes as normal.
-			For the purposes of box generation and layout,
-			the element must be treated as if it had been replaced with its children and pseudo-elements in the document tree.
+	the principal box's <a>outer display type</a> defaults to ''block''.
 
-			Issue: ''contents'' currently only has an effect on box generation and layout.
-			Other things that care about the document tree are unaffected, like counter scopes.
-			Is this what we want?
-
-		<dt><dfn>none</dfn>
-		<dd>
-			The element generates no boxes,
-			and does not participate in any formatting context.
+	Issue: Update Lists module to be referenceable here instead.
 
-			Note: This value exists for legacy reasons,
-			and interacts with the separate 'box-suppress' property.
+<h3 id="layout-specific-display">
+Layout-Specific Display Types</h3>
 
-			Advisement: It is recommended that 'box-suppress' be used instead of ''display: none'',
-			so that the element's display type is automatically preserved
-			for when it's no longer suppressed.
-	</dl>
+	Some layout modes, such as ''table'' and ''ruby'',
+	have a complex internal structure,
+	with several different roles that their children and descendants can fill.
+	This section defines those "internal" 'display' values,
+	which only have meaning within a particular layout mode.
 
-<h3>
-Layout-Specific Display Types</h3>
+	Unless otherwise specified,
+	both the <a>inner display type</a> and the <a>outer display type</a>
+	of elements using these 'display' values
+	are set to the given keyword.
 
 	The <<display-internal>> keywords are defined as follows:
 
@@ -218,54 +206,114 @@ Layout-Specific Display Types</h3>
 			The element is an <dfn dfn>internal table element</dfn>,
 			and participates in a table layout context. [[!CSS21]]
 
-			''table-cell'' and ''table-caption'' are <a>layout-specific leaf types</a>;
-			the rest are <a>layout-specific internal types</a>.
+			''table-cell'' and ''table-caption'' have a ''flow-root'' <a>inner display type</a>.
 
 		<dt><dfn>ruby-base</dfn>, <dfn&g
F882
t;ruby-text</dfn>, <dfn>ruby-base-container</dfn>, <dfn>ruby-text-container</dfn>
 		<dd>
 			The element is an <dfn dfn>internal ruby element</dfn>,
 			and participates in a ruby layout context. [[!CSS3RUBY]]
 
-			''ruby-base'' and ''ruby-text'' are <a>layout-specific leaf types</a>;
-			''ruby-base-container'' and ''ruby-text-container'' are <a>layout-specific internal types</a>.
+			''ruby-base'' and ''ruby-text'' have a ''flow-root'' <a>inner display type</a>.
 	</dl>
 
-	The <<display-internal>> values are specialized for particular formatting contexts,
-	and don't have meaning outside of those specific contexts:
+	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
+		must have a ''table-row'' parent box.
+
+		If it is misparented, like so:
+
+		<pre class="lang-markup">
+		&lt;div style="display:block;">
+			&lt;div style="display:table-cell">...&lt;/div>
+		&lt;/div>
+		</pre>
+
+		It will generate wrapper boxes around itself,
+		producing a structure like:
+
+		<pre>
+		block box
+		└anonymous table box
+		 └anonymous table-row-group box
+		  └anonymous table-row box
+		   └table-cell box
+		</pre>
+
+		Even if the parent is another <a>internal table element</a>,
+		if it's not the <em>correct</em> one,
+		wrapper boxes will be generated.
+		For example, in the following markup:
+
+		<pre class="lang-markup">
+		&lt;div style="display:table;">
+			&lt;div style="display:table-row">
+				&lt;div style="display:table-cell">...&lt;/div>
+			&lt;/div>
+		&lt;/div>
+		</pre>
+
+		Anonymous wrapper box generation will produce:
+
+		<pre>
+		table box
+		└anonymous table-row-group box
+		 └table-row box
+		  └table-cell box
+		</pre>
+
+		This "fix-up" ensures that the  Table Layout has a predictable structure to operate on.
+	</div>
+
+<h3 id="box-generation">
+Box Generation</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.
 
-	<dl>
-		<dt><dfn>layout-specific internal types</dfn>
+	The <<display-box>> keywords are defined as follows:
+
+	<dl dfn-type=value dfn-for="display, <display-box>">
+		<dt><dfn>contents</dfn>
 		<dd>
-			These display types require their parent and children to be of particular display types.
-			For example, a ''table-row'' box requires its parent to be a <a>table row group box</a>
-			and its children to be ''table-cell'' boxes.
+			The element itself does not generate any boxes,
+			but its children and pseudo-elements still generate boxes as normal.
+			For the purposes of box generation and layout,
+			the element must be treated as if it had been replaced with its children and pseudo-elements in the document tree.
+
+			Issue: ''contents'' currently only has an effect on box generation and layout.
+			Other things that care about the document tree are unaffected, like counter scopes.
+			Is this what we want?
 
-		<dt><dfn>layout-specific leaf types</dfn>
+		<dt><dfn>none</dfn>
 		<dd>
-			These display types require their parent to be of a particular display type,
-			and automatically specify particular <a>inner display types</a>,
-			as defined by their respective specifications.
-			For example, a ''table-caption'' box must have a ''table'' parent,
-			and behaves as a ''block'' for its children.
-	</dl>
+			The element and its descendants generates no boxes.
 
-	Boxes with layout-specific types generate wrapper boxes around themselves
-	when placed in an incompatible parent,
-	as defined by their respective specifications.
+			Advisement: It is recommended that 'box-suppress' be used instead of ''display: none'',
+			so that the element's display type is automatically preserved
+			for when it's no longer suppressed.
+	</dl>
 
-<h3>
+<h3 id='legacy-display'>
 Legacy Display Values</h3>
 
+	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.
+
 	The <<display-legacy>> keywords are defined as follows:
 
 	<dl dfn-type=value dfn-for="display, <display-legacy>">
 		<dt><dfn>inline-block</dfn>
 		<dd>
-			Behavas as ''inline flow-root''.
-
-		<dt><dfn>inline-list-item</dfn>
-		<dd>
-			Behaves as ''inline list-item''.
+			Behaves as ''inline flow-root''.
 
 		<dt><dfn>inline-table</dfn>
 		<dd>
@@ -285,8 +333,8 @@ Automatic Box Type Transformations</h3>
 
 	Some layout effects require <dfn export lt="blockify|blockification">blockification</dfn>
 	or <dfn export lt="inlinify|inlinification">inlinification</dfn> of the box type,
-	causing the box’s <a>outer display type</a>, if it is not ''none'' or ''contents'',
-	to compute to ''block'' or ''inline'' (respectively).
+	which sets the box’s <a>outer display type</a>, if it is not ''none'' or ''contents'',
+	to ''block'' or ''inline'' (respectively).
 
 	<div class='example'>
 		Some examples of this include:
@@ -298,9 +346,10 @@ Automatic Box Type Transformations</h3>
 		</ul>
 	</div>
 
-	When a box is <a>inlinified</a>,
-	it recursively <a>inlinifies</a> all of its in-flow children
-	unless it itself establishes a new formatting context,
+	If a box with a ''flow'' <a>inner display type</a> is <a>blockified</a>,
+	its <a>inner display type</a> becomes ''flow-root''.
+	If a box with a ''flow'' <a>inner display type</a> is <a>inlinified</a>,
+	it recursively <a>inlinifies</a> all of its in-flow children,
 	so that no block-level descendants
 	break up the inline formatting context in which it participates.
 
@@ -311,6 +360,14 @@ Automatic Box Type Transformations</h3>
 <h2 id='box-suppress'>
 Controlling box generation: the 'box-suppress' property</h2>
 
+	''display:none'' was historically used as a "toggle" to switch between displaying an element or not.
+	Making this reversible requires either setting up the CSS <a>cascade</a> properly,
+	or remembering what the display type was before it was set to ''none''.
+	To make this common use-case easier,
+	the 'box-suppress' property was defined to do the same thing,
+	so that toggling whether or not an element displays
+	can now be done without affecting its layout type when it <em>is</em> displayed.
+
 	<pre class="propdef">
 	Name: box-suppress
 	Value: show | discard | hide