W3C home > Mailing lists > Public > public-css-commits@w3.org > October 2011

csswg/css-variables Overview.html,1.18,1.19 Overview.src.html,1.18,1.19

From: Tab Atkins Jr.. via cvs-syncmail <cvsmail@w3.org>
Date: Sun, 30 Oct 2011 17:36:14 +0000
To: public-css-commits@w3.org
Message-Id: <E1RKZIs-0006mF-Nj@lionel-hutz.w3.org>
Update of /sources/public/csswg/css-variables
In directory hutz:/tmp/cvs-serv26029

Modified Files:
	Overview.html Overview.src.html 
Log Message:
Rewrote the 'using variables' section to data properties.

Index: Overview.html
===================================================================
RCS file: /sources/public/csswg/css-variables/Overview.html,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- Overview.html	30 Oct 2011 16:46:40 -0000	1.18
+++ Overview.html	30 Oct 2011 17:36:12 -0000	1.19
@@ -131,7 +131,7 @@
     Variables With Data Properties</a>
 
    <li><a href="#using-variables"><span class=secno>3. </span> Using
-    Variables</a>
+    Variables: the data() function</a>
     <ul class=toc>
      <li><a href="#using-invalid-variables"><span class=secno>3.1. </span>
       Using Invalid Variables</a>
@@ -219,8 +219,9 @@
 
   <h3 id=placement><span class=secno>1.1. </span> Module Interactions</h3>
 
-  <p>This module defines a new type of primitive value, the <i>variable</i>,
-   which is accepted by all properties.
+  <p>This module defines a new type of primitive value, the <a
+   href="#type-variable"><i>variable</i></a>, which is accepted by all
+   properties.
 
   <h3 id=values><span class=secno>1.2. </span> Values</h3>
 
@@ -240,7 +241,7 @@
 
   <p>This specification defines an open-ended set of properties called <a
    href="#data-property"><i>data properties</i></a>, which are used to define
-   <i>variables</i>.
+   <a href="#type-variable"><i>variables</i></a>.
 
   <table class=propdef>
    <tbody>
@@ -274,7 +275,8 @@
     <tr>
      <th>Computed Value:
 
-     <td>specified value with variables substituted
+     <td>specified value with variables substituted (but see prose for
+      "invalid variables")
 
     <tr>
      <th>Media:
@@ -354,9 +356,8 @@
    dependencies where two or more <a href="#data-property"><i>data
    properties</i></a> each attempt to use the variable that the other
    defines; doing so makes all the <a href="#data-property"><i>data
-   properties</i></a> involved in the cycle define <a
-   href="#invalid-variable"><i>invalid variables</i></a> instead of the
-   values they had intended to define.
+   properties</i></a> involved in the cycle compute to their initial value
+   (which is a guaranteed-invalid value).
 
   <div class=example>
    <p>This example shows a data property safely using a variable:</p>
@@ -389,7 +390,8 @@
   </div>
 
   <p>It is important to note that <a href="#data-property"><i>data
-   properties</i></a> resolve any <i>variables</i> in their values at
+   properties</i></a> resolve any <a
+   href="#type-variable"><i>variables</i></a> in their values at
    computed-value time, which occurs <em>before</em> the value is inherited.
    In general, cyclic dependencies occur only when multiple data properties
    on the same element refer to each other; data properties defined on
@@ -455,7 +457,25 @@
     references a font named "invalid".</p>
   </div>
 
-  <h2 id=using-variables><span class=secno>3. </span> Using Variables</h2>
+  <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:
+
+  <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?
 
   <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
@@ -469,27 +489,13 @@
    href="#invalid-at-computed-value-time"><i>invalid at computed-value
    time</i></a>.
 
