[css-text-decor-4] Update text-underline-position/text-underline-offset per #3118 (comment)

Author: fantasai

css-text-decor-4/Overview.bs

@@ -467,17 +467,16 @@ Text Underline Position: the 'text-underline-position' property</h3>
 
 	<pre class="propdef">
 	Name: text-underline-position
-	Value: auto | [ under || [ left | right ] ]
+	Value: auto | [ from-font | under ] || [ left | right ]
 	Initial: auto
 	Inherited: yes
 	Computed value: specified keyword(s)
 	Animation type: discrete
 	</pre>
 
-	This property sets the position of an underline with respect to the element.
-	(It does not affect underlines specified by ancestor elements.)
-	The exact position of the underline can be further adjusted
-	with 'text-underline-position'.
+	This property sets the position of an underline with respect to the element,
+	and sets its [=zero position=] for further adjustment by 'text-underline-offset'.
+	It does not affect underlines specified by ancestor elements.
 
 	<div class="example">
 		The following example styles modern Chinese, Japanese, and Korean
@@ -519,6 +518,13 @@ Text Underline Position: the 'text-underline-position' property</h3>
 				<p class="caption">A typical “alphabetic” underline is positioned just below the alphabetic baseline
 			</div>
 
+		<dt><dfn>from-font</dfn>
+		<dd>
+			If the <a>first available font</a> has
+			metrics indicating a preferred underline offset,
+			use that offset,
+			otherwise behaves as ''text-underline-offset/auto''.
+
 		<dt><dfn id="underline-under">under</dfn>
 		<dd>
 			The underline is positioned <i>under</i> the element's text content.
@@ -596,7 +602,7 @@ Text Underline Offset: the 'text-underline-offset' property</h3>
 
 	<pre class="propdef">
 	Name: text-underline-offset
-	Value: auto | from-font | <<length>>
+	Value: auto | <<length>>
 	Initial: auto
 	Applies to: all elements
 	Inherited: yes
@@ -606,29 +612,28 @@ Text Underline Offset: the 'text-underline-offset' property</h3>
 	</pre>
 
 	This property, which is <em>not</em> a <a>sub-property</a> of the 'text-decoration' shorthand,
-	sets the offset of underlines from their initial position.
+	sets the offset of underlines from their [=zero position=].
+	Positive offsets represent distances outward from the text;
+	negative offsets inward.
 
 	Values have the following meanings:
 
 	<dl dfn-for=text-underline-offset dfn-type=value>
 		<dt><dfn>auto</dfn>
 		<dd>
-			The UA chooses an appropriate offset for underlines.
+			<p>The UA chooses an appropriate offset for underlines.
 
-		<dt><dfn>from-font</dfn>
-		<dd>
-			If the <a>first available font</a> has
-			metrics indicating a preferred underline offset,
-			use that offset,
-			otherwise behaves as ''text-underline-offset/auto''.
+			However, this offset must be zero
+			if ''text-underline-position/from-font'' was specified
+			and the UA was able to extract an appropriate metric to use
+			from the font.
 
 		<dt><dfn><<length>>
 		<dd>
-			Specifies the offset of underlines as a length.
-			This replaces any information in the font
-			or derived from glyph shapes / character ranges.
-			Authors are strongly encouraged to use ''em'' units
-			so that the offset scales with the font.
+			<p>Specifies the offset of underlines as a fixed length.
+
+			Note: A length will inherit as a fixed value,
+			and will not scale with the font.
 	</dl>
 
 	When the value of the 'text-decoration-line' property is either
@@ -638,40 +643,45 @@ Text Underline Offset: the 'text-underline-offset' property</h3>
 <h4 id="line-offset-zero">
 Underline Offset Origin (Zero Position)</h4>
 
-	The initial position of the underline depends on the value of 'text-underline-position'
+	The <dfn lt="underline zero position" local-lt="zero position">zero position</dfn> of the underline
+	depends on the value of 'text-underline-position'
 	as detailed below.
 
 	<table class="data">
 		<caption>Interaction of 'text-underline-position' and 'text-underline-offset'
 		<thead>
 			<tr>
 				<th>'text-underline-position'
-				<th>Initial Position
+				<th>Zero Position
 				<th>Positive Direction
 		<tbody>
 			<tr>
 				<td>''text-underline-position/auto''
 				<td>alphabetic baseline
-				<td><a>over</a>
+				<td><a>under</a>
+			<tr>
+				<td>''text-underline-position/from-font''
+				<td>position specified by the font metrics, falling back to alphabetic baseline
+				<td><a>under</a>
 			<tr>
 				<td>''text-underline-position/under''
 				<td>text-under edge
-				<td><a>over</a>
+				<td><a>under</a>
 			<tr>
-				<td>''text-underline-position/over''
-				<td>text-over edge
+				<td>''text-underline-position/left''
+				<td>text-under (left) edge
 				<td><a>under</a>
+			<tr>
+				<td>''text-underline-position/right''
+				<td>text-over (right) edge
+				<td><a>over</a>
 	</table>
 
-	<ul>
-		<li>The line is aligned to the outside of the specified position.
-		    (Below for ''text-underline-position/under''/''text-underline-position/auto'' positions,
-		    above for ''text-underline-position/over''.)
-		<li>Positive lengths represent inward distances; negative lengths outward.
-		<li>Automatic adjustments made to accommodate descendant content are maintained;
-			the 'text-underline-offset' is in addition to those.
-			<span class="issue">Should this be removed?</span>
-	</ul>
+	The underline is aligned to the outside of the specified position
+	(extending its thickness in the positive direction only).
+
+	Any automatic adjustments made to accommodate descendant content are maintained;
+	the 'text-underline-offset' is in addition to those.
 
 <h4 id="line-auto-offset">
 Using Font Metrics for Automatic Positioning</h4>
@@ -680,7 +690,9 @@ Using Font Metrics for Automatic Positioning</h4>
 	about the appropriate position of a line decoration.
 	The UA should use such font-based information
 	in its choice of ''text-underline-offset/auto'' offset
-	wherever appropriate.
+	wherever appropriate,
+	and must use such information
+	when ''text-underline-position/from-font'' is specified for 'text-underline-position'.
 
 	Note: Typically, OpenType font metrics give the position
 	of an ''text-underline-position/alphabetic'' underline;