[css-values-5][editorial] Rename random grammar productions for clarity

Author: fantasai

css-values-5/Overview.bs

@@ -163,7 +163,7 @@ Commas in Function Arguments</h4>
 		For example, the grammar of the ''random-item()'' function is:
 
 		<pre>
-			random-item( <<random-cache-key>>, [<<declaration-value>>?]# )
+			random-item( <<random-key>>, [<<declaration-value>>?]# )
 		</pre>
 
 		The ''#'' indicates comma-separated repetitions,
@@ -2286,20 +2286,20 @@ Generating a Random Numeric Value: the ''random()'' function</h3>
 	optionally limiting the possible values to a step between those limits:
 
 	<pre class=prod>
-	&lt;random()> = random( <<random-cache-key>>? , <<calc-sum>>, <<calc-sum>>, <<calc-sum>>? )
+	&lt;random()> = random( <<random-key>>? , <<calc-sum>>, <<calc-sum>>, <<calc-sum>>? )
 	</pre>
 
 	See [[#random-evaluation]] and [[#random-caching]]
 	for details on how the function is evaluated.
 	Its arguments are:
 
 	<dl>
-		: <<random-cache-key>>
-		:: The optional <<random-cache-key>>
+		: <<random-key>>
+		:: The optional <<random-key>>
 			controls which [=random functions=] in the document
 			will share a [=random base value=]
 			and which will get distinct values.
-			If <<random-cache-key>> is omitted,
+			If <<random-key>> is omitted,
 			it behaves as ''random()/auto''.
 
 			See [[#random-caching]] for a full description of this value.
@@ -2426,7 +2426,7 @@ Picking a Random Item From a List: the ''random-item()'' function</h3>
 	from among its list of items.
 
 	<pre class=prod>
-	&lt;random-item()> = random-item( <<random-cache-key>> , [ <<declaration-value>>? ]# )
+	&lt;random-item()> = random-item( <<random-key>> , [ <<declaration-value>>? ]# )
 	</pre>
 
 	The ''random-item()'' function's [=argument grammar=] is:
@@ -2438,11 +2438,11 @@ Picking a Random Item From a List: the ''random-item()'' function</h3>
 	See [[#random-evaluation]] and [[#random-caching]]
 	for details on how the function is evaluated.
 
-	The <em>required</em> <<random-cache-key>>
+	The <em>required</em> <<random-key>>
 	is interpreted identically to ''random()''.
 	(See [[#random-caching]] for details.)
 
-	Note: The <<random-cache-key>> argument is required in ''random-item()'',
+	Note: The <<random-key>> argument is required in ''random-item()'',
 	but optional in ''random()'',
 	for parsing reasons
 	(it's impossible to tell whether ''random-item(--foo, --bar, --baz)''
@@ -2478,7 +2478,7 @@ Picking a Random Item From a List: the ''random-item()'' function</h3>
 			and |options| be a list of the remaining <<declaration-value>>? options.
 
 		2. [=Substitute arbitrary substitution functions=] in |value sharing|,
-			then [=CSS/parse=] it as <<random-cache-key>>.
+			then [=CSS/parse=] it as <<random-key>>.
 			If parsing returns failure,
 			return the [=guaranteed-invalid value=];
 			otherwise set |value sharing| to the result.
@@ -2572,7 +2572,7 @@ Evaluating Random Values</h3>
 
 
 <h3 id=random-caching>
-Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
+Sharing (Or Not) Random Values: the <<random-key>> value</h3>
 
 	CSS is a declarative language,
 	so functions don't have a specific “time” when they're evaluated;
@@ -2590,18 +2590,18 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 	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-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
+		<dfn><<random-key>></dfn> = auto | <<random-name>> | fixed <<number [0,1]>>
+		<dfn><<random-cache-key>></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>">
+	<dl dfn-type=value dfn-for="random(),random-item(),<random-key>">
 		: <dfn>auto</dfn>
 		:: The [=random function=] is roughly “as random as possible”:
 			the [=random cache name=], and thus the result,
@@ -2612,31 +2612,33 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 			This is equivalent to specifying ''element-scoped property-index-scoped'',
 			and simplifies in exactly the same way.
 
-		: <dfn><<random-name>></dfn>
-		:: The <<random-name>> specifies the [=random cache name=],
+		: <dfn><<random-cache-key>></dfn>
+		:: The <<random-cache-key>> 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 <<dashed-ident>> gives the value an explicit name.
+			<ul dfn-for="random(),random-item(),<random-key>,<random-cache-key>">
+			<li>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
+			<li><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
+			<li><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>
+			<li><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 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.
+			</ul>
 
 			See [[#random-simplify]] for how these values resolve.
 
@@ -2683,7 +2685,7 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 		}
 		</pre>
 
-		Depending on what <<random-cache-key>> you provide
+		Depending on what <<random-key>> you provide
 		in place of the ''???'',
 		you'll get significantly different behavior for the elements:
 
@@ -2768,7 +2770,7 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 		If you want the values to be completely uncorrelated,
 		give them distinct names (''--foo'' vs ''--bar'')
 		or mix in additional information that will uniquify their [=random cache names=]
-		(specifying ''--foo property-scoped'', or omitting the <<random-cache-key>> argument entirely)
+		(specifying ''--foo property-scoped'', or omitting the <<random-key>> argument entirely)
 	</div>
 
 	<details class=note id=auto-naming-details>
@@ -2830,7 +2832,7 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 	* Each instance of a [=random function=] in styles
 		has an associated <dfn>random base value</dfn>.
 
-		If the [=random function's=] <<random-cache-key>> is ''fixed <<number>>'',
+		If the [=random function's=] <<random-key>> is ''fixed <<number>>'',
 		the [=random base value=] is that number.
 
 		Otherwise, the [=random base value=] is a pseudo-random real number
@@ -2935,13 +2937,13 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 		the ''random()'' function isn't evaluated
 		(or even recognized *as* a ''random()'' function)
 		in ''--size'',
-		so the default rules for an omitted <<random-cache-key>> aren't applied.
+		so the default rules for an omitted <<random-key>> aren't applied.
 		Instead, it's evaluated when it's substituted into 'width' and 'height',
 		so each gets a distinct [=random cache name=],
 		and this ends up defining a random <em>rectangle</em>,
 		rather than a square.
 
-		Similarly, ''random()/element-scoped'' in the <<random-cache-key>>
+		Similarly, ''random()/element-scoped'' in the <<random-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--
@@ -2964,15 +2966,15 @@ Sharing (Or Not) Random Values: the <<random-cache-key>> value</h3>
 
 
 <h4 id=random-simplify>
-Random Simplification</h4>
+Simplification of <<random-key>></h4>
 
 	At parse time,
-	certain transformations are performed on the <<random-cache-key>> of a [=random function=]:
+	certain transformations are performed on the <<random-key>> of a [=random function=]:
 
-	* If the <<random-cache-key>> is ''auto'' (or omitted),
+	* If the <<random-key>> is ''auto'' (or omitted),
 		it's turned into ''element-scoped property-index-scoped''.
 		(And then subject to the below transformations.)
-	* If the <<random-cache-key>> contains ''property-scoped'' or ''property-index-scoped'',
+	* If the <<random-key>> contains ''property-scoped'' or ''property-index-scoped'',
 		that keyword is replaced by a <<random-ua-ident>>:
 		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
@@ -2983,7 +2985,7 @@ Random Simplification</h4>
 		before any canonicalization/reordering might occur
 		that could shuffle the values around.
 
-	If the <<random-cache-key>> contains a <<random-ua-ident>>,
+	If the <<random-key>> contains a <<random-ua-ident>>,
 	this must not be omitted in the serialization of the value,
 	even if this would normally be valid per the
 	[=serialize a CSS value|"shortest serialization principle"=].
@@ -2993,7 +2995,7 @@ Random Simplification</h4>
 		specifying ''margin: random(10px, 20px) random(10px, 20px)''
 		will cause the top and bottom margins to be one random value,
 		and the left and right margins to be another random value.
-		The omitted <<random-cache-key>>s get rewritten at parse-time
+		The omitted <<random-key>>s get rewritten at parse-time
 		to ''element-scoped ua-margin-1'' and ''element-scoped ua-margin-2'',
 		respectively,
 		before they expand into the 'margin' longhands.
@@ -3013,7 +3015,7 @@ Random Simplification</h4>
 	If a ''random()'' function can't be fully [=simplify a calculation tree|simplified=]
 	by [=computed value=] time,
 	then its arguments are maximally simplified,
-	and its <<random-cache-key>>
+	and its specified <<random-key>>
 	is replaced with ''fixed BASE'',
 	where <css>BASE</css> is the function's [=random base value=].