[css-overflow-3] Reorganize sections

Better grouping for better readability

Author: frivoal

css-overflow-3/Overview.bs

@@ -499,8 +499,11 @@ as the Flow-Relative box model properties defined in [[css-logical-1#box]].
   'overflow-x' and 'overflow-y' properties.
   The mapping depends on the element's 'writing-mode'.
 
-<h2 id="text-overflow" caniuse="text-overflow">
-    Overflow Ellipsis: the 'text-overflow' property</h2>
+<h2 id="auto-ellipsis">
+Automatic Ellipses</h3>
+
+<h3 id="text-overflow" caniuse="text-overflow">
+    Overflow Ellipsis: the 'text-overflow' property</h3>
 
 <pre class="propdef">
 Name: text-overflow
@@ -555,7 +558,7 @@ on a line
 must be clipped rather than ellipsed.
 
 <div class=example>
-<h3 id="bidi-ellipsis" class="no-num no-toc">Bidi ellipsis examples</h3>
+<h4 id="bidi-ellipsis" class="no-num no-toc">Bidi ellipsis examples</h4>
 These examples demonstrate which characters get hidden
 to make room for the ellipsis in a bidi situation:
 those visually at the end edge of the line.
@@ -583,7 +586,7 @@ Sample HTML fragments, renderings, and your browser:
 
 </div>
 
-<h3 id="ellipsing-details" class="no-num no-toc">ellipsing details</h3>
+<h4 id="ellipsing-details" class="no-num no-toc">ellipsing details</h4>
 <ul>
 <li>
 Ellipsing only affects rendering and must not affect layout
@@ -602,7 +605,7 @@ then clip the rendering of the ellipsis itself
 would have otherwise been clipped with the ''text-overflow:clip'' value).
 </ul>
 
-<h3 id="ellipsis-interaction" class="no-num no-toc">user interaction with ellipsis</h3>
+<h4 id="ellipsis-interaction" class="no-num no-toc">user interaction with ellipsis</h4>
 <ul>
 <li>When the user is interacting with content
 (e.g. editing, selecting, scrolling),
@@ -616,7 +619,7 @@ Behavior of partially-selected ellipsed text is up to the UA.
 </ul>
 
 <div class="example"><p style="display:none">Example(s):
-<h3 id="text-overflow-examples" class="no-num no-toc">text-overflow examples</h3>
+<h4 id="text-overflow-examples" class="no-num no-toc">text-overflow examples</h4>
 
 These examples demonstrate setting the text-overflow of a block container element
 that has text which overflows its dimensions:
@@ -716,7 +719,7 @@ to represent that clipped content.
 
 <!-- insert RTL example diagram here to illustrate note. -->
 
-<h3 id="ellipsis-scrolling" class="no-num no-toc">ellipsis interaction with scrolling interfaces</h3>
+<h4 id="ellipsis-scrolling" class="no-num no-toc">ellipsis interaction with scrolling interfaces</h4>
 
 This section applies to elements with text-overflow other than ''text-overflow:clip''
 (non-clip text-overflow)
@@ -779,8 +782,118 @@ having it overlap other text by default.
 
 While the content is being scrolled, implementations may adjust their rendering of ellipses (e.g. align to the box edge rather than line edge).
 
-<h2 id=line-clamp>
-Limiting Visible Lines: the 'line-clamp' shorthand property</h2>
+<h3 id="block-ellipsis">
+Indicating Block-Axis Overflow: the 'block-overflow' property</h3>
+
+	<pre class=propdef>
+		Name: block-overflow
+		Value: clip | ellipsis | <<string>>
+		Initial: clip
+		Applies to: [=block containers=]
+		Inherited: yes
+		Percentages: N/A
+		Computed value: specified value
+	</pre>
+
+	This property allows inserting content into the last line box
+	before a (forced <em>or</em> unforced) <a>region break</a>
+	to indicate the continuity of truncated/interrupted content.
+	It only affects line boxes contained directly by the <a>block container</a> itself,
+	but as it inherits, will have an effect on descendants’ line boxes unless overridden.
+	If the box contains no line box immediately preceding a <a>region break</a>,
+	then this property has no effect.
+
+	Note: See [[#fragmentation]] for a way to generate boxes with such a [=region break=].
+
+	ISSUE: Should this apply to other types of fragmentation breaks (e.g. pages, columns)?
+
+	The inserted content is called the <dfn>block overflow ellipsis</dfn>.
+	Values have the following meanings:
+
+	<dl dfn-for="block-overflow" dfn-type=value>
+		<dt><dfn>clip</dfn>
+		<dd>
+			The rendering is unaffected.
+
+		<dt><dfn>ellipsis</dfn>
+		<dd>
+			Render an ellipsis character (U+2026)--
+			or a more typographically-appropriate equivalent--
+			as the <a>block overflow ellipsis</a>
+			at the end of the affected line box.
+			UAs should use the conventions of the
+			<a>content language</a>,
+			writing system, and
+			<a>writing mode</a>
+			to determine the most appropriate ellipsis string.
+
+		<dt><dfn><<string>></dfn>
+		<dd>
+			Render the specified string
+			as the <a>block overflow ellipsis</a>
+			at the end of the affected line box.
+			The UA may truncate this string if it is absurdly long.
+	</dl>
+
+	When 'block-overflow' is not ''block-overflow/clip'',
+	the <a>block overflow ellipsis</a> string
+	is wrapped in an anonymous inline
+	and placed at the end of the line box
+	as a direct child of the <a>block container</a>’s <a>root inline box</a>,
+	reducing the space in the line box
+	available to the other contents of the line.
+	This inline is assigned ''unicode-bidi: plaintext''
+	and is placed in the line box after the last
+	<a>soft wrap opportunity</a> [[!CSS-TEXT-3]]
+	that would still allow the entire <a>block overflow ellipsis</a> to fit on the line.
+	(This can result in the entire contents of the line box being replaced.)
+	For this purpose, <a>soft wrap opportunities</a> added by 'overflow-wrap' are ignored.
+	Text <a href="https://www.w3.org/TR/css-text-3/#justification">alignment and justification</a>
+	occurs after placement,
+	and measures the inserted <a>block overflow ellipsis</a>
+	together with the rest of the line’s content.
+
+	If there is no next <a>fragmentation container</a>
+	and thus the remainder of the content after the break would be discarded,
+	then the UA may visually replace the contents of the line,
+	as it does for 'text-overflow'.
+	If, however, there is a next <a>fragmentation container</a>
+	that would receive subsequent content,
+	then the content replaced by the <a>block overflow ellipsis</a>
+	must be pushed to the next <a>fragmentation container</a>
+	and the <a>block overflow ellipsis</a> inserted and laid out
+	exactly as if it were part of the <a>in-flow</a> contents of the line.
+	This can result in changes to layout within or impacted by the line.
+	The means of breaking any resulting cycles is up to the UA.
+
+	If the <a>block overflow ellipsis</a>
+	is too long to fit in the line,
+	the result is undefined.
+	(The UA may, for example, treat the <a>block overflow ellipsis</a> as an unbreakable string,
+	or it may lay out the string across more than one line,
+	replacing content in earlier lines as well.)
+
+	The <a>block overflow ellipsis</a> does not capture events:
+	pointer events are dispatched to whatever is underneath
+	or otherwise visually replaced by it.
+
+	It also has no effect on the intrinsic size of the box:
+	its <a lt="min-content size">min-content</a> and <a lt="max-content size">max-content</a> sizes
+	are calculated exactly as if 'block-overflow' were ''block-overflow/clip''.
+
+	Note: Future specifications may extend this feature,
+	for example by providing an ''::ellipsis'' pseudo-element
+	to style the text,
+	or by allowing the selection of a child element of the block
+	to use as either an inline-level or block-level indicator
+	(in which case, it can capture events).
+
+
+<h2 id=fragmentation>
+Fragmenting Overflow</h2>
+
+<h3 id=line-clamp>
+Limiting Visible Lines: the 'line-clamp' shorthand property</h3>
 
 	<pre class=propdef>
 		Name: line-clamp
@@ -796,6 +909,14 @@ Limiting Visible Lines: the 'line-clamp' shorthand property</h2>
 	The 'line-clamp' property is a <a>shorthand</a>
 	for the 'max-lines', 'block-overflow', and 'continue' properties.
 
+	Issue: For the time being,
+	experiemental implementations are encouraged
+	to follow the full behavior defined by this shorthand and its longhands,
+	but to only expose the shorthand to authors.
+	This is in order to facilitate further tweaking,
+	and in particular potential renaming,
+	of the longhand properties and their values.
+
 	It allows limiting the contents of a block container
 	to the specified number of lines;
 	remaining content is fragmented away
@@ -822,14 +943,6 @@ Limiting Visible Lines: the 'line-clamp' shorthand property</h2>
 	See the corresponding longhand properties for details
 	about how this mechanism operates.
 
-	Issue: For the time being,
-	experiemental implementations are encouraged
-	to follow the full behavior defined by this shorthand and its longhands,
-	but to only expose the shorthand to authors.
-	This is in order to facilitate further tweaking,
-	and in particular potential renaming,
-	of the longhand properties and their values.
-
 	<div class="example">
 		In this example, the lead paragraph of each article
 		is listed in a shortened menu,
@@ -875,8 +988,8 @@ Limiting Visible Lines: the 'line-clamp' shorthand property</h2>
 	Something more complicated might be needed.
 
 
-<h2 id="max-lines">
-Forcing a break after a set number of lines: the 'max-lines' property</h2>
+<h3 id="max-lines">
+Forcing a break after a set number of lines: the 'max-lines' property</h3>
 
 	<pre class=propdef>
 		Name: max-lines
@@ -931,8 +1044,8 @@ Forcing a break after a set number of lines: the 'max-lines' property</h2>
 		* classify these fragmentation containers as "category3" (i.e. not pages nor multicol) for the purpose of forced breaks.
 	</div>
 
-<h2 id="fragmentation">
-Fragmentation of overflow: the 'continue' property</h2>
+<h3 id="continue">
+Fragmentation of overflow: the 'continue' property</h3>
 
 	<pre class=propdef>
 		Name: continue
@@ -1056,111 +1169,6 @@ Once it is sufficiently stable in this specification,
 	</figure>
 	</div>
 
-<h2 id="block-ellipsis">
-Indicating Block-Axis Overflow: the 'block-overflow' property</h2>
-
-	<pre class=propdef>
-		Name: block-overflow
-		Value: clip | ellipsis | <<string>>
-		Initial: clip
-		Applies to: [=block containers=]
-		Inherited: yes
-		Percentages: N/A
-		Computed value: specified value
-	</pre>
-
-	This property allows inserting content into the last line box
-	before a (forced <em>or</em> unforced) <a>region break</a>
-	to indicate the continuity of truncated/interrupted content.
-	It only affects line boxes contained directly by the <a>block container</a> itself,
-	but as it inherits, will have an effect on descendants’ line boxes unless overridden.
-	If the box contains no line box immediately preceding a <a>region break</a>,
-	then this property has no effect.
-
-	ISSUE: Should this apply to other types of fragmentation breaks (e.g. pages, columns)?
-
-	The inserted content is called the <dfn>block overflow ellipsis</dfn>.
-	Values have the following meanings:
-
-	<dl dfn-for="block-overflow" dfn-type=value>
-		<dt><dfn>clip</dfn>
-		<dd>
-			The rendering is unaffected.
-
-		<dt><dfn>ellipsis</dfn>
-		<dd>
-			Render an ellipsis character (U+2026)--
-			or a more typographically-appropriate equivalent--
-			as the <a>block overflow ellipsis</a>
-			at the end of the affected line box.
-			UAs should use the conventions of the
-			<a>content language</a>,
-			writing system, and
-			<a>writing mode</a>
-			to determine the most appropriate ellipsis string.
-
-		<dt><dfn><<string>></dfn>
-		<dd>
-			Render the specified string
-			as the <a>block overflow ellipsis</a>
-			at the end of the affected line box.
-			The UA may truncate this string if it is absurdly long.
-	</dl>
-
-	When 'block-overflow' is not ''block-overflow/clip'',
-	the <a>block overflow ellipsis</a> string
-	is wrapped in an anonymous inline
-	and placed at the end of the line box
-	as a direct child of the <a>block container</a>’s <a>root inline box</a>,
-	reducing the space in the line box
-	available to the other contents of the line.
-	This inline is assigned ''unicode-bidi: plaintext''
-	and is placed in the line box after the last
-	<a>soft wrap opportunity</a> [[!CSS-TEXT-3]]
-	that would still allow the entire <a>block overflow ellipsis</a> to fit on the line.
-	(This can result in the entire contents of the line box being replaced.)
-	For this purpose, <a>soft wrap opportunities</a> added by 'overflow-wrap' are ignored.
-	Text <a href="https://www.w3.org/TR/css-text-3/#justification">alignment and justification</a>
-	occurs after placement,
-	and measures the inserted <a>block overflow ellipsis</a>
-	together with the rest of the line’s content.
-
-	If there is no next <a>fragmentation container</a>
-	and thus the remainder of the content after the break would be discarded,
-	then the UA may visually replace the contents of the line,
-	as it does for 'text-overflow'.
-	If, however, there is a next <a>fragmentation container</a>
-	that would receive subsequent content,
-	then the content replaced by the <a>block overflow ellipsis</a>
-	must be pushed to the next <a>fragmentation container</a>
-	and the <a>block overflow ellipsis</a> inserted and laid out
-	exactly as if it were part of the <a>in-flow</a> contents of the line.
-	This can result in changes to layout within or impacted by the line.
-	The means of breaking any resulting cycles is up to the UA.
-
-	If the <a>block overflow ellipsis</a>
-	is too long to fit in the line,
-	the result is undefined.
-	(The UA may, for example, treat the <a>block overflow ellipsis</a> as an unbreakable string,
-	or it may lay out the string across more than one line,
-	replacing content in earlier lines as well.)
-
-	The <a>block overflow ellipsis</a> does not capture events:
-	pointer events are dispatched to whatever is underneath
-	or otherwise visually replaced by it.
-
-	It also has no effect on the intrinsic size of the box:
-	its <a lt="min-content size">min-content</a> and <a lt="max-content size">max-content</a> sizes
-	are calculated exactly as if 'block-overflow' were ''block-overflow/clip''.
-
-	Note: Future specifications may extend this feature,
-	for example by providing an ''::ellipsis'' pseudo-element
-	to style the text,
-	or by allowing the selection of a child element of the block
-	to use as either an inline-level or block-level indicator
-	(in which case, it can capture events).
-
-
 
 Privacy and Security Considerations {#priv-sec}
 ===============================================