[css-images-4] Rearrange the color-stops section and break into subsections for clarity. Remove hint complaining that I should do this rearranging. ^_^ Rework some text, particularly in notes, for clarity; no normative changes intended.

Author: tabatkins

css-images-4/Overview.bs

@@ -1333,8 +1333,23 @@ Repeating Gradients: the ''repeating-linear-gradient()'', ''repeating-radial-gra
 <h3 id='color-stop-syntax'>
 Gradient Color-Stops</h3>
 
-	All gradients are specified by a list of color stops,
-	giving the color and position of each stop on the [=gradient line=],
+	The colors in gradients are specified using <a>color stops</a>.
+	A <dfn export>color stop</dfn> is a combination of a color and one or two positions.
+	(Depending on the type of gradient, that position can be a length, angle, or percentage.)
+	While every color stop conceptually has at least one position,
+	the position can be omitted in the syntax.
+	(It gets automatically filled in by the user agent; see below for details.)
+	The unit identifier may be omitted if the position is zero.
+
+	Between two <a>color stops</a> there can be a <dfn local-lt="color hint">color interpolation hint</dfn>,
+	which specifies how the colors of the two <a>color stops</a> on either side
+	should be interpolated in the space between them
+	(by default, they interpolate linearly).
+	There can only be at most one <a>color interpolation hint</a> between any two given <a>color stops</a>;
+	using more than that makes the function invalid.
+
+	Color stops are organized into a <dfn export>color stop list</dfn>,
+	which is a list of one or more <a>color stops</a>,
 	according to the following grammar:
 
 	<pre class=prod>
@@ -1375,33 +1390,6 @@ Gradient Color-Stops</h3>
 		</pre>
 	</div>
 
-	<p class='issue'>
-		This is past the complexity point where it can be easily understood with just prose.
-		Add a diagram illustrating the possibilities,
-		preferably for all three kinds of gradients
-		(to show off the three shapes of gradient lines).
-
-	The colors in gradients are specified using <a>color stops</a>.
-	A <dfn export>color stop</dfn> is a combination of a color and one or two positions.
-	(Depending on the type of gradient, that position can be a length, angle, or percentage.)
-	While every color stop conceptually has at least one position,
-	the position can be omitted in the syntax.
-	(It gets automatically filled in by the user agent; see below for details.)
-	The unit identifier may be omitted if the position is zero.
-
-	Between two <a>color stops</a> there can be a <dfn local-lt="color hint">color interpolation hint</dfn>,
-	which specifies how the colors of the two <a>color stops</a> on either side
-	should be interpolated in the space between them
-	(by default, they interpolate linearly).
-	There can only be at most one <a>color interpolation hint</a> between any two given <a>color stops</a>;
-	using more than that makes the function invalid.
-
-	Color stops are organized into a <dfn export>color stop list</dfn>,
-	which is a list of one or more <a>color stops</a>.
-	The first and last <a>color stops</a> in the list
-	must have a color
-	(though their position can be omitted).
-
 	<a>Color stops</a> and <a>color hints</a> are placed on a <a>gradient line</a>,
 	which defines the colors at every point of a gradient.
 	The gradient function defines the shape and length of the <a>gradient line</a>,
@@ -1432,6 +1420,121 @@ Gradient Color-Stops</h3>
 	If multiple stops in a row lack a position,
 	they space themselves out equally.
 
