[css-values-5] Clean up Arbitrary Substitution Function prose

Author: fantasai

css-values-5/Overview.bs

@@ -17,6 +17,7 @@ Inline Github Issues: no
 Default Highlight: css
 </pre>
 <pre class='link-defaults'>
+spec:css-color-4; type:property; text:color
 spec:css-values-4; type: dfn;
 	text: determine the type of a calculation
 	text: keyword
@@ -1259,11 +1260,6 @@ Conditional Value Selection: the ''if()'' notation</h3>
 	if no condition matches,
 	then the ''if()'' notation represents an empty token stream.
 
-	Note: [=Arbitrary substitution functions=] all resolve at [=computed value=] time;
-	therefore if the resulting property value is invalid,
-	it falls back to the property's [=initial value=]
-	rather than to an earlier value in the [=cascade=].
-
 	The ''if()'' notation syntax is defined as follows:
 
 	<pre class=prod>
@@ -2616,24 +2612,28 @@ Interpolating sizing keywords: the 'interpolate-size' property</h3>
 Appendix A: Arbitrary Substitution Functions</h2>
 
 	An <dfn export>arbitrary substitution function</dfn>
-	is a function that will,
+	is a [=functional notation=] that will,
 	when resolved,
-	substitute itself with other content
-	which is unknowable at parse time.
-
-	Specifically,
-	[=arbitrary substitution functions=] are allowed in <em>all properties</em>.
-	When present, the property must be assumed to be valid
-
-	[=Arbitrary substitution functions=] can be used in place of any part of a value
-	in any property on an element.
-	They can not be used as
-	property names,
-	selectors,
-	or anything else besides property values,
-	unless otherwise specified.
-
-	<wpt>
+	substitute itself with other values
+	that are potentially unknowable at parse time--
+	and must therefore be parsed while resolving its [=computed value=].
+
+	Note: Since [=arbitrary substitution functions=] resolve at [=computed value=] time,
+	if the resulting value after substitution is invalid,
+	the property falls back (essentially) to ''unset'' behavior,
+	rather than falling back to an earlier value in the [=cascade=]
+	the way declarations invalid at parse time do.
+	See [[#invalid-substitution]].
+
+	Unless otherwise specified,
+	[=arbitrary substitution functions=] can be used
+	in place of any part of any property's value
+	(including within other [=functional notations=]);
+	and are not valid in any other context.
+
+	ISSUE: Should any of these functions be valid in contexts outside of properties?
+
+	<wpt pathprefix="css/css-variables">
 	variable-external-font-face-01.html
 	variable-font-face-01.html
 	variable-font-face-02.html
@@ -2654,13 +2654,13 @@ Appendix A: Arbitrary Substitution Functions</h2>
 		for having an invalid property name.
 	</div>
 
-	If a property contains one or more [=arbitrary substitution functions=],
-	and those functions are syntactically valid,
-	the entire property's grammar must be assumed to be valid at parse time.
+	If a property value contains one or more [=arbitrary substitution functions=],
+	and those functions are themselves syntactically valid,
+	the entire value's grammar must be assumed to be valid at parse time.
 	It is only syntax-checked at computed-value time,
 	after [=arbitrary substitution=].
 
-	<wpt>
+	<wpt pathprefix="css/css-variables">
 	variable-reference-18.html
 	variable-reference-19.html
 	variable-reference-30.html
@@ -2669,12 +2669,12 @@ Appendix A: Arbitrary Substitution Functions</h2>
 	Each [=arbitrary substitution function=]
 	must define how to <dfn export>resolve an arbitrary substitution function</dfn>
 	for itself,
-	returning optional "result" and "fallback" values.
-	The "result" is used to replace the function
+	returning optional |result| and |fallback| values.
+	The |result| is used to replace the function
 	as long as it does not contain the [=guaranteed-invalid value=];
-	the "fallback" is used otherwise.
-	The "fallback" does not need to be resolved in any way;
-	[=substitution=] will handle that if it's actually used.
+	the |fallback| is used otherwise.
+	(The |fallback| does not need to be resolved in any way;
+	[=substitution=] will handle that if it's actually used.)
 
 	Note: See, for example, [=resolve a var() function=].
 
@@ -2712,7 +2712,7 @@ Appendix A: Arbitrary Substitution Functions</h2>
 			replace |value| with the [=guaranteed-invalid value=].
 	</div>
 
-	<wpt>
+	<wpt pathprefix="css/css-variables">
 	css-variable-change-style-001.html
 	css-variable-change-style-002.html
 	variable-declaration-01.html
@@ -2739,7 +2739,7 @@ Appendix A: Arbitrary Substitution Functions</h2>
 	variable-substitution-variable-declaration.html
 	</wpt>
 
-	<wpt title="CSSOM">
+	<wpt pathprefix="css/css-variables" title="CSSOM">
 	variable-reference-cssom.html
 	</wpt>
 
@@ -2787,7 +2787,7 @@ Appendix A: Arbitrary Substitution Functions</h2>
 		to enforce that they are separate tokens even when re-parsing.
 	</div>
 
-	<wpt>
+	<wpt pathprefix="css/css-variables">
 	variable-declaration-14.html
 	variable-declaration-53.html
 	variable-declaration-54.html
@@ -2796,15 +2796,15 @@ Appendix A: Arbitrary Substitution Functions</h2>
 	variable-reference-without-whitespace.html
 	</wpt>
 
-	In properties,
-	[=arbitrary substitution functions=] are [=substituted=] at computed-value time,
+	[=Arbitrary substitution functions=] are [=substituted=]
+	during style [=computed value|computation=],
 	before any other value transformations or introspection can occur.
 	If a property,
 	after [=substitution=],
 	does not match its declared grammar,
 	the declaration is <a>invalid at computed-value time</a>.
 
-	<wpt>
+	<wpt pathprefix="css/css-variables">
 	variable-declaration-16.html
 	variable-declaration-17.html
 	variable-declaration-18.html
@@ -2820,7 +2820,7 @@ Appendix A: Arbitrary Substitution Functions</h2>
 	(and possibly whitespace/comments),
 	its value is determined as if that keyword were its [=specified value=] all along.
 
-	<wpt>
+	<wpt pathprefix="css/css-variables">
 	whitespace-in-fallback-crash.html
 	wide-keyword-fallback-001.html
 	wide-keyword-fallback-002.html
@@ -2903,7 +2903,7 @@ Invalid Substitution</h3>
 		    as if the property's value had been specified as the ''unset'' keyword.
 	</dl>
 
-	<wpt>
+	<wpt pathprefix="css/css-variables">
 	variables-substitute-guaranteed-invalid.html
 	</wpt>
 
@@ -2965,7 +2965,7 @@ Substitution in Shorthand Properties</h3>
 	the shorthand must be parsed
 	and the longhands must be given their appropriate values at that point.
 
-	<wpt>
+	<wpt pathprefix="css/css-variables">
 	variable-reference-36.html
 	variable-reference-37.html
 	variable-reference-38.html
@@ -2985,7 +2985,7 @@ Substitution in Shorthand Properties</h3>
 	[=Pending-substitution values=] must be serialized as the empty string,
 	if an API allows them to be observed.
 
-	<wpt>
+	<wpt pathprefix="css/css-variables">
 	variable-definition-border-shorthand-serialize.html
 	vars-border-shorthand-serialize.html
 	</wpt>
@@ -3054,7 +3054,7 @@ Safely Handling Overly-Long Substitution</h3>
 	If an [=arbitrary substitution function=] would expand into a longer token stream than this limit,
 	it instead is replaced with the [=guaranteed-invalid value=].
 
-	<wpt>
+	<wpt pathprefix="css/css-variables">
 	long-variable-reference-crash.html
 	variable-exponential-blowup.html
 	</wpt>