tweak/rearrange stripes() text; add sum<1 behavior

Author: tabatkins

css-images-4/Overview.bs

@@ -1907,36 +1907,83 @@ Color Stop “Fixup”</h4>
 1D Image Values: the ''stripes()'' notation {#stripes}
 ======================================================
 
-	The ''stripes()'' function allows to define a number of stripes of
-	different colors with different widths.
-
-	The syntax for ''1d-image'' and ''stripes()'' is defined as:
+	While most <<image>> values represent a 2-dimensional image,
+	and <<color>> can be thought of as a "0-dimensional" image
+	(unvarying in either axis),
+	there are some contexts where a 1-dimensional image makes sense,
+	specifying colors along a <dfn export>paint line</dfn>
+	without defining a <em>direction</em> for the line.
+	The <<1d-image>> type represents such images.
+	
+	Some contexts will define how they use the <<1d-image>> as a 1-dimensional value;
+	for example, in 'border-color',
+	the given colors paint "outwards" from each side of the border.
+	When used generically as an <<image>>, a <<1d-image>> is painted identically to a ''linear-gradient(to bottom, ...)''
+	using the [=paint line=] as its [=gradient line=].
 
 	<pre class=prod>
 		<dfn>&lt;1d-image></dfn> = <<stripes()>>
 		<dfn>stripes()</dfn> = stripes( [ <<color>> && [ <<length-percentage>> | <<flex>>]? ]# )
 	</pre>
-
-	The function represents a 1-dimensional image generated by a list of colors
-	and an optional thickness for each of them.
-
-	A <<percentage>> or <<flex>> value refers to the total length of the image
-	in the used context.
-	The <<percentage>> must be between ''0%'' and ''100%'' inclusive;
-	any other value is invalid.
-
-	If the thickness of a stripe is omitted, it is interpreted as ''1fr''.
-
-	If not defined differently by the context the function is used in, the
-	stripes are painted from top to bottom and tiled horizontally. If the size
-	of the painting area exceeds the total thickness of the stripes, the
-	remaining area is painted transparently. I.e. it behaves as if there was an
-	additional last ''transparent'' stripe. If the size of the painting area
-	is smaller than the total thickness of the stripes, the stripes are clipped
-	starting from the last defined color.
-
-	The computed value of this function is the [=specified value=] with all
-	<<color>>s computed '1fr' values removed.
+	
+	The ''stripes()'' function defines a 1d-image
+	as a number of colored stripes with different widths.
+	
+	Each comma-separated entry defines a solid-color stripe,
+	each placed end-to-end on the [=paint line=] in the order given,
+	with the specified <<color>> and thickness.
+	If the thickness is omitted,
+	it defaults to ''1fr''.
+	
+	In each entry, a <<percentage>> is relative to the |painting area|
+	and must be between ''0%'' and ''100%'' inclusive
+	or else the function is invalid.
+	A <<flex>> is evaluated as a fraction of the |painting area|
+	relative to the total sum of <<flex>> entries in the function,
+	after subtracting the thickness of any non-<<flex>> entries
+	(flooring the subtraction result at zero).
+	If the sum of <<flex>> values is less than 1fr,
+	the result of the subtraction is multiplied by the sum's value
+	before being distributed.
+	
+	<div class=example>
+		For example, 
+		''stripes(red 1fr, green 2fr, blue 100px)``
+		with a |painting area| of ''400px''
+		will result in a 100px red stripe and 200px green stripe,
+		giving red 1 share and green 2 shares of the 300px remaining
+		after subtracting blue's 100px from the 400px total.
+		
+		On the other hand,
+		''stripes(red .1fr, green .2fr, blue 100px)``
+		with a |painting area| of ''400px''
+		will instead give a 30px red stripe and 60px green stripe,
+		followed by 100px of blue and then 210px of transparent.
+		The 300px of leftover space is multiplied by .3,
+		the value of the sum of the <<flex>> values,
+		to obtain only 90px,
+		which is then distributed in the 1:2 ratio
+		the <<flex>> values would dictate.
+		
+		(This is similar to how [=flex layout=] deals with small <<flex>> sums on a line,
+		and ensures smoothly continuous behavior
+		as the <<flex>> values approach zero.)
+	</div>
+		
+	
+	The |painting area| is defined by the context in which the ''stripes()'' function is used.
+	If used generically as an <<image>>,
+	the |painting area| is the height of the [=concrete image size=].
+	
+	If the sum thickness of the stripes is smaller than the |painting area|,
+	the [=paint line=] is [=transparent black=] for its remaining length,
+	as if a final ''transparent'' argument were given.
+	If the sum thickness is larger,
+	any stripes or portions thereof that would be past the end of the [=paint line=] have no effect.
+
+	The computed value of this function is the [=specified value=] 
+	with all <<color>>s computed
+	and all <<length-percentage>>s absolutized and computed to the extent possible.
 
 <!--
  ██████  ████ ████████ ████ ██    ██  ██████