[css-variables] Move examples to more appropriate places. Fixes w3c#462.

Author: tabatkins

css-variables/Overview.bs

@@ -15,6 +15,7 @@ Previous Version: https://www.w3.org/TR/2013/WD-css-variables-20130312/
 Previous Version: https://www.w3.org/TR/2012/WD-css-variables-20120410/
 Editor: Tab Atkins Jr., Google, http://xanthir.com/contact
 Abstract: This module introduces cascading variables as a new primitive value type that is accepted by all CSS properties, and custom properties for defining them.
+Default Highlight: css
 </pre>
 
 <pre class=link-defaults>
@@ -239,11 +240,11 @@ Custom Property Value Syntax</h3>
 		#alert { --color: red; }
 		* { color: var(--color); }
 
-		&lt;p>I inherited blue from the root element!&lt;/p>
-		&lt;div>I got green set directly on me!&lt;/div>
+		&lt;p><span style="color: blue">I inherited blue from the root element!</span>&lt;/p>
+		&lt;div><span style="color: green">I got green set directly on me!</span>&lt;/div>
 		&lt;div id='alert'>
-			While I got red set directly on me!
-			&lt;p>I'm red too, because of inheritance!&lt;/p>
+			<span style="color: red">While I got red set directly on me!</span>
+			&lt;p><span style="color: red">I'm red too, because of inheritance!</span>&lt;/p>
 		&lt;/div>
 		</pre>
 	</div>
@@ -401,6 +402,21 @@ Using Cascading Variables: the ''var()'' notation</h2>
 	(Doing so usually produces invalid syntax,
 	or else a value whose meaning has no connection to the variable.)
 
+	<div class='example'>
+		For example, the following code incorrectly attempts to use a variable as a property name:
+
+		<pre>
+		.foo {
+			--side: margin-top;
+			var(--side): 20px;
+		}
+		</pre>
+
+		This is <em>not</em> equivalent to setting ''margin-top: 20px;''.
+		Instead, the second declaration is simply thrown away as a syntax error
+		for having an invalid property name.
+	</div>
+
 	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,
@@ -410,38 +426,6 @@ Using Cascading Variables: the ''var()'' notation</h2>
 	For example, ''var(--foo, red, blue)'' defines a fallback of ''red, blue'';
 	that is, anything between the first comma and the end of the function is considered a fallback value.
 
-	If a property contains one or more ''var()'' functions,
-	and those functions are syntactically valid,
-	the entire property's grammar must be assumed to be valid at parse time.
-	It is only syntax-checked at computed-value time,
-	after ''var()'' functions have been <a lt="substitute a var()">substituted</a>.
-
-	To <dfn export>substitute a var()</dfn> in a property's value:
-
-	<ol>
-		<li>
-			If the <a>custom property</a> named by the first argument to the ''var()'' function is <a>animation-tainted</a>,
-			and the ''var()'' function is being used in the 'animation' property or one of its longhands,
-			treat the <a>custom property</a> as having its initial value for the rest of this algorithm.
-
-		<li>
-			If the value of the <a>custom property</a> named by the first argument to the ''var()'' function
-			is anything but the initial value,
-			replace the ''var()'' function by the value of the corresponding <a>custom property</a>.
-
-		<li>
-			Otherwise, if the ''var()'' function has a fallback value as its second argument,
-			replace the ''var()'' function by the fallback value.
-			If there are any ''var()'' references in the fallback,
-			<a lt="substitute a var()">substitute</a> them as well.
-
-		<li>
-			Otherwise,
-			the property containing the ''var()'' function is <a>invalid at computed-value time</a>.
-
-			Note: Other things can also make a property <a>invalid at computed-value time</a>.
-	</ol>
-
 	<div class='example'>
 		The fallback value allows for some types of defensive coding.
 		For example,
@@ -475,21 +459,42 @@ Using Cascading Variables: the ''var()'' notation</h2>
 		</pre>
 	</div>
 
-	<div class='example'>
-		For example, the following code incorrectly attempts to use a variable as a property name:
+	If a property contains one or more ''var()'' functions,
+	and those functions are syntactically valid,
+	the entire property's grammar must be assumed to be valid at parse time.
+	It is only syntax-checked at computed-value time,
+	after ''var()'' functions have been <a lt="substitute a var()">substituted</a>.
 
-		<pre>
-		.foo {
-			--side: margin-top;
-			var(--side): 20px;
-		}
-		</pre>
+	To <dfn export lt="substitute a var()|var() substitution">substitute a var()</dfn> in a property's value:
 
-		This is <em>not</em> equivalent to setting ''margin-top: 20px;''.
-		Instead, the second declaration is simply thrown away as a syntax error
-		for having an invalid property name.
+	<ol>
+		<li>
+			If the <a>custom property</a> named by the first argument to the ''var()'' function is <a>animation-tainted</a>,
+			and the ''var()'' function is being used in the 'animation' property or one of its longhands,
+			treat the <a>custom property</a> as having its initial value for the rest of this algorithm.
+
+		<li>
+			If the value of the <a>custom property</a> named by the first argument to the ''var()'' function
+			is anything but the initial value,
+			replace the ''var()'' function by the value of the corresponding <a>custom property</a>.
+
+		<li>
+			Otherwise, if the ''var()'' function has a fallback value as its second argument,
+			replace the ''var()'' function by the fallback value.
+			If there are any ''var()'' references in the fallback,
+			<a lt="substitute a var()">substitute</a> them as well.
+
+		<li>
+			Otherwise,
+			the property containing the ''var()'' function is <a>invalid at computed-value time</a>.
+
+			Note: Other things can also make a property <a>invalid at computed-value time</a>.
+	</ol>
 
-		Similarly, you can't build up a single token where part of it is provided by a variable:
+	<div class=note>
+		Note that <a>var() substitution</a> takes place at the level of CSS tokens [[css-syntax-3]],
+		not at a textual level;
+		you can't build up a single token where part of it is provided by a variable:
 
 		<pre>
 		.foo {
@@ -498,7 +503,7 @@ Using Cascading Variables: the ''var()'' notation</h2>
 		}
 		</pre>
 
-		Again, this is <em>not</em> equivalent to setting ''margin-top: 20px;'' (a length).
+		This is <em>not</em> equivalent to setting ''margin-top: 20px;'' (a length).
 		Instead, it's equivalent to ''margin-top: 20 px;'' (a number followed by an ident),
 		which is simply an invalid value for the 'margin-top' property.
 		Note, though, that ''calc()'' can be used to validly achieve the same thing, like so: