w3c
diff --git a/‎css-grid/Overview.bs‎
Lines changed: 37 additions & 19 deletions b/‎css-grid/Overview.bs‎
Lines changed: 37 additions & 19 deletions
@@ -1492,7 +1492,7 @@ Sizing Auto-generated Rows and Columns: the 'grid-auto-rows' and 'grid-auto-colu
 
 	<pre class='propdef'>
 	Name: grid-auto-flow
-	Value: [ row | column ] && dense?  |   stack && [ row | column ]?
+	Value: <<auto-flow-direction>> || <<auto-flow-algorithm>>
 	Initial: row
 	Applies to: <a>grid containers</a>
 	Inherited: no
@@ -1501,12 +1501,23 @@ Sizing Auto-generated Rows and Columns: the 'grid-auto-rows' and 'grid-auto-colu
 	Computed value: specified value
 	</pre>
 
+	<pre class=prod>
+		<dfn><<auto-flow-direction>></dfn> = row | column
+		<dfn><<auto-flow-algorithm>></dfn> = dense | stack
+	</pre>
+
 	<a>Grid items</a> that aren't explicitly placed are automatically placed
-	into an unoccupied space in the <a>grid container</a>.
-	The 'grid-auto-flow' property controls the direction in which the search for unoccupied space takes place,
+	into an unoccupied space in the <a>grid container</a>
+	by the <a>auto-placement algorithm</a>.
+	'grid-auto-flow' controls how the <a>auto-placement algorithm</a> works,
+	specifying exactly how auto-placed items get flowed into the grid.
+
+	The <<auto-flow-direction>> determines what direction the search for unoccupied space takes place,
 	and whether rows or columns are added as needed to accommodate the content.
+	If this is omitted, it means the same as specifying ''grid-auto-flow/row''.
 
-	<dl dfn-for=grid-auto-flow dfn-type=value>
+	<dl dfn-for="grid-auto-flow <auto-flow-direction>" dfn-type=value>
 		<dt><dfn>row</dfn>
 		<dd>
 			The <a>auto-placement algorithm</a> places items
@@ -1518,33 +1529,40 @@ Sizing Auto-generated Rows and Columns: the 'grid-auto-rows' and 'grid-auto-colu
 			The <a>auto-placement algorithm</a> places items
 			by filling each column in turn,
 			adding new columns as necessary.
+	</dl>
+
+	The <<auto-flow-algorithm>> determines how the search for free space is conducted,
+	and where items are placed.
+	If omitted, it indicates that a “sparse” algorithm is to be used.
+
+	<dl dfn-for="grid-auto-flow <auto-flow-algorithm>" dfn-type=value>
+		<dt>omitted (“sparse”)
+		<dd>
+			If the <<auto-flow-algorithm>> is not specified,
+			the auto-placement algorithm uses a “sparse” packing algorithm.
+			It maintains a “cursor” that gradually moves through the grid,
+			looking for sufficiently large unoccupied areas to place each auto-placed <a>grid item</a> in turn.
+			It never returns to already-searched areas of the grid,
+			even if a large <a>grid item</a> causes the “cursor” to skip over areas
+			that would be large enough to fit smaller subsequent <a>grid items</a>.
+
+			Note: While this algorithm can possibly leave large “holes” in a grid,
+			it ensures that all of the auto-placed items appear “in order”,
+			regardless of the shape of the items and the grid.
 
 		<dt><dfn>dense</dfn>
 		<dd>
-			If specified, the auto-placement algorithm uses a "dense" packing algorithm,
+			If specified, the auto-placement algorithm uses a “dense” packing algorithm,
 			which attempts to fill in holes in the grid if smaller items come up later.
-			(By default, the auto-placement algorithm is "sparse",
-			permanently skipping spaces that it can't fill with the current <a>grid item</a>.)
 
 			Note: This may cause items to appear out-of-order.
 
 		<dt><dfn>stack</dfn>
 		<dd>
 			The auto-placement algorithm is run with a single hypothetical 1×1 grid item,
-			as if ''grid-auto-flow: row'' or ''grid-auto-flow: column'' were specified,
-			depending on whether ''row'' or ''column'' is specified alongside it,
-			respectively.
-			If neither ''row'' nor ''column'' are specified,
-			it defaults to running the algorithm as if ''grid-auto-flow: row'' were specified.
-
-			Wherever the hypothetical item would be placed,
-			all auto-placed items are placed there,
-			stacked atop one another.
+			and all of the auto-placed items are placed wherever that hypothetical item ends up.
 			(This happens even if the auto-placed item is greater than 1×1,
 			even if doing so would cause it to overlap explicitly-placed <a>grid items</a>.)
-
-			Issue: Need to clarify what "placed there" means.
-			(See the <a>auto-placement algorithm</a> for details.)
 	</dl>
 
 	Note: A future level of this module is expected to add a value that flows auto-positioned items together into a single “default” cell.