[css-values-5] Rewrite the comma/semicolon rules a little for clarity.

Author: tabatkins

css-values-5/Overview.bs

@@ -89,11 +89,16 @@ Commas and Semicolons in Functions</h4>
 	This is all-or-nothing:
 	either every comma in the [=functional notation=] must be written as a semicolon,
 	or none of them must be.
-	When the [=functional notation=]’s arguments are parsed,
-	initially commas in the grammar match only <<comma-token>>s;
-	if a <<semicolon-token>> is encountered,
-	then the [=functional notation=] is re-interpreted
-	with all commas in the grammar replaced by <<semicolon-token>>s.
+
+	When a [=functional notation=] is parsed,
+	initially commas (<css>,</css>) and comma-multipliers (<css>#</css>)
+	in the grammar match only <<comma-token>>s in the value,
+	and any [=comma-containing productions=] are not allowed to contain <<comma-token>>s
+	(the productions must be interpreted as ending before the comma).
+	If a <<semicolon-token>> is encountered while parsing the [=functional notation=],
+	the contents must be <em>re-interpreted</em>,
+	with commas and comma-multipliers in the grammar matching only <<semicolon-token>>s in the value,
+	and [=comma-containing productions=] being allowed to contain <<comma-token>>s.
 
 	Commas contained in productions defined as <dfn>comma-containing productions</dfn>
 	(such as <<any-value>> or <<whole-value>>)
@@ -102,29 +107,47 @@ Commas and Semicolons in Functions</h4>
 	these productions end when a <<semicolon-token>> is encountered.
 
 	<div class="example">
-		The following examples are both equivalent declarations:
+		For example, the grammar of the ''random-item()'' function is:
+
+		<pre>
+			random-item( <<random-caching-options>>, [<<declaration-value>>?]# )
+		</pre>
+
+		The ''#'' indicates comma-separated repetitions,
+		so randomly choosing between three keywords
+		would be written as normal for functions,
+		like:
+
+		<pre>
+			list-style: random-item(--x, disc, circle, square);
+		</pre>
+
+		It is <em>allowed</em>, however,
+		to "upgrade" the commas to semicolons,
+		like:
 
 		<pre>
-			list-style: toggle(disc, circle, square);
-			list-style: toggle(disc; circle; square);
+			list-style: random-item(--x; disc; circle; square);
 		</pre>
 
-		however, this is different (and invalid):
+		Both of the above mean the exact same thing.
+		However, mixing commas and semicolons does not work;
+		the following can produce an invalid value after substitution:
 
 		<pre>
-			list-style: toggle(disc, circle; square);
+			list-style: random-item(--x; disc, circle; square);
 		</pre>
 
-		because it represents toggling between two values
+		because it represents choosing between two values
 		(<css>disc, circle</css> and <css>square</css>)
 		and <css>disc, circle</css> is not a valid 'list-style' value.
 
-		This ability is important,
-		because sometimes [=functional notation=] arguments need to include commas.
+		However, sometimes the values you want to choose between
+		need to include commas.
 		For example, in 'font-family':
 
 		<pre>
-			font-family: random-item(Times, serif; Arial, sans-serif; Courier, monospace);
+			font-family: random-item(--x; Times, serif; Arial, sans-serif; Courier, monospace);
 		</pre>
 
 		This randomly chooses one of three font-family lists:
@@ -133,7 +156,7 @@ Commas and Semicolons in Functions</h4>
 		commas <em>could</em> have been used to separate them:
 
 		<pre>
-		font-family: random-item(serif, sans-serif, monospace);
+			font-family: random-item(--x, serif, sans-serif, monospace);
 		</pre>
 
 	</div>