[css-values-5] Added ability to upgrade commas to semicolons. w3c#9539

Author: tabatkins

css-values-5/Overview.bs

@@ -48,6 +48,106 @@ Textual Data Types</h2>
 
 	See [[css-values-4#textual-values]].
 
+
+<!-- Big Text: syntax
+
+ ███▌  █   ▐▌ █    █▌ █████▌  ███▌  █     █
+█▌  █▌ ▐▌  █  █▌   █▌   █▌   ▐█ ▐█   █   █
+█▌      █ ▐▌  ██▌  █▌   █▌   █▌  █▌   █ █
+ ███▌   ▐▌█   █▌▐█ █▌   █▌   █▌  █▌    █
+    █▌   █▌   █▌  ██▌   █▌   █████▌   █ █
+█▌  █▌   █▌   █▌   █▌   █▌   █▌  █▌  █   █
+ ███▌    █▌   █▌   ▐▌   █▌   █▌  █▌ █     █
+-->
+
+<h2 id=value-defs>
+Value Definition Syntax</h2>
+
+	See [[css-values-4#value-defs]].
+
+<h3 id=component-functions>
+Functional Notation Definitions</h3>
+
+	See [[css-values-4#component-functions]].
+
+<h4 id=component-function-commas>
+Commas and Semicolons in Functions</h4>
+
+	[=Functional notation=] often uses commas
+	to separate parts of its internal grammar.
+	However, some functions
+	(such as ''mix()'')
+	allow values that, themselves,
+	can contain commas.
+
+	To accommodate these sorts of grammars unambiguously,
+	commas in functional grammars are <em>implicitly upgradeable</em> to semicolons in Level 5;
+	that is,
+	commas in a [=functional notation=]'s grammar
+	can instead be represented as <<semicolon-token>>s.
+	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.
+
+	Commas contained in productions defined as <dfn>comma-containing productions</dfn>
+	(such as <<any-value>> or <<whole-value>>)
+	are not implicitly upgradeable.
+	Even when a [=functional notation=] is being re-interpreted with semicolons,
+	these productions end when a <<semicolon-token>> is encountered.
+
+	<div class="example">
+		The following examples are both equivalent declarations:
+
+		<pre>
+			list-style: toggle(disc, circle, square);
+			list-style: toggle(disc; circle; square);
+		</pre>
+
+		however, this is different (and invalid):
+
+		<pre>
+			list-style: toggle(disc, circle; square);
+		</pre>
+
+		because it represents toggling 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.
+		For example, in 'font-family':
+
+		<pre>
+			font-family: random-item(Times, serif; Arial, sans-serif; Courier, monospace);
+		</pre>
+
+		This randomly chooses one of three font-family lists:
+		either ''Times, serif'', or ''Arial, sans-serif'', or ''Courier, monospace''.
+		But if only single fonts were needed for each choice,
+		commas <em>could</em> have been used to separate them:
+
+		<pre>
+		font-family: random-item(serif, sans-serif, monospace);
+		</pre>
+
+	</div>
+
+	[=Functional notations=] are serialized with commas (rather than semicolons) whenever possible.
+
+	The following generic productions are [=comma-containing productions=]:
+
+	* <<any-value>>
+	* <<whole-value>>
+	* <<declaration-value>>
+
+	Issue: The functions defined in this spec with semicolons in their grammar
+	need fixing to just use commas, now.
+
 <!-- Big Text: url
 
 █▌  █▌ ████▌  █▌