+<h4 id=coloring-gradient-line>
+Coloring the Gradient Line</h4>
+
+	At each <a>color stop</a> position,
+	the [=gradient line=] is the color of the <a>color stop</a>.
+	Before the first <a>color stop</a>,
+	the [=gradient line=] is the color of the first <a>color stop</a>.
+	After the last <a>color stop</a>, the [=gradient line=] is the color of the last <a>color stop</a>.
+	Between two <a>color stops</a>,
+	the [=gradient line’s=] color is interpolated between the colors of the two <a>color stops</a>,
+	with the interpolation taking place in premultiplied RGBA space.
+
+	By default,
+	this interpolation is linear--
+	at 25%, 50%, or 75% of the distance between two <a>color stops</a>,
+	the color is a 25%, 50%, or 75% blend of the colors of the two stops.
+
+	However, if a <a>color hint</a> was provided between two <a>color stops</a>,
+	the interpolation is non-linear,
+	and controlled by the hint:
+
+	<div algorithm="interpolate with a color hint">
+		<ol>
+			<li>
+				Determine the location of the <a>color hint</a> as a percentage of the distance between the two <a>color stops</a>,
+				denoted as a number between 0 and 1,
+				where 0 indicates the hint is placed right on the first <a>color stop</a>,
+				and 1 indicates the hint is placed right on the second <a>color stop</a>.
+				Let this percentage be <var>H</var>.
+
+			<li>
+				For any given point between the two color stops,
+				determine the point's location as a percentage of the distance between the two <a>color stops</a>,
+				in the same way as the previous step.
+				Let this percentage be <var>P</var>.
+
+			<li>
+				Let <var>C</var>, the color weighting at that point,
+				be equal to <code>P<sup>log<sub>H</sub>(.5)</sup></code>.
+
+			<li>
+				The color at that point is then a linear blend between the colors of the two <a>color stops</a>,
+				blending <code>(1 - C)</code> of the first stop and <var>C</var> of the second stop.
+		</ol>
+	</div>
+
+	Note: The color hint specifies where the "halfway color"--
+	the 50% blend between the colors of the two surrounding color stops--
+	should be placed.
+	When the hint is exactly halfway between the two surrounding color stops,
+	the above interpolation algorithm
+	happens to produce the ordinary linear interpolation.
+	If the hint is placed anywhere else,
+	it produces a smooth "exponential curve"
+	between the surrounding color stops,
+	with the "halfway color" occuring exactly where the hint specifies.
+
+	Issue: Add a visual example of a color hint being used.
+
+	If multiple <a>color stops</a> have the same position,
+	they produce an infinitesimal transition from the one specified first in the list
+	to the one specified last.
+	In effect, the color suddenly changes at that position rather than smoothly transitioning.
+
+	<div class=example>
+		The following example illustrates the difference between
+		a gradient transitioning in pre-multiplied sRGBA
+		and one transitioning (incorrectly) in non-premultiplied.
+		In both of these example,
+		the gradient is drawn over a white background.
+		Both gradients could be written with the following value:
+
+		<pre>linear-gradient(90deg, red, transparent, blue)</pre>
+
+		In premultiplied space,
+		transitions to or from "transparent" always look nice:
+
+		<object data="images/gradient2.svg" width="200"height="100">(Image requires SVG)</object>
+
+		On the other hand,
+		if a gradient were to incorrectly transition in non-premultiplied space,
+		the colors near "transparent" would noticeably darken to a grayish color,
+		because "transparent" is actually a shorthand for ''rgba(0,0,0,0)'', or transparent black:
+
+		<object data="images/gradient3.svg" width="200"height="100">(Image requires SVG)</object>
+	</div>
+
+	<div class=note>
+
+		The definition and implications of "premultiplied" color spaces are given elsewhere in the technical literature,
+		but a quick primer is given here to illuminate the process.
+
+		Given a color expressed as an rgba() 4-tuple,
+		one can convert this to a premultiplied representation
+		by multiplying the red, green, and blue components by the alpha component.
+		For example, a partially-transparent blue may be given as <code class=lang-css><nobr>rgba(0, 0, 255, .5)</nobr></code>,
+		which would then be expressed as <code><nobr>[0, 0, 127.5, .5]</nobr></code> in its premultiplied representation.
+
+		Interpolating colors using the premultiplied representations
+		rather than the plain rgba representations
+		tends to produce more attractive transitions,
+		particularly when transitioning from a fully opaque color to fully transparent.
+
+		Note that transitions where either the transparency or the color are held constant
+		(for example, transitioning between <code class=lang-css><nobr>rgba(255, 0, 0, 100%)</nobr></code> (opaque red)
+		and <code class=lang-css><nobr>rgba(0,0,255,100%)</nobr></code> (opaque blue),
+		or <code class=lang-css><nobr>rgba(255,0,0,100%)</nobr></code> (opaque red)
+		and <code class=lang-css><nobr>rgba(255,0,0,0%)</nobr></code> (transparent red))
+		have identical results whether the color interpolation is done in premultiplied or non-premultiplied color-space.
+		Differences only arise when <em>both</em> the color and transparency differ between the two endpoints.
+	</div>
+
+<h4 id=color-stop-fixup>
+Color Stop "Fixup"</h4>
+
 	The following steps must be applied <em>in order</em> to process the <<color-stop-list>>.
 	After applying these rules,
 	all <a>color stops</a> and <a>color hints</a> will have a definite position and color (if appropriate)
@@ -1464,63 +1567,9 @@ Gradient Color-Stops</h3>
 		at the cost of changing behavior from level 3 for some edge cases that triggered fixup.
 		Make sure this is handled well in the serialization rules.
 
