[css-color-5] try to improve bikeshed markup

Author: svgeesus

css-color-5/Overview.bs

@@ -89,7 +89,7 @@ Mixing colors: the ''color-mix'' function {#colormix}
 
 <pre class='prod'>
 	<dfn>color-mix()</dfn> = color-mix( <<color>>  <<color>> [ <<number>> | <<percentage>> |
-		[ <<color-adjuster>> <<colorspace>>? ]?] )
+		[ [=color-adjuster=] [=colorspace=]? ]?] )
 </pre>
 
 <pre class='prod'>
@@ -107,34 +107,34 @@ Mixing colors: the ''color-mix'' function {#colormix}
 	<dfn>hue-adjuster</dfn> = hue [shorter | longer | increasing | decreasing ]?
 </pre>
 
-When no colorspace is specified,
-the mixing is done in the ''lch()'' colorspace.
+When no [=colorspace=] is specified,
+the mixing is done in the ''lch'' colorspace.
 
-When a plain number or percentage is specified (without a color-adjuster),
-it applies to all color channels in the given colorspace equally.
+When a plain number or percentage is specified (without a [=color-adjuster=]),
+it applies to all color channels in the given [=colorspace=] equally.
 
 If the plain number or percentage is omitted,
 it defaults to 50% (an equal mix of the two colors).
 
-The xyz colorspace is CIE XYZ and allows computation to be done
-in a linear-light-intensity space..
+The [=xyz=] colorspace is CIE XYZ, with a D50 whitepoint, and allows computation to be done
+in a linear-light-intensity space.
 
 The meaning of the adjusters is defined by colorspace.
-For example, if the colorspace is hsl,
+For example, if the [=colorspace=] is [=hsl=],
 hue means the HSL hue, which is not the same as the LCH hue;
-if the colorspace is LCH,
+if the colorspace is [=lch=],
 lightness means the LCH Lightness, which is the same as Lab lightness,
 but different to the HSL Lightness.
 
-Only the adjusters defined for a given colorspace are available.
+Only the [=color-adjuster=]s defined for a given [=colorspace=] are available.
 For example,
-it is not possible to use the HWB whiteness adjuster unless the colorspace is hwb.
+it is not possible to use the HWB [=whiteness=] adjuster unless the colorspace is [=hwb=].
 
 If the specified colorspace has a smaller gamut
 than the one in which the color to be adjusted is specified,
 gamut mapping will occur.
 
-Note: not all adjusters are equally useful.
+Note: not all [=color-adjuster=]s are equally useful.
 Adjustments in LCH are the most useful, which is why it is the default.
 Adjustments on the a and b axes are rarely needed.
 Adjustments in the srgb-related spaces (srgb itself, hsl, hwb)
@@ -144,7 +144,7 @@ Adjusting the individual x, y and z channels will produce significant hue shifts
 however, adjusting all three channels together is useful
 and will lighten or darken the color.
 
-The hue adjuster takes optional keywords, because there are two ways around the hue circle. If no keyword is specified, it is as if ''shorter'' were specified. ''increasing'' is the direction of increasing hue angle; ''decreasing'' is the direction of decreasing hue angle. If the hue difference is exactly 180 degrees,
+The [=hue-adjuster=] takes optional keywords, because there are two ways around the hue circle. If no keyword is specified, it is as if ''shorter'' were specified. ''increasing'' is the direction of increasing hue angle; ''decreasing'' is the direction of decreasing hue angle. If the hue difference is exactly 180 degrees,
 it is as if ''decreasing'' were specified.
 
 <div class="example">
@@ -323,12 +323,25 @@ are copied across from the <em>first</em> color.
 
 </div>
 
-<!-- number | percent is ambiguous for lightness because lightness is itself a percentage -->
+<div class="example">
+	This example produces the mixture of
+	the same two colors as the previous examples
+	(a red and a sky blue),
+	in ''xyz'' colorspace,
+	with the mixture being 75.23% of that of the red
+	(and thus, 24.77% of that of the blue).
 
-	<!-- showing out of gamut colors next -->
+	<pre class="lang-css">color-mix(rgb(82.02% 30.21% 35.02%) rgb(5.64% 55.94% 85.31%) 75.23% xyz);</pre>
 
+	The calculation is as follows:
+	  * <span class="swatch" style="--color: rgb(82.02% 30.21% 35.02%)"></span> rgb(82.02% 30.21% 35.02%) is lch(52% 58.1 22.7) which is X=0.3214, Y=0.2014, Z=0.0879.
+	  * <span class="swatch" style="--color: rgb(5.64% 55.94% 85.31%)"></span> rgb(5.64% 55.94% 85.31%) is lch(56% 49.1 257.1) which is X=0.2070, Y=0.2391, Z=0.5249.
+	  * mixed result X=(0.3214 * 0.7523) + (0.2070 * (1 - 0.7523)) = 0.29306.
+	  * mixed result Y=(0.2014 * 0.7523) + (0.2391 * (1 - 0.7523)) = 0.21074.
+	  * mixed result Z=(0.0879 * 0.7523) + (0.5249 * (1 - 0.7523)) = 0.19614.
+	  * mix result is <span class="swatch" style="--color: rgb(72.300% 38.639% 53.557%)"></span> lch(53.0304% 38.9346, 352.8138) which is rgb(72.300% 38.639% 53.557%)
+</div>
 
-<!-- <img src="images/mix_red_white_lightness50.png" alt="Result of color-mix(red, white, lightness(50%)" /> -->
 
 <div class="example">
 	This example produces the mixture of red and yellow,