Editorial revision of the 'using variables' chapter.

Author: tabatkins

css-variables/Overview.html

@@ -448,22 +448,28 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Variables
   <h2 id=using-variables><span class=secno>3. </span> Using Variables: the
    data() function</h2>
 
-  <p>The value of a <a href="#data-property"><i>data property</i></a> may be
-   substituted into any other property (including other data properties) by
-   referencing it with the &lsquo;<code class=css>data()</code>&rsquo;
-   function, otherwise known as a <a
-   href="#type-variable"><i>variable</i></a>. The syntax of the &lsquo;<code
-   class=css>data()</code>&rsquo; function is:
+  <p>A <dfn id=variable>variable</dfn> allows the value of a <a
+   href="#data-property"><i>data property</i></a> on an element to be
+   substituted into another property on the element. Variables are used with
+   the &lsquo;<code class=css>data()</code>&rsquo; function, taking the name
+   of a variable and returning the value of the associated data property. The
+   syntax of the &lsquo;<code class=css>data()</code>&rsquo; function is:
 
   <pre><dfn id=type-variable
    title="variable|variables">&lt;variable></dfn> = data( IDENT )</pre>
 
   <p>The &lsquo;<code class=css>data()</code>&rsquo; function references the
-   <a href="#data-property"><i>data property</i></a> named when the "data-"
-   prefix is added to the argument to the function.
-
-  <p class=issue>Um, can you use a variable variable? Is &lsquo;<code
-   class=css>data(data(foo))</code>&rsquo; valid?
+   <a href="#data-property"><i>data property</i></a> with the name obtained
+   by prepending "data-" to the function's argument. <span class=note>Note
+   that all possible <a href="#data-property"><i>data properties</i></a>
+   exist; if one with the given name has not yet been defined in the
+   document, it simply takes its initial value.</span> When a property
+   resolves its computed value, a &lsquo;<code class=css>data()</code>&rsquo;
+   function is replaced by the value of the referenced <a
+   href="#data-property"><i>data property</i></a>.
+
+  <p class=issue>What about variable variables? Should &lsquo;<code
+   class=css>data(data(foo))</code>&rsquo; be valid? (Probably not.)
 
   <p>A variable can be used anywhere a value is expected in CSS. Variables
    can not be used as property names, selectors, or anything else besides
@@ -857,6 +863,7 @@ <h2 class=no-num id=index>Index</h2>
     </ul>
 
    <li>variable, <a href="#type-variable"
+    title=variable><strong>3.</strong></a>, <a href="#variable"
     title=variable><strong>3.</strong></a>
 
    <li>variables, <a href="#type-variable"

css-variables/Overview.src.html

@@ -210,13 +210,13 @@ <h2 id="defining-variables">
 <h2 id='using-variables'>
 Using Variables: the data() function</h2>
 
-	<p>The value of a <i>data property</i> may be substituted into any other property (including other data properties) by referencing it with the ''data()'' function, otherwise known as a <i>variable</i>.  The syntax of the ''data()'' function is:</p>
+	<p>A <dfn>variable</dfn> allows the value of a <i>data property</i> on an element to be substituted into another property on the element.  Variables are used with the ''data()'' function, taking the name of a variable and returning the value of the associated data property.  The syntax of the ''data()'' function is:</p>
 
 	<pre><dfn id='type-variable' title="variable|variables">&lt;variable></dfn> = data( IDENT )</pre>
 
-	<p>The ''data()'' function references the <i>data property</i> named when the "data-" prefix is added to the argument to the function.</p>
+	<p>The ''data()'' function references the <i>data property</i> with the name obtained by prepending "data-" to the function's argument.  <span class='note'>Note that all possible <i>data properties</i> exist; if one with the given name has not yet been defined in the document, it simply takes its initial value.</span>  When a property resolves its computed value, a ''data()'' function is replaced by the value of the referenced <i>data property</i>.</p>
 
-	<p class='issue'>Um, can you use a variable variable?  Is ''data(data(foo))'' valid?</p>
+	<p class='issue'>What about variable variables?  Should ''data(data(foo))'' be valid? (Probably not.)</p>
 
 	<p>A variable can be used anywhere a value is expected in CSS.  Variables can not be used as property names, selectors, or anything else besides property values - doing so either produces an invalid value or, in some situations like the attribute value of an attribute selector, a valid value that nonetheless has no relation to the variable of that name.</p>