Merge branch 'master' of https://github.com/w3c/csswg-drafts

Author: Jihye Hong

css-variables-1/Overview.bs

@@ -131,60 +131,6 @@ Defining Custom Properties: the '--*' family of properties</h2>
 	It's expected that the CSS Extensions spec [[CSS-EXTENSIONS]]
 	will expand on these use-cases and make them easier to do.
 
-<h3 id='syntax'>
-Custom Property Value Syntax</h3>
-
-	The allowed syntax for <a>custom properties</a> is extremely permissive.
-	The <<declaration-value>> production matches <em>any</em> sequence of one or more tokens,
-	so long as the sequence does not contain
-	<<bad-string-token>>,
-	<<bad-url-token>>,
-	unmatched <<)-token>>, <<]-token>>, or <<}-token>>,
-	or top-level <<semicolon-token>> tokens or <<delim-token>> tokens with a value of "!".
-
-	In addition, if the value of a <a>custom property</a> contains a ''var()'' reference,
-	the ''var()'' reference must be valid according to the specified ''var()'' grammar.
-	If not, the <a>custom property</a> is invalid and must be ignored.
-
-	Note: This definition,
-	along with the general CSS syntax rules,
-	implies that a custom property value never includes an unmatched quote or bracket,
-	and so cannot have any effect on larger syntax constructs,
-	like the enclosing style rule,
-	when reserialized.
-
-	Note: Custom properties can contain a trailing ''!important'',
-	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 ''!important'' from being used,
-	as the ''!important'' is removed before syntax checking happens.
-
-	<div class='example'>
-		For example, the following is a valid custom property:
-
-		<pre>
-		--foo: if(x > 5) this.width = 10;
-		</pre>
-
-		While this value is obviously useless as a <em>variable</em>,
-		as it would be invalid in any normal property,
-		it might be read and acted on by JavaScript.
-	</div>
-
-	The values of custom properties,
-	and the values of ''var()'' functions substituted into custom properties,
-	are <em>case-sensitive</em>,
-	and must be preserved in their original author-given casing.
-	(Many CSS values are <a>ASCII case-insensitive</a>,
-	which user agents can take advantage of by "canonicalizing" them into a single casing,
-	but that isn't allowed for custom properties.)
-
-	The initial value of a <a>custom property</a> is an empty value;
-	that is, nothing at all.
-	This initial value has a special interaction with the ''var()'' notation,
-	which is explained in the section defining ''var()''.
-
 	Custom properties are ordinary properties,
 	so they can be declared on any element,
 	are resolved with the normal inheritance and cascade rules,
@@ -262,6 +208,55 @@ Custom Property Value Syntax</h3>
 		to make maintaining the translations simpler.
 	</div>
 
+<h3 id='syntax'>
+Custom Property Value Syntax</h3>
+
+	The allowed syntax for <a>custom properties</a> is extremely permissive.
+	The <<declaration-value>> production matches <em>any</em> sequence of one or more tokens,
+	so long as the sequence does not contain
+	<<bad-string-token>>,
+	<<bad-url-token>>,
+	unmatched <<)-token>>, <<]-token>>, or <<}-token>>,
+	or top-level <<semicolon-token>> tokens or <<delim-token>> tokens with a value of "!".
+
+	In addition, if the value of a <a>custom property</a> contains a ''var()'' reference,
+	the ''var()'' reference must be valid according to the specified ''var()'' grammar.
+	If not, the <a>custom property</a> is invalid and must be ignored.
+
+	Note: This definition,
+	along with the general CSS syntax rules,
+	implies that a custom property value never includes an unmatched quote or bracket,
+	and so cannot have any effect on larger syntax constructs,
+	like the enclosing style rule,
+	when reserialized.
+
+	Note: Custom properties can contain a trailing ''!important'',
+	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 ''!important'' from being used,
+	as the ''!important'' is removed before syntax checking happens.
+
+	<div class='example'>
+		For example, the following is a valid custom property:
+
+		<pre>
+		--foo: if(x > 5) this.width = 10;
+		</pre>
+
+		While this value is obviously useless as a <em>variable</em>,
+		as it would be invalid in any normal property,
+		it might be read and acted on by JavaScript.
+	</div>
+
+	The values of custom properties,
+	and the values of ''var()'' functions substituted into custom properties,
+	are <em>case-sensitive</em>,
+	and must be preserved in their original author-given casing.
+	(Many CSS values are <a>ASCII case-insensitive</a>,
+	which user agents can take advantage of by "canonicalizing" them into a single casing,
+	but that isn't allowed for custom properties.)
+
 <h3 id='guaranteed-invalid'>
 Guaranteed-Invalid Values</h3>
 
@@ -272,7 +267,7 @@ Guaranteed-Invalid Values</h3>
 
 	This value serializes as the empty string,
 	but actually writing an empty value into a custom property,
-	like ''--foo: ;'',
+	like <nobr>''--foo: ;''</nobr>,
 	is a valid (empty) value,
 	not the [=guaranteed-invalid value=].
 	If, for whatever reason,
@@ -337,8 +332,9 @@ Resolving Dependency Cycles</h3>
 		}
 		</pre>
 