-	At each <a>color stop</a> position,
-	the line is the color of the <a>color stop</a>.
-	Between two <a>color stops</a>,
-	the line's color is interpolated between the colors of the two <a>color stops</a>,
-	with the interpolation taking place in premultiplied RGBA space.
-
-	By default,
-	this interpolation is linear--
-	at 25%, 50%, or 75% of the distance between two <a>color stops</a>,
-	the color is a 25%, 50%, or 75% blend of the colors of the two stops.
-
-	However, if a <a>color hint</a> was provided between two <a>color stops</a>,
-	the interpolation is non-linear,
-	and controlled by the hint:
-
-	<ol>
-		<li>
-			Determine the location of the <a>color hint</a> as a percentage of the distance between the two <a>color stops</a>,
-			denoted as a number between 0 and 1,
-			where 0 indicates the hint is placed right on the first <a>color stop</a>,
-			and 1 indicates the hint is placed right on the second <a>color stop</a>.
-			Let this percentage be <var>H</var>.
-
-		<li>
-			For any given point between the two color stops,
-			determine the point's location as a percentage of the distance between the two <a>color stops</a>,
-			in the same way as the previous step.
-			Let this percentage be <var>P</var>.
-
-		<li>
-			Let <var>C</var>, the color weighting at that point,
-			be equal to <code>P<sup>log<sub>H</sub>(.5)</sup></code>.
-
-		<li>
-			The color at that point is then a linear blend between the colors of the two <a>color stops</a>,
-			blending <code>(1 - C)</code> of the first stop and <var>C</var> of the second stop.
-	</ol>
-
-	Note: If the hint is placed halfway between the two stops,
-	this is thus the ordinary linear interpolation.
-	If the hint is placed anywhere else,
-	it dictates the position of the "halfway point",
-	where the color is an equal blend between the two <a>color stops</a>,
-	and produces smooth, even blends between the <a>color stops</a> and the "halfway point".
-
-	Before the first <a>color stop</a>,
-	the line is the color of the first <a>color stop</a>.
-	After the last <a>color stop</a>, the line is the color of the last <a>color stop</a>.
-
-	If multiple <a>color stops</a> have the same position,
-	they produce an infinitesimal transition from the one specified first in the rule
-	to the one specified last.
-	In effect, the color suddenly changes at that position rather than smoothly transitioning.
-
 	<div class=example>
-		Below are several pairs of gradients.
-		The latter of each pair is a manually "fixed-up" version of the former,
+		In the following pairs of gradients,
+		the latter of each pair is a manually "fixed-up" version of the former,
 		obtained by applying the above rules.
 		For each pair, both gradients will render identically.
 		<span class='note'>The numbers in each arrow specify which fixup steps are invoked in the transformation.</span>
@@ -1560,29 +1609,6 @@ Gradient Color-Stops</h3>
 		</pre>
 	</div>
 
-	<div class=example>
-		The following example illustrates the difference between
-		a gradient transitioning in pre-multiplied sRGBA
-		and one transitioning (incorrectly) in non-premultiplied.
-		In both of these example,
-		the gradient is drawn over a white background.
-		Both gradients could be written with the following value:
-
-		<pre>linear-gradient(90deg, red, transparent, blue)</pre>
-
-		In premultiplied space,
-		transitions to or from "transparent" always look nice:
-
-		<object data="images/gradient2.svg" width="200"height="100">(Image requires SVG)</object>
-
-		On the other hand,
-		if a gradient were to incorrectly transition in non-premultiplied space,
-		the colors near "transparent" would noticeably darken to a grayish color,
-		because "transparent" is actually a shorthand for ''rgba(0,0,0,0)'', or transparent black:
-
-		<object data="images/gradient3.svg" width="200"height="100">(Image requires SVG)</object>
-	</div>
-
 	Note: It is recommended that authors not mix different types of units,
 	such as px, em, or %,
 	in a single rule,
@@ -1593,23 +1619,8 @@ Gradient Color-Stops</h3>
 	the blue <a>color stop's</a> position would be equivalent to "75px",
 	which precedes the yellow <a>color stop</a>,
 	and would be corrected to a position of 100px.
-
-	Note: The definition and implications of "premultiplied" color spaces are given elsewhere in the technical literature,
-	but a quick primer is given here to illuminate the process.
-	Given a color expressed as an rgba() 4-tuple,
-	one can convert this to a premultiplied representation
-	by multiplying the red, green, and blue components by the alpha component.
-	For example, a partially-transparent blue may be given as rgba(0,0,255,.5),
-	which would then be expressed as [0, 0, 127.5, .5] in its premultiplied representation.
-	Interpolating colors using the premultiplied representations
-	rather than the plain rgba representations
-	tends to produce more attractive transitions,
-	particularly when transitioning from a fully opaque color to fully transparent.
-	Note that transitions where either the transparency or the color are held constant
-	(for example, transitioning between rgba(255,0,0,100%) and rgba(0,0,255,100%),
-	or rgba(255,0,0,100%) and rgba(255,0,0,0%))
-	have identical results whether the color interpolation is done in premultiplied or non-premultiplied color-space.
-	Differences only arise when both the color and transparency differ between the two endpoints.
+	This would produce an abrupt transition from yellow to blue,
+	rather than the likely-intended smooth transition between the two colors.
 
 
 1D Image Values: the ''stripes()'' notation {#stripes}