[css-values-5][editorial] Clean up some random() prose.

Author: fantasai

css-values-5/Overview.bs

@@ -2287,11 +2287,6 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
 
 	<pre class=prod>
 	&lt;random()> = random( <<random-cache-key>>? , <<calc-sum>>, <<calc-sum>>, <<calc-sum>>? )
-
-	<dfn><<random-cache-key>></dfn> = auto | <<random-name>> | fixed <<number [0,1]>>
-	<dfn><<random-name>></dfn> =  <<dashed-ident>> || element-scoped
-	                       || [ property-scoped | property-index-scoped | <<random-ua-ident>> ]
-	<dfn><<random-ua-ident>></dfn> = <<custom-ident>>
 	</pre>
 
 	See [[#random-evaluation]] and [[#random-caching]]
@@ -2580,70 +2575,76 @@ Evaluating Random Values</h3>
 Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 
 	CSS is a declarative language,
-	so functions don't have a specific "time" when they're "evaluated";
-	the user agent is free to "execute" functions in any order,
+	so functions don't have a specific “time” when they're evaluated;
+	the user agent is free to “execute” functions in any order,
 	as many times as they want,
 	as every execution will return the same value.
-	This is difficult to square with "random" functions,
+	This is difficult to square with random-value functions,
 	which are inherently <em>stateful</em> and care about
 	when, how often, and in what order they're executed.
 
-	To fix this, the [=random functions=] are associated with a [=random cache name=],
+	To solve this, the [=random functions=] are associated with a [=random cache name=],
 	ensuring that any time the random function is evaluated with the same cache key,
 	it will return the same [=random base value=];
 	and also that [=random functions=] with <em>different</em> caching keys
 	will return <em>different</em> [=random base value=] from each other
 	(unless they are, randomly, the same).
 
-	The <<random-cache-key>> value controls this behavior:
+	The <<random-cache-key>> value controls this behavior,
+	and defaults to ''random()/auto'' when omitted.
+	It's syntax is as follows, and interpreted as described below:
+
+	<pre class=prod>
+		<dfn><<random-cache-key>></dfn> = auto | <<random-name>> | fixed <<number [0,1]>>
+		<dfn><<random-name>></dfn> =  <<dashed-ident>> || element-scoped
+		                       || [ property-scoped | property-index-scoped | <<random-ua-ident>> ]
+		<dfn><<random-ua-ident>></dfn> = <<custom-ident>>
+	</pre>
 
 	<dl dfn-type=value dfn-for="random(),random-item(),<random-cache-key>">
 		: <dfn>auto</dfn>
-		:: The [=random function=] is roughly "as random as possible":
-			every usage in a property,
-			between different properties,
-			and between different elements
-			will get a different [=random cache name=].
+		:: The [=random function=] is roughly “as random as possible”:
+			the [=random cache name=], and thus the result,
+			varies across every ''random()'' instance in a multi-component value,
+			across different properties,
+			and across different elements.
+
 			This is equivalent to specifying ''element-scoped property-index-scoped'',
 			and simplifies in exactly the same way.
 
-			If the <<random-cache-key>> is omitted,
-			it behaves as ''random()/auto''.
-
 		: <dfn><<random-name>></dfn>
-		:: The <<random-name>> specifies the [=random cache name=] directly,
-			<em>naming</em> the random value and allowing it to be explicitly shared (or not)
+		:: The <<random-name>> specifies the [=random cache name=],
+			allowing it to be explicitly shared (or not)
 			with other uses of [=random functions=].
 			Every [=random function=] using the same [=random cache name=]
 			will get the same random value;
 			every one using a <em>different</em> [=random cache name=]
 			will get unrelated random values.
 
-			The [=random cache name=] is made of several possible parts,
-			which are all optional
-			and can be specified in any order:
-
-			* The <<dashed-ident>>, giving the value an explicit name.
+			* The <<dashed-ident>> gives the value an explicit name.
 				If omitted, this part of the name is null.
 			* <dfn>element-scoped</dfn> adds an element-specific identifier
 				to the [=random cache name=],
 				so different elements will get different random values.
 			* <dfn>property-scoped</dfn> adds the property name the [=random function=] is being used on
 				to the [=random cache name=],
 				so different properties will get different random values.
+				Note that shorthand declarations will apply the [=shorthand property=]'s name.
 			* <dfn>property-index-scoped</dfn>
 				adds the property name <em>and</em> the index of the random function
 				among all the random functions used in the same property value
 				to the [=random cache name=],
-				so multiple uses of a [=random function=] in the same property
-				will get different random values.
+				so multiple instances of a [=random function=] in the same declaration
+				will each get different [=random cache names=].
+				Note this index is assigned <em>before</em> [=shorthand=] expansion.
 
-			''property-scoped'' and ''property-index-scoped''
-			are mutually exclusive with each other,
-			and also with the <dfn><<random-ua-ident>></dfn> value.
-			This value, like ''fixed'' below, isn't intended to be specified by authors,
+			See [[#random-simplify]] for how these values resolve.
+
+			The <dfn><<random-ua-ident>></dfn> value,
+			like ''fixed'' below, isn't intended to be specified by authors,
 			but can show up in [=computed values=].
-			It is a <<custom-ident>> that must start with the prefix <css>ua-</css>.
+			It is a <<custom-ident>> that must start with the prefix <css>ua-</css>,
+			or else it is invalid.
 			When generated automatically by the user agent,
 			it will always be <css>ua-PROPERTY</css> or <css>ua-PROPERTY-INDEX</css>,
 			with the <css>PROPERTY</css> and <css>INDEX</css> parts
@@ -2797,7 +2798,8 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 		(both are the first [=random function=] used in 'animation'),
 		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".
+		even though the author likely considers them to be
+		different instances of ''random()''.
 
 		This unexpected sharing is, unfortunately, unavoidable.
 		CSS generally doesn't care <em>how</em> you organize styles for your elements;
@@ -2858,28 +2860,28 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 		2. A nullable [=string=] property/index value:
 			the value of the <<random-ua-ident>>, if specified/calculated;
 			otherwise null.
-		4. A nullable "element identifier"
+		4. A nullable /element identifier/
 			uniquely identifying the {{Element}} or [=pseudo-element=]
 			the style is being applied to,
 			if ''random()/element-scoped'' is specified;
 			otherwise null.
-		5. A document ID identifying the {{Document}} the styles are from.
+		5. A /document identifier/ identifying the {{Document}} the styles are from.
 
-		The "element ID" and "document ID" must have the same lifetimes and equivalence semantics
+		The /element identifier/ and /document identifier/
+		must have the same lifetimes and equivalence semantics
 		as a JavaScript reference to the {{Element}} or {{Document}}.
 
 		Issue: The behavior for pseudo-elements needs to be clarified.
 
 	* The [=random cache name=] and [=random base value=]
 		must be determined by [=computed value=] time,
 		before [=inheritance=],
-		so that a random function which is unresolved by inheritance time
+		so that a random function that is unresolved by inheritance time
 		(due to containing, for example, a layout-sensitive percentage)
 		does not have a different behavior on children
-		from one that resolves immediately.
+		than one that resolves immediately.
 
 	<div class=example>
-
 		Shorthands are recorded as part of the [=random cache name=],
 		rather than the longhand the value gets expanded to.
 		For example:
@@ -2941,8 +2943,8 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 
 		Similarly, ''random()/element-scoped'' in the <<random-cache-key>>
 		won't cause the function to determine its "element identifier"
-		until substitution actually happens,
-		which might be <em>after</em> '--size' has inherited through multiple elements,
+		until substitution actually happens--
+		which might be <em>after</em> '--size' has inherited through multiple elements--
 		so again multiple elements using ''var(--size)''
 		would end up with distinct random values
 		rather than sharing one value defined on their ancestor.
@@ -2955,14 +2957,14 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 		Both issues can be resolved
 		by instead using a [=registered custom property=]
 		with a non-universal grammar,
-		so the ''random()'' function will be parsed and evaluated in the [=custom property=]
+		so the ''random()'' function will be parsed and evaluated by the [=custom property=]
 		(gaining a <<random-ua-ident>> of "ua---size-1"),
 		and then the resolved random value will be substituted into each property.
 	</div>
 
 
 <h4 id=random-simplify>
-Simplification</h4>
+Random Simplification</h4>
 
 	At parse time,
 	certain transformations are performed on the <<random-cache-key>> of a [=random function=]:
@@ -2975,7 +2977,7 @@ Simplification</h4>
 		either <css>ua-PROPERTY</css> with PROPERTY being the property the value was parsed as,
 		or <css>ua-PROPERTY-INDEX</css> with PROPERTY as the previous
 		and INDEX being the 1-indexed integer index of this [=random function=]
-		among all [=random functions=] being used in the property.
+		among all [=random functions=] being used in the declaration.
 
 		The INDEX value is based on the ordering in the parsed value,
 		before any canonicalization/reordering might occur