[css-values-5][editorial] Big, but completely editorial, rearranging/rewrite of the caching key information.

Author: tabatkins

css-values-5/Overview.bs

@@ -1461,7 +1461,7 @@ Toggling Between Values: the ''toggle()'' notation</h3>
 	not a particular serialization [[!CSS21]],
 	so comparison between computed values should always be unambiguous and have the expected result.
 	For example,
-	a Level 2 <l spec=css22>'background-position'</l> computed value
+	a Level 2 <l spec=css2>'background-position'</l> computed value
 	is just two offsets, each represented as an absolute length or a percentage,
 	so the declarations ''background-position: top center'' and ''background-position: 50% 0%''
 	produce identical computed values.
@@ -1993,101 +1993,23 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
 	<pre class=prod>
 	&lt;random()> = random( <<random-value-sharing>>? , <<calc-sum>>, <<calc-sum>>, <<calc-sum>>? )
 
-	<dfn><<random-value-sharing>></dfn> = <dfn value for="random()|<random-value-sharing>">auto</dfn> | [ <<dashed-ident>> || <dfn value for="random()|<random-value-sharing>">match-element</dfn> ] | <<number [0,1]>>
+	<dfn><<random-value-sharing>></dfn> = [ [ auto | <<dashed-ident>> ] || match-element ]
+	                       | <<number [0,1]>>
 	</pre>
 
 	Its arguments are:
 
 	<dl>
-		: <css><<random-value-sharing>></css>
+		: <<random-value-sharing>>
 		:: The optional <<random-value-sharing>>
