[css-variables] Specify how variables interact with shorthand expansion/serialization.

Author: tabatkins

css-variables/Overview.html

@@ -12,7 +12,7 @@
 </a></p>
   <h1 class="p-name no-ref" id=title>CSS Custom Properties for Cascading Variables Module Level 1</h1>
   <h2 class="no-num no-toc no-ref heading settled heading" id=subtitle><span class=content>Editor’s Draft,
-    <span class=dt-updated><span class=value-title title=20130828>28 August 2013</span></span></span></h2>
+    <span class=dt-updated><span class=value-title title=20130829>29 August 2013</span></span></span></h2>
   <div data-fill-with=spec-metadata><dl><dt>This version:<dd><a class=u-url href=http://dev.w3.org/csswg/css-variables/>http://dev.w3.org/csswg/css-variables/</a><dt>Latest version:<dd><a href=http://www.w3.org/TR/css-variables-1/>http://www.w3.org/TR/css-variables-1/</a><dt>Editor’s Draft:<dd><a href=http://dev.w3.org/csswg/css-variables/>http://dev.w3.org/csswg/css-variables/</a><dt>Previous Versions:<dd><a href=http://www.w3.org/TR/2013/WD-css-variables-20130312/ rel=previous>http://www.w3.org/TR/2013/WD-css-variables-20130312/</a><dd><a href=http://www.w3.org/TR/2012/WD-css-variables-20120410/ rel=previous>http://www.w3.org/TR/2012/WD-css-variables-20120410/</a>
 <dt>Feedback:</dt>
     <dd><a href="mailto:www-style@w3.org?subject=%5Bcss-variables%5D%20feedback">www-style@w3.org</a>
@@ -72,7 +72,8 @@ <h2 class="no-num no-toc no-ref heading settled heading" id=contents><span class
 Using Custom Properties</a><li><a href=#cycles><span class=secno>2.3</span>
 Resolving Dependency Cycles</a></ul><li><a href=#using-variables><span class=secno>3</span>
 Using Cascading Variables: the <span class=css data-link-type=maybe>var()</span> notation</a><ul class=toc><li><a href=#invalid-variables><span class=secno>3.1</span>
-Invalid Variables</a></ul><li><a href=#cssom><span class=secno>4</span>
+Invalid Variables</a><li><a href=#variables-in-shorthands><span class=secno>3.2</span>
+Variables in Shorthand Properties</a></ul><li><a href=#cssom><span class=secno>4</span>
 APIs</a><ul class=toc><li><a href=#the-cssstyledeclaration-interface><span class=secno>4.1</span>
 Extensions to the <code>CSSStyleDeclaration</code> Interface</a><ul class=toc><li><a href=#serializing-custom-props><span class=secno>4.1.1</span>
 Serializing Custom Properties</a></ul><li><a href=#the-CSSVariablesMap-interface><span class=secno>4.2</span>
@@ -232,12 +233,12 @@ <h3 class="heading settled heading" data-level=2.1 id=syntax><span class=secno>2
 	like the enclosing style rule,
 	when reserialized.
 
-<p class=note>	Note: Custom properties can contain a trailing <span class=css data-link-type=maybe>!important</span>,
+<p class=note>	Note: Custom properties can contain a trailing <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-cascade-3/#important>!important</a>,
 	but this is automatically removed from the property’s value by the CSS parser,
 	and makes the custom property "important" in the CSS cascade.
 	In other words, the prohibition on top-level "!" characters
-	does not prevent <span class=css data-link-type=maybe>!important</span> from being used,
-	as the <span class=css data-link-type=maybe>!important</span> is removed before syntax checking happens.
+	does not prevent <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-cascade-3/#important>!important</a> from being used,
+	as the <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-cascade-3/#important>!important</a> is removed before syntax checking happens.
 
 <p class=note>	Note: While <a class=production data-link-type=type href=#typedef-any-value>&lt;any-value&gt;</a> must represent at least one token,
 	that one token may be whitespace.
@@ -612,6 +613,39 @@ <h3 class="heading settled heading" data-level=3.1 id=invalid-variables><span cl
 	so by the time the user agent realizes a property value is invalid,
 	it’s already thrown away the other cascaded values.
 