-		Both '--one' and '--two' now compute to their initial value,
-		rather than lengths.
+		Both '--one' and '--two' are now [=cyclic at computed-value time=],
+		and compute to the [=guaranteed-invalid value=]
+		rather than than lengths.
 	</div>
 
 	It is important to note that
@@ -354,12 +350,14 @@ Resolving Dependency Cycles</h3>
 		these custom properties are <strong>not</strong> cyclic,
 		and all define valid variables:
 
-		<pre>
-		&lt;one>&lt;two>&lt;three />&lt;/two>&lt;/one>
-		one   { --foo: 10px; }
-		two   { --bar: calc(var(--foo) + 10px); }
-		three { --foo: calc(var(--bar) + 10px); }
-		</pre>
+		<xmp highlight=markup>
+			<one><two><three /></two></one>
+			<style>
+			one   { --foo: 10px; }
+			two   { --bar: calc(var(--foo) + 10px); }
+			three { --foo: calc(var(--bar) + 10px); }
+			</style>
+		</xmp>
 
 		The &lt;one> element defines a value for '--foo'.
 		The &lt;two> element inherits this value,
@@ -441,7 +439,8 @@ Using Cascading Variables: the ''var()'' notation</h2>
 	The first argument to the function is the name of the <a>custom property</a> to be substituted.
 	The second argument to the function, if provided,
 	is a fallback value,
-	which is used as the substitution value when the referenced <a>custom property</a> is invalid.
+	which is used as the substitution value when the value of the referenced <a>custom property</a>
+	is the [=guaranteed-invalid value=].
 
 	Note: The syntax of the fallback, like that of <a>custom properties</a>, allows commas.
 	For example, ''var(--foo, red, blue)'' defines a fallback of ''red, blue'';
@@ -544,7 +543,7 @@ Using Cascading Variables: the ''var()'' notation</h2>
 	''var()'' functions are <a lt="substitute a var()">substituted</a> at computed-value time.
 	If a declaration,
 	once all ''var()'' functions are substituted in,
-	is invalid,
+	does not match its declared grammar,
 	the declaration is <a>invalid at computed-value time</a>.
 
 	<div class='example'>
@@ -572,14 +571,14 @@ Using Cascading Variables: the ''var()'' notation</h2>
 <h3 id='invalid-variables'>
 Invalid Variables</h3>
 
-	When a <a>custom property</a> has its initial value,
+	When a <a>custom property’s</a> value is the [=guaranteed-invalid value=],
 	''var()'' functions cannot use it for substitution.
 	Attempting to do so
 	makes the declaration <a>invalid at computed-value time</a>,
 	unless a valid fallback is specified.
 
 	A declaration can be <dfn export>invalid at computed-value time</dfn>
-	if it contains a ''var()'' that references a <a>custom property</a> with its initial value,
+	if it contains a ''var()'' that references a <a>custom property</a> with the [=guaranteed-invalid value=],
 	as explained above,
 	or if it uses a valid <a>custom property</a>,
 	but the property value,
@@ -764,16 +763,15 @@ Changes since the May 6 2014 Last Call Working Draft</h2>
 <h2 id="acks">
 Acknowledgments</h2>
 
-	<p>
-		Many thanks to several people in the CSS Working Group for keeping the dream of variables alive over the years,
-		particularly Daniel Glazman and David Hyatt.
-		Thanks to multiple people on the mailing list for helping contribute to the development of this incarnation of variables,
-		particularly
-		Brian Kardell,
-		David Baron,
-		François Remy,
-		Roland Steiner,
-		and Shane Stephens.
+	Many thanks to several people in the CSS Working Group for keeping the dream of variables alive over the years,
+	particularly Daniel Glazman and David Hyatt.
+	Thanks to multiple people on the mailing list for helping contribute to the development of this incarnation of variables,
+	particularly
+	Brian Kardell,
+	David Baron,
+	François Remy,
+	Roland Steiner,
+	and Shane Stephens.
 
 Privacy and Security Considerations {#priv-sec}
 ===============================================