-			controls whether a given ''random()'' function
-			resolves similarly or differently to other [=random functions=] on the page.
-			See [[#random-caching]] for details.
-
-			If <<random-value-sharing>> is omitted or specified as ''random()/auto'',
-			''random()'' functions on different properties,
-			and multiple ''random()'' functions within a single property,
-			will resolve to different random values,
-			and will have different values on every element
-			styled with that property.
-
-			Providing <<random-value-sharing>> makes it "less random":
-
-			* two ''random()'' functions on an element with the same <<dashed-ident>>
-				will use the same random value.
-				(They'll still be different between elements, tho.)
-			* two elements using the same style containing ''random()'' with ''match-element''
-				will use the same random value on both of them.
-				(They'll still be different between properties, tho.)
-			* with both <<dashed-ident>> and ''match-element'' together,
-				multiple ''random()'' functions will use the same random value
-				across different properties
-				and on all elements using the same style.
+			controls which [=random functions=] in the document
+			will share a [=random base value=]
+			and which will get distinct values.
+			If <<random-value-sharing>> is omitted,
+			it behaves as ''random()/auto''.
 
-			<div class=example>
-				* <b>Maximum random</b>:
-					both properties get a different value,
-					and it's different per element too,
-					so you get lots of random rectangles.
-
-					<pre highlight=css>
-					.random-rect {
-						width: random(100px, 200px);
-						height: random(100px, 200px);
-					}
-					</pre>
-
-				* <b>Shared by name within an element</b>:
-					both properties get the same value,
-					but it's still different per element,
-					so you get lots of random squares.
-
-					<pre highlight=css>
-					.random-square {
-						width: random(--foo, 100px, 200px);
-						height: random(--foo, 100px, 200px);
-					}
-					</pre>
-
-				* <b>Shared between elements within a property</b>:
-					both properties get different values,
-					but they're shared by every element,
-					so you get lots of identical rectangles of a single random size.
-
-					<pre highlight=css>
-					.shared-random-rect {
-						width: random(match-element, 100px, 200px);
-						height: random(match-element, 100px, 200px);
-					}
-					</pre>
-
-				* <b>Shared globally</b>:
-					both properties get the same value,
-					and every element shares that value,
-					so you get lots of identical squares of a single random size.
-
-					<pre highlight=css>
-					.shared-random-squares {
-						width: random(--foo match-element, 100px, 200px);
-						height: random(--foo match-element, 100px, 200px);
-					}
-					</pre>
-			</div>
-
-			Instead of a caching key,
-			a <<number>> between 0 and 1 can be specified;
-			this provides the [=random base value=] to be used
-			rather than generating one for you.
-
-			This <em>can</em> be used by authors to aid in testing their page
-			(using a stable value rather than one that changes each refresh),
-			but it mostly exists to help [=user agents=]
-			ensure that ''random()'' can be fully resolved at [=computed value=] time in all cases,
-			so the function inherits reasonably.
-			If the function's min/max/step values can't resolve in time,
-			the ''random()'' function determines its [=random base value=]
-			and computes to a form using this instead.
+			See below for details on the <<random-value-sharing>> options,
+			and see [[#random-caching]] for a precise description of their behavior.
 
 		: <css><<calc-sum>>, <<calc-sum>></css>
 		:: The two required [=calculations=]
@@ -2150,6 +2072,186 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
 			while ''100px'' and ''200px'' will only occur 1/4 of the time each.
 	</dl>
 
+	The <<random-value-sharing>> value controls sharing along two axises:
+
+	* between [=random functions=] used for different things
+		in the style for a single element,
+		via the ''random()/auto'' or ''random()/<dashed-ident>'' values
+	* between [=random functions=] used for the same thing
+		in the styles across several elements,
+		via the ''random()/match-element'' value (or its absence)
+
+	<dl dfn-type=value dfn-for="random()|<random-value-sharing>">
+		: <dfn>auto</dfn>
+		::	Each [=random function=] in an element's styles
+			will use a distinct [=random base value=].
+			(But see <a href="#auto-naming-details">the note below</a> for a small wrinkle about this.)
+
+			If neither ''random()/auto'' nor ''random()/<dashed-ident>'' are specified,
+			it behaves as ''random()/auto''.
+
+		: <dfn><<dashed-ident>></dfn>
+		:: Each [=random function=] in an element's styles
+			with the same <<dashed-ident>>
+			will share the same [=random base value=];
+			ones with different <<dashed-ident>>s
+			will use distinct [=random base values=].
+
+		: <dfn>match-element</dfn>
+		:: If ''random()/match-element'' is omitted,
+			[=random functions=] on different elements
+			will use distinct [=random base values=].
+
+			If specified,
+			[=random functions=] on different elements
+			will share the same [=random base value=]
+			if they have the same <<dashed-ident>> (if specified)
+			or if they're used in the same style in the same way (if not).
+			(Again, see <a href="#auto-naming-details">the note below</a> for a small wrinkle about this.)
+
+		: <dfn><<number>></dfn>
+		:: If <<number>> is specified,
+			it's used as the [=random function's=] [=random base value=],
+			rather than allowing the UA to generate a [=random base value=]
+			and controlling how it's shared.
+
+			Note: While this <em>might</em> be useful for authors
+			to get predictable values while testing a page,
+			the reason it exists is to fix some corner cases in [=inheritance=]
+			that would otherwise cause elements to <em>not</em> share [=random base values=]
+			when authors would expect them to.
+			It is observable in some rare [=computed values=],
+			but otherwise will never show up in an element's styles.
+	</dl>
+
+	<div class=example>
+		* <b>Maximum random</b>:
+			both properties get a different value,
+			and it's different per element too,
+			so you get lots of random rectangles.
+
+			<pre highlight=css>
+			.random-rect {
+				width: random(100px, 200px);
+				height: random(100px, 200px);
+			}
+			</pre>
+
+		* <b>Shared by name within an element</b>:
+			both properties get the same value,
+			but it's still different per element,
+			so you get lots of random squares.
+
+			<pre highlight=css>
+			.random-square {
+				width: random(--foo, 100px, 200px);
+				height: random(--foo, 100px, 200px);
+			}
+			</pre>
+
+		* <b>Shared between elements within a property</b>:
+			both properties get different values,
+			but they're shared by every element,
+			so you get lots of identical rectangles of a single random size.
+
+			<pre highlight=css>
+			.shared-random-rect {
+				width: random(match-element, 100px, 200px);
+				height: random(match-element, 100px, 200px);
+			}
+			</pre>
+
+		* <b>Shared globally</b>:
+			both properties get the same value,
+			and every element shares that value,
+			so you get lots of identical squares of a single random size.
+
+			<pre highlight=css>
+			.shared-random-squares {
+				width: random(--foo match-element, 100px, 200px);
+				height: random(--foo match-element, 100px, 200px);
+			}
+			</pre>
+	</div>
+
+	<details class=note id=auto-naming-details>
+		<summary>Details about how ''random()/auto'' works</summary>
+
+		Technically, the ''random()/auto'' value generates a name
+		similar to an author specifying a <<dashed-ident>>,
+		but it's auto-generated using the property the [=random function=] shows up in,
+		and its index among multiple [=random functions=] in that property.
+		For example, in ''margin: random(0px, 10px) random(0px, 10px)'',
+		the first function gets a name of "margin 0"
+		while the second gets a name of "margin 1".
+
+		This ensures that every auto-generated name on a single element is unique,
+		and thus will get their own [=random base value=].
+		It also ensures that declarations like
+		''.foo { width: random(match-element, 100px, 200px); }''
+		will cause all the ''.foo'' elements to share a [=random base value=] for their width
+		(they all have the same auto-generated name, "width 0").
+
+		However, it also means that a few other cases can create sharing that might be unexpected.
+		For example, in the following:
+
+		<pre highlight=css>
+		.foo {
+			width: random(match-element, 100px, 200px);
+		}
+		.bar {
+			width: random(match-element, 200px, 300px);
+		}
+		</pre>
+
+		Both ''.foo'' and ''.bar'' elements have ''random()'' functions
+		whose auto-generated names are "width 0",
+		so they'll share the same [=random base value=]
+		and generate related random values,
+		even if they were never intended to be linked together like that.
+
+		Similarly, in the following:
+
+		<pre highlight=css>
+		.foo {
+			animation: flicker linear random(1s, 2s);
+		}
+		.foo:hover {
+			animation: glow linear random(4s, 6s);
+		}
+		</pre>
+
+		The two ''random()'' functions have the same auto-generated name "animation 0",
+		so they'll share [=random base values=] on a single element
+		and generate related random values,
+		even tho the author likely considers them to be "different uses".
+
+		This unexpected sharing is, unfortunately, unavoidable.
+		CSS generally doesn't care <em>how</em> you organize styles for your elements;
+		in particular, whether you style several elements
+		with a single style rule like ''.foo, .bar {...}'',
+		multiple style rules like ''.foo {...} .bar {...}'',
+		or by setting the <{html-global/style}> attribute on each element individually,
+		you'll get the same results.
+		This needs to continue to be true even when you're using random values,
+		so we can't distinguish random values by how they're <em>set</em>,
+		only how they're <em>used</em>.
+
+		There's no syntactic distinction in a stylesheet
+		between styling "related" elements and "independent" elements,
+		or distinguishing "independent" states,
+		so we must treat all elements as potentially related for this purpose.
+		If this is undesirable,
+		you can always supply a sufficiently unique <<dashed-ident>> yourself,
+		like ''random(--sidebar-width match-element, ...)'' on one set of elements
+		and ''random(--card-width match-element, ...)'' on another,
+		or ''random(--flicker, ...)'' and ''random(--glow, ...)'' on the different rules.
+
+		This is the one case where supplying a <<dashed-ident>>
+		can <em>reduce</em> the sharing of [=random base values=]
+		versus omitting it.
+	</details>
+
 	All of the [=calculation=] arguments can resolve to any value,
 	but must have a [=consistent type=]
 	or else the function is invalid;