[css-inline-3] Clarifications to baseline alignment intro

Author: fantasai

css-inline-3/Overview.bs

@@ -524,49 +524,63 @@ Baselines of Glyphs and Boxes</h3>
 <h2 id="alignment">
 Baseline Alignment</h2>
 
-	While CSS [=formatting contexts=] usually position content
+	While most CSS [=formatting contexts=] position content
 	by aligning boxes with respect to their container’s edges,
 	[=inline layout=] positions boxes in the [=block axis=]
 	by aligning them with respect to each other
 	using their [=baselines=].
 
 	More specifically,
+	(unless using a [=line-relative shift value=])
 	each glyph or [=inline-level box=]
-	is typically aligned in the [=block axis=]
+	is aligned in the [=block axis=]
 	by positioning its [=alignment baseline=]
-	to match the corresponding [=baseline=] of its parent,
-	and then potentially shifted from that position
+	to match the <em>corresponding</em> [=baseline=] of its parent
+	(which is its [=alignment context=]),
+	and then is potentially shifted from that position
 	according to its [=post-alignment shift=].
-	The [=alignment baseline=] of the box is selected
-	by the 'alignment-baseline' longhand of 'vertical-align';
-	this defaults to the parent’s' [=dominant baseline=].
+
+	Note: Baseline alignment always matches corresponding baselines:
+	alphabetic to alphabetic, hanging to hanging, mathematical to mathematical, etc.
+
+	When aligning a [=box=], the [=alignment baseline=] is chosen
+	according to its 'alignment-baseline' and 'baseline-source' values
+	(see shorthand 'vertical-align'),
+	and defaults to matching the parent’s 'dominant-baseline'.
+	For a glyph, the [=alignment baseline=] is always determined
+	by the parent’s [=dominant baseline=].
 
 	<div class="example">
 		<p>Given following sample markup:
-		<pre>&lt;p&gt;&lt;span class="outer"&gt;Ap &lt;span class="inner"&gt;ਜੀ&lt;/span&gt;&lt;/span&gt;&lt;/p&gt;</pre>
+		<pre highlight=html>&lt;p&gt;&lt;span class="outer"&gt;Ap &lt;span class="inner"&gt;ਜੀ&lt;/span&gt;&lt;/span&gt;&lt;/p&gt;</pre>
+
 		<p>And the following style rule:
-		<pre>span.inner { font-size: 75%; }</pre>
+		<pre highlight=css>.inner { font-size: 75%; }</pre>
+
 		<p>The [=baseline sets=] of the parent (<code>.outer</code>) and the child (<code>.inner</code>)
 		will not match up due to the font size difference.
-		Since the [=dominant baseline=] is the [=alphabetic baseline=]
-		(the default in horizontal [=typographic modes=]),
-		the child box is aligned to its parent
+		The child box is aligned to its parent
 		by matching up their [=alphabetic baselines=].
+
 		<figure>
 			<img alt="In this example, the distance between each baseline in the baseline set
 			          is compacted 75% in the span with a 75% font size.
 			          Their alphabetic baselines, however, line up."
 			     src="images/baseline-align-sizes.gif">
 		</figure>
-	</div>
 
-	<div class="example">
-		<p>If we assign ''vertical-align: super''
+
+		<p>The [=alphabetic baseline=] is used here
+		because by default a box’s [=alignment baseline=] matches
+		the [=dominant baseline=] of its parent,
+		and in horizontal [=typographic mode=],
+		the [=dominant baseline=] itself defaults to the [=alphabetic baseline=].
+
+		<p>If we add ''vertical-align: super''
 		to the <code>.inner</code> element from the example above,
 		the same rules are used to align the <code>.inner</code> child to its parent;
-		the only difference is in addition to the baseline alignment,
+		but in addition to the baseline alignment,
 		the child is shifted to the superscript position.
-		<pre>span.inner { vertical-align: super; font-size: .75em; }</pre>
 		<figure>
 			<p><img alt="In this example, the resulting alignment is equivalent to
 			             shifting the parent baseline table upwards by its superscript offset,
@@ -826,10 +840,10 @@ Post-Alignment Shift: the 'baseline-shift' longhand</h4>
 	</pre>
 
 	This property specifies the box’s <dfn>post-alignment shift</dfn>.
-	The <dfn>baseline-relative values</dfn>
+	The <dfn local-lt="baseline-relative values">baseline-relative shift values</dfn>
 	<<length-percentage>>, ''baseline-shift/sub'', ''baseline-shift/super''
 	shift the box relative to its baseline-aligned position,
-	whereas the <dfn>line-relative values</dfn>
+	whereas the <dfn local-lt="line-relative values">line-relative shift values</dfn>
 	''baseline-shift/top'', ''baseline-shift/center'', and ''baseline-shift/bottom''
 	shift the [=inline box=] and its contents
 	relative to the bounds of its [=line box=].
@@ -884,12 +898,12 @@ Post-Alignment Shift: the 'baseline-shift' longhand</h4>
 	the [=layout bounds=] of that box
 	and the [=aligned subtrees=] of all child [=inline boxes=]
 	whose computed 'alignment-baseline' value
-	is not itself a [=line-relative value=].
+	is not itself a [=line-relative shift value=].
 	The [=line-over=] edge of the [=aligned subtree=]
 	is the highest [=over=] edge of the [=layout bounds=] in the subtree,
 	and the [=line-under=] edge is analogously the lowest.
 
-	ISSUE: The [=line-relative values=] don't fit perfectly
+	ISSUE: The [=line-relative shift values=] don't fit perfectly
 	in the dichotomy between 'alignment-baseline' and 'baseline-shift'.
 	There's <a href="https://github.com/w3c/csswg-drafts/issues/5180">decent</a> <a href="https://github.com/w3c/csswg-drafts/issues/5234">arguments</a>
 	for either option.
@@ -2965,7 +2979,7 @@ Changes</h2>
 			(<a href="https://github.com/w3c/csswg-drafts/issues/5168">Issue 5168</a>)
 
 		<li>
-			Shifted the [=line-relative values=] of 'vertical-align'
+			Shifted the [=line-relative shift values=] of 'vertical-align'
 			from the 'alignment-baseline' longhand to the 'baseline-shift' longhand.
 			(<a href="https://github.com/w3c/csswg-drafts/issues/5180">Issue 5180</a>)