-  <div class=note>
-   <p>I'm not sure how to precisely define where/how variables can be used.
-    The Grammar section has a perfect definition, if only it weren't all
-    non-normative (because it's just extending the 2.1 grammar). I don't know
-    if 2.1 actually has a term for what is represented by the "term"
-    production in the 2.1 grammar.</p>
-
-   <p>Basically, though, variables are lexically substituted into the
-    property value, with restrictions on where they can appear as implied by
-    the Grammar section. You can't, for example, do something ridiculous like
-    &lsquo;<code class=css>@var $unit px; div { width: 20$unit;
-    }</code>&rsquo;.</p>
-  </div>
-
   <div class=example>
    <p>For example, the following usage is fine from a syntax standpoint, but
     results in nonsense when the variable is substituted in:</p>
 
    <pre>
-@var $looks-valid 20px;
-p { background-color: $looks-valid; }</pre>
+:root { data-looks-valid: 20px; }
+p { background-color: data(looks-valid); }</pre>
 
    <p>Since &lsquo;<code class=css>20px</code>&rsquo; is an invalid value for
     &lsquo;<code class=property>background-color</code>&rsquo;, this instance
@@ -501,13 +507,14 @@
   <h3 id=using-invalid-variables><span class=secno>3.1. </span> Using Invalid
    Variables</h3>
 
-  <p>An <dfn id=invalid-variable
-   title="invalid variable|invalid variables">invalid variable</dfn> results
-   from having variables directly or indirectly refer to themselves, or from
-   using an undefined variable. Using an <a
-   href="#invalid-variable"><i>invalid variable</i></a> in a property value
-   makes the declaration <a href="#invalid-at-computed-value-time"><i>invalid
-   at computed-value time</i></a>.
+  <p>When a data property has its initial value, a &lsquo;<code
+   class=css>data()</code>&rsquo; function referencing that property
+   represents an <dfn id=invalid-variable
+   title="invalid variable|invalid variables">invalid variable</dfn>. Using
+   an <a href="#invalid-variable"><i>invalid variable</i></a> in a property
+   value makes the declaration <a
+   href="#invalid-at-computed-value-time"><i>invalid at computed-value
+   time</i></a>.
 
   <p>A declaration that is <dfn id=invalid-at-computed-value-time>invalid at
    computed-value time</dfn> results from either using an <a
@@ -520,14 +527,14 @@
    <p>For example, in the following code:</p>
 
    <pre>
-@var $not-a-color 20px; 
+:root { data-not-a-color: 20px; }
 p { background-color: red; }
-p { background-color: $not-a-color; }</pre>
+p { background-color: data(not-a-color); }</pre>
 
    <p>the &lt;p> elements will have transparent backgrounds (the initial
     value for &lsquo;<code class=property>background-color</code>&rsquo;),
     rather than red backgrounds. The same would happen if the variable itself
-    was invalid (such as if it was part of a cycle) or undefined.</p>
+    was invalid.</p>
 
    <p>Note the difference between this and what happens if the author had
     just written &lsquo;<code class=css>background-color: 20px</code>&rsquo;
@@ -1018,8 +1025,14 @@
       title="style sheet, as conformance class"><strong>6.2.</strong></a>
     </ul>
 
+   <li>variable, <a href="#type-variable"
+    title=variable><strong>3.</strong></a>
+
    <li><a href="#variablerule"><code>VARIABLE_RULE</code></a>, <a
     href="#variablerule" title="VARIABLE_RULE"><strong>4.2.1.</strong></a>
+
+   <li>variables, <a href="#type-variable"
+    title=variables><strong>3.</strong></a>
   </ul>
   <!--end-index-->
 
@@ -1055,7 +1068,8 @@
 
      <td>yes
 
-     <td>specified value with variables substituted
+     <td>specified value with variables substituted (but see prose for
+      "invalid variables")
 
      <td>all
   </table>

Index: Overview.src.html
===================================================================
RCS file: /sources/public/csswg/css-variables/Overview.src.html,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- Overview.src.html	30 Oct 2011 16:46:48 -0000	1.18
+++ Overview.src.html	30 Oct 2011 17:36:12 -0000	1.19
@@ -102,7 +102,7 @@
 			<td>yes
 		<tr>
 			<th>Computed Value:
-			<td>specified value with variables substituted
+			<td>specified value with variables substituted (but see prose for "invalid variables")
 		<tr>
 			<th>Media:
 			<td>all
@@ -146,7 +146,7 @@
 &lt;/div></pre>
 	</div>
 
-	<p><i>Data properties</i> may use variables in their own values to build up composite variables.  This can create cyclic dependencies where two or more <i>data properties</i> each attempt to use the variable that the other defines; doing so makes all the <i>data properties</i> involved in the cycle define <i>invalid variables</i> instead of the values they had intended to define.</p>
+	<p><i>Data properties</i> may use variables in their own values to build up composite variables.  This can create cyclic dependencies where two or more <i>data properties</i> each attempt to use the variable that the other defines; doing so makes all the <i>data properties</i> involved in the cycle compute to their initial value (which is a guaranteed-invalid value).</p>
 
 	<div class='example'>
 		<p>This example shows a data property safely using a variable:</p>
@@ -205,24 +205,26 @@
 
 
 <h2 id='using-variables'>
-Using Variables</h2>
+Using Variables: the data() function</h2>
 
-	<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>
+	<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 variable is substituted for its value in the property value at computed-value time.  If a declaration, once all variables are substituted in, is invalid, the declaration is <i>invalid at computed-value time</i>.</p>
+	<pre><dfn id='type-variable' title="variable|variables">&lt;variable></dfn> = data( IDENT )</pre>
 
-	<div class='note'>
-		<p>I'm not sure how to precisely define where/how variables can be used.  The Grammar section has a perfect definition, if only it weren't all non-normative (because it's just extending the 2.1 grammar).  I don't know if 2.1 actually has a term for what is represented by the "term" production in the 2.1 grammar.</p>
+	<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>Basically, though, variables are lexically substituted into the property value, with restrictions on where they can appear as implied by the Grammar section.  You can't, for example, do something ridiculous like ''@var $unit px; div { width: 20$unit; }''.</p>
-	</div>
+	<p class='issue'>Um, can you use a variable variable?  Is ''data(data(foo))'' valid?</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>
+
+	<p>A variable is substituted for its value in the property value at computed-value time.  If a declaration, once all variables are substituted in, is invalid, the declaration is <i>invalid at computed-value time</i>.</p>
 
 	<div class='example'>
 		<p>For example, the following usage is fine from a syntax standpoint, but results in nonsense when the variable is substituted in:</p>
 
 		<pre>
-@var $looks-valid 20px;
-p { background-color: $looks-valid; }</pre>
+:root { data-looks-valid: 20px; }
+p { background-color: data(looks-valid); }</pre>
 
 		<p>Since ''20px'' is an invalid value for 'background-color', this instance of the property computes to 'transparent' (the initial value for 'background-color') instead.</p>
 	</div>
@@ -230,7 +232,7 @@
 <h3 id='using-invalid-variables'>
 Using Invalid Variables</h3>
 
-	<p>An <dfn title="invalid variable|invalid variables">invalid variable</dfn> results from having variables directly or indirectly refer to themselves, or from using an undefined variable.  Using an <i>invalid variable</i> in a property value makes the declaration <i>invalid at computed-value time</i>.</p>
+	<p>When a data property has its initial value, a ''data()'' function referencing that property represents an <dfn title="invalid variable|invalid variables">invalid variable</dfn>.  Using an <i>invalid variable</i> in a property value makes the declaration <i>invalid at computed-value time</i>.</p>
 
 	<p>A declaration that is <dfn>invalid at computed-value time</dfn> results from either using an <i>invalid variable</i> in a property value, or using a valid variable that produces an invalid declaration when it is substituted in.  When this happens, the declaration must compute to the property's initial value.</p>
 
@@ -238,11 +240,11 @@
 		<p>For example, in the following code:</p>
 
 		<pre>
-@var $not-a-color 20px; 
+:root { data-not-a-color: 20px; }
 p { background-color: red; }
-p { background-color: $not-a-color; }</pre>
+p { background-color: data(not-a-color); }</pre>
 
-		<p>the &lt;p> elements will have transparent backgrounds (the initial value for 'background-color'), rather than red backgrounds.  The same would happen if the variable itself was invalid (such as if it was part of a cycle) or undefined.</p>
+		<p>the &lt;p> elements will have transparent backgrounds (the initial value for 'background-color'), rather than red backgrounds.  The same would happen if the variable itself was invalid.</p>
 
 		<p>Note the difference between this and what happens if the author had just written ''background-color: 20px'' directly in their stylesheet - that would be a normal syntax error, which would cause the rule to be discarded, so the ''background-color: red'' rule would be used instead.</p>
 	</div>
Received on Sunday, 30 October 2011 17:36:16 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Sunday, 30 October 2011 17:36:17 GMT