[css-text-decor-4] Replace text-decoration-skip-edges with text-decoration-trim. #4557

Author: fantasai

css-text-decor-4/Overview.bs

@@ -843,6 +843,74 @@ Text Decoration Line Uniformity</h3>
 		-->
 	</div>
 
+
+<h4 id="text-decoration-skip-inset-property">
+Text Decoration Line Trimming and Extension: the 'text-decoration-trim' property</h4>
+
+	<pre class="propdef">
+	Name: text-decoration-trim
+	Value: <<length>>{1,2} | auto
+	Initial: 0
+	Applies to: all elements
+	Inherited: no
+	Percentages: N/A
+	Computed value: specified keyword or absolute length
+	Animation type: by computed value
+	</pre>
+
+	This property adjusts the start and end points of line decorations,
+	allowing the author to shorten, lengthen, or shift the decoration
+	with respect to the text.
+	It controls all text decoration lines drawn by this [=decorating box=],
+	but not any text decoration lines drawn by its ancestors.
+	If two component values are given,
+	the first applies to the [=start=] and the second to the [=end=].
+	Values have the following meanings:
+
+	<dl dfn-type=value dfn-for=text-decoration-skip-inset>
+		<dt><dfn><<length>></dfn></dt>
+		<dd>
+			Inset (positive) or outset (negative)
+			the start/end of the affected line decorations.
+
+			<div class="example">
+				<p>The following example offsets an extra thick underline
+				1em endwards with respect to the text
+				<pre>
+					h1 {
+						text-decoration: underline 0.3em rgba(36,148,187,0.25);
+						text-decoration-trim: 1em -1em;
+					}
+				</pre>
+			</div>
+
+		<dt><dfn>auto</dfn></dt>
+		<dd>
+			The UA chooses a trim amount that ensures that
+			if two identical underlined elements appear side-by-side
+			they do not appear to have a single underline.
+			(This is important in Chinese, where underlining is a form of punctuation.)
+
+			<div class="figure">
+				<p><img title="text-decoration-skip-inset: auto"
+				        alt="An underline below a series of Chinese characters has a gap between two adjacent underlining elements."
+				        src="images/decoration-skip-inset.png">
+				<p class="caption">''text-decoration-skip-inset: auto'' for <code>&lt;u>石井&lt;/u>&lt;u>艾俐俐&lt;/u></code>
+</p>
+			</div>
+	</dl>
+
+	Text decoration trimming is subject to 'box-decoration-break':
+	* for ''box-decoration-break/slice'' (the default)
+		trimming is only applied to the [=start=] edge of the first fragment
+		and the [=end=] edge of the last fragment,
+		and may accumulate to other fragments if the amount of the trim
+		is more than the length of the fragment.
+		Percentages are relative to the total length of the [=decorating box=].
+	* for ''box-decoration-break/clone''
+		trimming is applied to each fragment independently.
+		<!-- and percentages are relative to the length of that fragment individually -->
+
 <h3 id="text-decoration-skipping">
 Text Decoration Line Continuity: the 'text-decoration-skip' shorthand and its sub-properties</h3>
 
@@ -971,57 +1039,6 @@ Skipping Spaces: the 'text-decoration-skip-box' property</h4>
 			a <a>decorating box</a> never draws over its own box decoration.
 	</dl>
 
-<h4 id="text-decoration-skip-inset-property">
-Inset Edges: the 'text-decoration-skip-inset' property</h4>
-
-	<pre class="propdef">
-	Name: text-decoration-skip-inset
-	Value: none | auto
-	Initial: none
-	Applies to: all elements
-	Inherited: yes
-	Percentages: N/A
-	Computed value: specified keyword(s)
-	Animation type: discrete
-	</pre>
-
-	Issue: The CSSWG resolved to split 'text-decoration-skip' into sub-properties,
-	but this value set has not yet been vetted by the CSSWG.
-
-	This property specifies what parts of the element's box area
-	any text decoration affecting the element must skip over.
-	It controls all text decoration lines drawn by the element,
-	but not any text decoration lines drawn by its ancestors.
-	Values have the following meanings:</p>
-
-	<dl dfn-type=value dfn-for=text-decoration-skip-inset>
-		<dt><dfn>none</dfn></dt>
-		<dd>
-			Skip nothing: text-decoration is drawn from box edge to box edge.
-
-		<dt><dfn>auto</dfn></dt>
-		<dd>
-			The UA must place the start and end of the line inwards slightly
-			from the content edge of the <a>decorating box</a> so that,
-			e.g. two underlined elements side-by-side do not appear to have a single underline.
-			The size of the inset is up to the user agent
-			(e.g. half a line thickness)
-			but must not be zero.
-			(This is important in Chinese, where underlining is a form of punctuation.)
-
-			<div class="figure">
-				<p><img title="text-decoration-skip-inset: auto"
-				        alt="An underline below a series of Chinese characters has a gap between two adjacent underlining elements."
-				        src="images/decoration-skip-inset.png">
-				<p class="caption">''text-decoration-skip-inset: auto'' for <code>&lt;u>石井&lt;/u>&lt;u>艾俐俐&lt;/u></code>
-</p>
-			</div>
-	</dl>
-
-	ISSUE: This might want to be a standalone property rather than part of the 'text-decoration-skip' set.
-	See also <a href="https://github.com/w3c/csswg-drafts/issues/4557">Issue 4557</a>,
-	about controlling the line length explicitly.
-
 <h4 id="text-decoration-skip-spaces-property">
 Skipping Spaces: the 'text-decoration-skip-spaces' property</h4>