[css-align] Rearrange the sections for better parallel structure. No normative changes.

Author: tabatkins

css-align/Overview.bs

@@ -48,6 +48,8 @@ table.align-details { width: 100%; }
 <h2 id="intro">
 Introduction</h2>
 
+	<em>This section is not normative.</em>
+
 	CSS Levels 1 and 2 allowed for the alignment of text via 'text-align'
 	and the alignment of blocks by balancing ''margin/auto'' margins.
 	However, except in table cells,
@@ -64,8 +66,6 @@ Introduction</h2>
 	If implementors or anyone else notices a discrepency,
 	please report this to the CSSWG as an error.
 
-	<em>This section (above) is not normative.</em>
-
 <h3 id="placement">
 Module interactions</h3>
 
@@ -192,10 +192,9 @@ Overview of Alignment Properties</h2>
 			<td><a>flex containers</a> and <a>grid containers</a>
 	</table>
 
-	Note: The '*-items' properties don't actually <em>do</em> anything
-	except through their effect on the initial value
-	(''align-self/auto'') of the 'align-self' and 'justify-self' properties
-	of the element’s children.
+	Note: The '*-items' properties don't affect the element itself.
+	When set on a container,
+	they specify the interpretation of any ''*-self: auto'' used on children of the container element.
 
 <h2 id='terms'>
 Alignment Terminology</h2>
@@ -219,7 +218,8 @@ Alignment Terminology</h2>
 		<dd>
 			The <a>alignment container</a> is the rectangle that the <a>alignment subject</a> is aligned within.
 			This is defined by the layout mode,
-			but is usually the <a>alignment subject</a>’s containing block.
+			but is usually the <a>alignment subject</a>’s containing block,
+			and assumes the writing mode of the box establishing the containing block.
 
 		<dt><dfn export>fallback alignment</dfn>
 		<dd>
@@ -615,7 +615,10 @@ Overflow Alignment: the ''safe'' and ''unsafe'' keywords</h3>
 -->
 
 <h2 id='content-distribution'>
-Content Distribution: the 'align-content' and 'justify-content' properties and 'place-content' shorthand</h2>
+Content Distribution: aligning a box's contents within itself</h2>
+
+<h3 id='align-justify-content'>
+The 'justify-content' And 'align-content' Properties</h3>
 
 	The <dfn export>content distribution properties</dfn> 'align-content' and 'justify-content'
 	(and their 'place-content' shorthand)
