[css-variables-1][editorial] Editorial rewrite of the shorthand parsing/serialization text. No normative change intended.

Author: tabatkins

css-variables-1/Overview.bs

@@ -753,38 +753,50 @@ Invalid Variables</h3>
 <h3 id=variables-in-shorthands>
 Variables in Shorthand Properties</h3>
 
-	The use of ''var()'' functions in <a>shorthand properties</a> presents some unique difficulties.
-
-	For non-custom properties,
-	the value of a shorthand property is separated out into its component <a>longhand properties</a> at parse time,
-	and then the longhands themselves participate in the <a>cascade</a>,
-	with the shorthand more-or-less discarded.
-	If a ''var()'' functions is used in a shorthand, however,
-	one can't tell what values are meant to go where;
-	it may in fact be impossible to separate it out at parse time,
-	as a single ''var()'' function may substitute in the value of several longhands at once.
-
-	To get around this,
-	implementations must fill in longhands with a special, unobservable-to-authors <dfn export>pending-substitution value</dfn>
+	''var()'' functions produce some complications
+	when parsing [=shorthand properties=] into their component longhands,
+	and when serializing [=shorthand properties=] <em>from</em> their component longhands.
+
+	If a [=shorthand property=] contains a ''var()'' function in its value,
+	the [=longhand properties=] it's associated with must instead be filled in
+	with a special, unobservable-to-authors <dfn export>pending-substitution value</dfn>
 	that indicates the shorthand contains a variable,
-	and thus the longhand's value is pending variable substitution.
+	and thus the longhand's value can't be determined until variables are [=substituted=].
+
 	This value must then be cascaded as normal,
 	and at computed-value time,
 	after ''var()'' functions are finally substituted in,
 	the shorthand must be parsed and the longhands must be given their appropriate values at that point.
 
-	<a>Pending-substitution values</a> must be serialized as the empty string,
+	Note: When a shorthand is written without a ''var()'',
+	it is parsed and separated out into its component [=longhand properties=] at parse time;
+	the longhands then participate in the [=cascade=],
+	with the [=shorthand property=] more or less discarded.
+	When the shorthand contains a ''var()'', however,
+	this can't be done,
+	as the ''var()'' could be substituted with anything.
+
+	[=Pending-substitution values=] must be serialized as the empty string,
 	if an API allows them to be observed.
 
-	Similarly,
-	while [[CSSOM]] defines that shorthand properties are serialized
-	by appropriately concatenating the values of their corresponding longhands,
-	shorthands that are specified with explicit ''var()'' functions
-	must serialize to the original, ''var()''-containing value.
-	For other shorthands,
-	if any of the longhand subproperties for that shorthand have <a>pending-substitution values</a>
-	then the serialized value of the shorthand must be the empty string.
+	----
+
+	[=Shorthand properties=] are serialized
+	by gathering the values of their component [=longhand properties=],
+	and synthesizing a value
+	that will parse into the same set of values.
+
+	If all of the component [=longhand properties=] for a given [=shorthand=]
+	are [=pending-substitution values=]
+	from the same original shorthand value,
+	the [=shorthand property=] must serialize to that original
+	(''var()''-containing)
+	value.
 
+	Otherwise,
+	if any of the component [=longhand properties=] for a given [=shorthand=]
+	are [=pending-substitution values=],
+	the [=shorthand property=] must serialize to the empty string.
 
 <!--
 ████████  ███████   ███████          ██        ███████  ██    ██  ██████