+<h3 class="heading settled heading" data-level=3.2 id=variables-in-shorthands><span class=secno>3.2 </span><span class=content>
+Variables in Shorthand Properties</span><a class=self-link href=#variables-in-shorthands></a></h3>
+
+<p>	The use of <a href=#cascading-variable>variables</a> in <a href=http://dev.w3.org/csswg/css-cascade-3/#shorthand-properties>shorthand properties</a> presents some unique difficulties.
+
+<p>	Ordinarily, the value of a shorthand property is separated out into its component <a href=http://dev.w3.org/csswg/css-cascade-3/#longhand-sub-properties>longhand properties</a> at parse time,
+	and then the longhands themselves participate in the <a href=http://dev.w3.org/csswg/css-cascade-3/#cascade>cascade</a>,
+	with the shorthand more-or-less discarded.
+	If a <a href=#cascading-variable>variable</a> 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 <a href=#cascading-variable>variable</a> may substitute in the value of several longhands at once.
+
+<p>	To get around this,
+	implementations must fill in longhands with a special, unobservable-to-authors <dfn data-dfn-type=dfn data-export="" id=pending-variable-substitution-value>pending variable-substitution value<a class=self-link href=#pending-variable-substitution-value></a></dfn>
+	that indicates the shorthand contains a variable,
+	and thus the longhand’s value is pending variable substitution.
+	This value must then be cascaded as normal,
+	and at computed-value time,
+	after <a href=#cascading-variable>variables</a> are finally substituted in,
+	the shorthand must be parsed and the longhands must be given their appropriate values at that point.
+
+<p>	<a href=#pending-variable-substitution-value>Pending variable-substitution values</a> must be serialized as the empty string,
+	if an API allows them to be observed.
+
+<p>	Similarly,
+	while <a data-biblio-type=informative data-link-type=biblio href=#cssom title=CSSOM>[CSSOM]</a> defines that shorthand properties are serialized
+	by appropriately concatenating the values of their corresponding longhands,
+	shorthands containing <a href=#cascading-variable>variables</a> must instead retain their original, <a class=css data-link-type=maybe href=#funcdef-var>var()</a>-containing, value.
+	If serializing a shorthand’s value would involve serializing a <a href=#pending-variable-substitution-value>pending variable-substitution value</a>,
+	the shorthand must instead be serialized by serializing its original value.
+
+
 <!--
                AAA               PPPPPPPPPPPPPPPPP   IIIIIIIIII
               A:::A              P::::::::::::::::P  I::::::::I
@@ -946,7 +980,7 @@ <h3 class="no-num no-ref heading settled heading" id=normative><span class=conte
 
 <h3 class="no-num no-ref heading settled heading" id=informative><span class=content>
 Informative References</span><a class=self-link href=#informative></a></h3>
-<div data-fill-with=informative-references><dl><dt id=css3color title=CSS3COLOR><a class=self-link href=#css3color></a>[CSS3COLOR]<dd>Tantek Çelik; Chris Lilley; L. David Baron. <a href=http://www.w3.org/TR/2011/REC-css3-color-20110607>CSS Color Module Level 3</a>. 7 June 2011. W3C Recommendation. URL: <a href=http://www.w3.org/TR/2011/REC-css3-color-20110607>http://www.w3.org/TR/2011/REC-css3-color-20110607</a></dl></div>
+<div data-fill-with=informative-references><dl><dt id=css3color title=CSS3COLOR><a class=self-link href=#css3color></a>[CSS3COLOR]<dd>Tantek Çelik; Chris Lilley; L. David Baron. <a href=http://www.w3.org/TR/2011/REC-css3-color-20110607>CSS Color Module Level 3</a>. 7 June 2011. W3C Recommendation. URL: <a href=http://www.w3.org/TR/2011/REC-css3-color-20110607>http://www.w3.org/TR/2011/REC-css3-color-20110607</a><dt id=cssom title=CSSOM><a class=self-link href=#cssom></a>[CSSOM]<dd>Anne van Kesteren. <a href=http://www.w3.org/TR/2011/WD-cssom-20110712/>CSSOM</a>. 12 July 2011. W3C Working Draft. (Work in progress.) URL: <a href=http://www.w3.org/TR/2011/WD-cssom-20110712/>http://www.w3.org/TR/2011/WD-cssom-20110712/</a></dl></div>
 
 <h2 class="no-num no-ref heading settled heading" id=index><span class=content>
 Index</span><a class=self-link href=#index></a></h2>
@@ -960,6 +994,7 @@ <h2 class="no-num no-ref heading settled heading" id=index><span class=content>
 <li>custom property, <a href=#custom-property title="section 2">2</a>
 <li>invalid at computed-value time, <a href=#invalid-at-computed-value-time title="section 3.1">3.1</a>
 <li>invalid variable, <a href=#invalid-variable title="section 3.1">3.1</a>
+<li>pending variable-substitution value, <a href=#pending-variable-substitution-value title="section 3.2">3.2</a>
 <li>resolve a variable, <a href=#resolve-a-variable title="section 3">3</a>
 <li>var(), <a href=#funcdef-var title="section 3">3</a>
 <li>variable, <a href=#cascading-variable title="section 2.2">2.2</a>

css-variables/Overview.src.html

@@ -576,14 +576,34 @@ <h3 id=variables-in-shorthands>
 
 	The use of <a>variables</a> in <a>shorthand properties</a> presents some unique difficulties.
 
-	Ordinarily, the value of a shorthand property is separated out into its component longhands at parse time,
+	Ordinarily, 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 <a>variable</a> 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 <a>variable</a> 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 variable-substitution value</dfn>
+	that indicates the shorthand contains a variable,
+	and thus the longhand's value is pending variable substitution.
+	This value must then be cascaded as normal,
+	and at computed-value time,
+	after <a>variables</a> are finally substituted in,
+	the shorthand must be parsed and the longhands must be given their appropriate values at that point.
+
+	<a>Pending variable-substitution values</a> 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 containing <a>variables</a> must instead retain their original, ''var()''-containing, value.
+	If serializing a shorthand's value would involve serializing a <a>pending variable-substitution value</a>,
+	the shorthand must instead be serialized by serializing its original value.
+
+
 <!--
                AAA               PPPPPPPPPPPPPPPPP   IIIIIIIIII
               A:::A              P::::::::::::::::P  I::::::::I