@@ -652,28 +655,6 @@ Content Distribution: the 'align-content' and 'justify-content' properties and '
 	Aligns the contents of the box as a whole.
 	Values other than <dfn value for="justify-content, align-content">normal</dfn> are defined in [[#alignment-values]], above.
 
-	<pre class="propdef">
-	Name: place-content
-	Value: <<'align-content'>> <<'justify-content'>>?
-	Initial: normal
-	Applies to: block containers, flex containers, and grid containers
-	Inherited: no
-	Percentages: n/a
-	Media: visual
-	Computed value: see individual properties
-	Animatable: no
-	</pre>
-
-	This <a>shorthand property</a> sets both the 'align-content' and 'justify-content' properties in one declaration.
-	The first value is assigned to 'align-content'.
-	The second value is assigned to 'justify-content';
-	if omitted, it is copied from the first value,
-	unless that value is a <<baseline-position>>
-	in which case it is defaulted to ''start''.
-
-Details per Layout Mode {#distribution-details}
------------------------------------------------
-
 ### Block Containers ### {#distribution-block}
 
 	<table class="data align-details">
@@ -811,6 +792,48 @@ Details per Layout Mode {#distribution-details}
 
 	See [[!CSS-GRID-1]] for details.
 
+<h3 id='place-content'>
+Content Distribution Shorthand: the 'place-content' property</h3>
+
+	<pre class="propdef">
+	Name: place-content
+	Value: <<'align-content'>> <<'justify-content'>>?
+	Initial: normal
+	Applies to: block containers, flex containers, and grid containers
+	Inherited: no
+	Percentages: n/a
+	Media: visual
+	Computed value: see individual properties
+	Animatable: no
+	</pre>
+
+	This <a>shorthand property</a> sets both the 'align-content' and 'justify-content' properties in one declaration.
+	The first value is assigned to 'align-content'.
+	The second value is assigned to 'justify-content';
+	if omitted, it is copied from the first value,
+	unless that value is a <<baseline-position>>
+	in which case it is defaulted to ''start''.
+
+<h3 id="overflow-scroll-position">
+Overflow and Scroll Positions</h3>
+
+	The <a>content distribution properties</a> also affect the initial scroll position,
+	setting it to display the appropriate portion of the scrollable area.
+	In other words,
+	the <a>scrollable overflow region</a> is aligned relative to the viewport
+	as specified by the <a>content distribution properties</a>.
+	Additionally, so that the content remains in the <a>scrollable overflow region</a> in order to be scrollable,
+	the ''overflow/scroll'' and ''overflow/auto'' values of 'overflow'
+	trigger ''safe'' content alignment always.
+
+	<div class='example'>
+		For example,
+		if a scrollable flex container is set to ''justify-content: flex-end''
+		(or ''justify-content: flex-start'' with ''flex-flow: row-reverse''),
+		it will be initially displayed scrolled all the way to the main-end edge of the scrollable area,
+		and its content will appear to overflow its main-start edge.
+	</div>
+
 <h3 id="baseline-align-content">
 Baseline Content-Alignment</h3>
 
@@ -865,26 +888,6 @@ Baseline Content-Alignment</h3>
 	See [[#align-by-baseline]] for exact details.
 	This can increase the intrinsic size of the box.
 
-<h3 id="overflow-scroll-position">
-Overflow and Scroll Positions</h3>
-
-	Content that overflows a <a>scroll container</a>
-	is aligned exactly like content in a non-scrollable container.
-	However, to prevent content from being shifted into the unscrollable region,
-	when the <a>content distribution properties</a> are set on a <a>scroll container</a>,
-	the zero coordinate of its <a>scrollable overflow region</a>
-	(that is, the point beyond which content is unreachable)
-	is set to the top left corner of the <a>alignment subject</a>,
-	effectively changing the <a>initial scroll position</a>.
-
-	<div class='example'>
-		For example,
-		if a scrollable flex container is set to ''justify-content: flex-end''
-		(or ''justify-content: flex-start'' with ''flex-flow: row-reverse''),
-		it will be initially displayed scrolled all the way to the main-end edge of the scrollable area,
-		and its content will appear to overflow its main-start edge.
-	</div>
-
 <!--
                    ██████  ████████ ██       ████████
  ██   ██          ██    ██ ██       ██       ██
@@ -1415,7 +1418,7 @@ Inline/Main-Axis Alignment: the 'justify-items' property</h3>
 	Inherited: no
 	Percentages: n/a
 	Media: visual
-	Computed value: specified value, except for ''justify-items/legacy'' (see prose)
+	Computed value: specified value, except for ''justify-items/auto'' (see prose)
 	Animatable: no
 	</pre>
 
@@ -1610,14 +1613,19 @@ Determining the Baselines of a Box</h2>
 		whichever is orthogonal to the box’s own 'writing-mode'.
 		<!-- This pairing is chosen because the most likely case for this situation is CJK. -->
 
+	Issue: Maybe these things are wrong?
+	CSS 2.1 is really weird about baseline alignment.
+
 	For the purposes of finding the baselines of a box,
 	it and all its in-flow descendants with a scrolling mechanism (see the 'overflow' property)
-	must be considered as if scrolled to their initial scroll position.
+	must be considered as if scrolled to their origin.
 	Furthermore, if, in the case of a box with non-''visible'' overflow,
 	the resulting position of a first (last) baseline
 	is past a box's end (start) border edge,
 	its position is clamped to that border edge.
 
+	ISSUE: This reflects the latest CSS2.1 errata, however see also discussion of an <a href="https://github.com/w3c/csswg-drafts/issues/766">alternate solution</a> that was previously drafted here.
+
 <h3 id='baseline-terms'>
 Baseline Alignment Grouping</h3>