Finish rewrite of 'Defining Variables' section to the new data-properties form.

Author: tabatkins

css-variables/Overview.html

@@ -22,14 +22,14 @@
 
    <h1>CSS Variables Module Level 1</h1>
 
-   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 26 October
+   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 27 October
     2011</h2>
 
    <dl>
     <dt>This version:
 
     <dd><a
-     href="http://www.w3.org/TR/2011/ED-css-variables-20111026/">http://dev.w3.org/csswg/css-variables/</a>
+     href="http://www.w3.org/TR/2011/ED-css-variables-20111027/">http://dev.w3.org/csswg/css-variables/</a>
      <!--<dt>Latest version:
 		<dd><a href="http://www.w3.org/TR/css-variables/">http://www.w3.org/TR/css-variables/</a>-->
 
@@ -208,18 +208,19 @@ <h2 id=intro><span class=secno>1. </span> Introduction</h2>
    across multiple files), and may not be amenable to Find-and-Replace.
 
   <p>This module introduces a family of custom user-defined properties known
-   collectively as <b>Variables</b>, which allow an author to assign values
-   to a property with an author-chosen name, and then use those values in
-   other properties elsewhere in the document. This makes it easier to read
-   large files, as seemingly-arbitrary values now have informative names, and
-   makes editting such files much easier and less error-prone, as one only
-   has to change the value once, at the variable definition site, and the
-   change will propagate to all uses of that variable automatically.
+   collectively as <a href="#data-property"><i>data properties</i></a>, which
+   allow an author to assign arbitrary values to a property with an
+   author-chosen name, and then use those values in other properties
+   elsewhere in the document. This makes it easier to read large files, as
+   seemingly-arbitrary values now have informative names, and makes editting
+   such files much easier and less error-prone, as one only has to change the
+   value once, at the variable definition site, and the change will propagate
+   to all uses of that variable automatically.
 
   <h3 id=placement><span class=secno>1.1. </span> Module Interactions</h3>
 
   <p>This module defines a new type of primitive value, the <a
-   href="#variable"><b>Variable</b></a>, which is accepted by all properties.
+   href="#variable"><i>variable</i></a>, which is accepted by all properties.
 
   <h3 id=values><span class=secno>1.2. </span> Values</h3>
 
@@ -286,7 +287,7 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Variables</h2>
   </table>
 
   <div class=example>
-   <p>This variables declaration:</p>
+   <p>This style rule:</p>
 
    <pre>
 :root {
@@ -309,89 +310,99 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Variables</h2>
     variable declaration.</p>
   </div>
 
-  <p class=issue>Finish replacing the rest of this section.
-
-  <p>Defined variables are available to all stylesheets in the document.
-   Thus, using &lsquo;<code class=css>@import</code>&rsquo; to include a
-   stylesheet also includes all variables defined in the stylesheet (and
-   makes all variables declared outside available within the stylesheet, if
-   applicable). &lsquo;<code class=css>@var</code>&rsquo; rules present in
-   disabled or alternate stylesheets do not define variables. Scoped
-   stylesheets are an exception to this: variables defined in the global
-   scope are available within a scoped stylesheet, but variables defined or
-   imported within scoped stylesheets are only available within the scoped
-   stylesheet and any imported stylesheets.
-
-  <p>A &lsquo;<code class=css>@var</code>&rsquo; rule is <dfn
-   id=inactive-var-rule>inactive</dfn> if it's present in a disabled or
-   alternate stylesheet, a stylesheet with a media query that evaluates to
-   false, or is present within a conditional rule group [[CSS3CONDITIONAL]]
-   whose condition evaluates to false. <a
-   href="#inactive-var-rule"><i>Inactive</i></a> &lsquo;<code
-   class=css>@var</code>&rsquo; rules do not define variables. All other
-   &lsquo;<code class=css>@var</code>&rsquo; rules are <dfn
-   id=active-var-rule>active</dfn>.
-
-  <p>If new &lsquo;<code class=css>@var</code>&rsquo; rules are added to the
-   document through any means, such as direct CSSOM manipulation or new
-   stylesheets being added to the document, or if an <a
-   href="#inactive-var-rule"><i>inactive</i></a> &lsquo;<code
-   class=css>@var</code>&rsquo; rule becomes <a
-   href="#active-var-rule"><i>active</i></a>, they define variables.
-   Similarly, if &lsquo;<code class=css>@var</code>&rsquo; rules are removed
-   from the document or become <a
-   href="#inactive-var-rule"><i>inactive</i></a>, they no longer define
-   variables.
+  <p>There is no restriction on the possible names for <a
+   href="#data-property"><i>data properties</i></a>, except that they must
+   start with "data-" and be a valid identifier like any other property name.
+   Data properties are ordinary properties, so they can be declared on any
+   element, are resolved with the normal inheritance and cascade rules, can
+   be made conditional with &lsquo;<code class=css>@media</code>&rsquo; and
+   other conditional rules, can be used in HTML's <code>style</code>
+   attribute, can be read or set using the CSSOM, etc..
+
+  <div class=example>
+   <p>If a variable is declared multiple times, the standard cascade rules
+    help resolve it:</p>
+
+   <pre>
+:root { data-color: blue; }
+div { data-color: green; }
+#alert { data-color: red; }
+* { color: data(color); }
+
+&lt;p>I'm blue!&lt;/p>
+&lt;div>I'm green!&lt;/div>
+&lt;div id='alert'>
+  And I'm red!
+  &lt;p>So am I, because of inheritance!&lt;/p>
+&lt;/div></pre>
+  </div>
 
-  <p>If multiple <a href="#active-var-rule"><i>active</i></a> &lsquo;<code
-   class=css>@var</code>&rsquo; rules attempt to define variables with the
-   same name, the last one defined wins; the preceding &lsquo;<code
-   class=css>@var</code>&rsquo; rules do not define a variable. For this
-   purpose, user-agent defined variable rules come before author-defined
-   variable rules, which come before user-defined variable rules, which come
-   before override variable rules. Within each of the preceding groups, the
-   ordering is document order.
+  <p><a href="#data-property"><i>Data properties</i></a> may use variables in
+   their own values to build up composite variables. This can create cyclic
+   dependencies where two or more variables attempt to use each other's
+   value; doing so makes all the data properties involved in the cycle define
+   <a href="#invalid-variable"><i>invalid variables</i></a> instead of the
+   values they had intended to define.
 
   <div class=example>
-   <p>Earlier declarations of the same variable have no effect, even if uses
-    of the variable come between the earlier and final attempts to define the
-    variable:</p>
+   <p>This example shows a variable safely depending on another:</p>
 
    <pre>
-@var $var red;
-p { color: $var; }
-@var $var blue;</pre>
+:root {
+	data-main-color: #c06;
+	data-accent-background: linear-gradient(to top, data(main-color), white);
+}</pre>
 
-   <p>In this example, the color of &lt;p> elements is blue, because the
-    second declaration wins over the first declaration in all uses.</p>
+   <p>The &lsquo;<code class=property>data-accent-background</code>&rsquo;
+    property will automatically update when the &lsquo;<code
+    class=property>data-main-color</code>&rsquo; property is changed.</p>
   </div>
 
-  <p>Variables can refer to other variables in their value. If a dependency
-   cycle is created, all the declarations that directly contribute to the
-   cycle define <a href="#invalid-variable"><i>invalid variables</i></a>.
+  <div class="example invalid-example">
+   <p>On the other hand, this example shows an invalid instance of variables
+    depending on each other:</p>
 
-  <div class=example>
-   <p>For example, the following set of variable declarations create a
-    dependency cycle:</p>
+   <pre>
+:root {
+	data-one: calc(data(two) + 20px);
+	data-two: calc(data(one) - 20px);
+}</pre>
+
+   <p>Both &lsquo;<code class=property>data-one</code>&rsquo; and
+    &lsquo;<code class=property>data-two</code>&rsquo; now define <a
+    href="#invalid-variable"><i>invalid variables</i></a> rather than
+    lengths.</p>
+  </div>
+
+  <div class=issue>
+   <p>Is it possible to do a "cyclic" dependency safely?</p>
 
    <pre>
-@var $foo red;
-@var $bar linear-gradient(transparent, $foo);
-@var $foo $bar;</pre>
-
-   <p>The last two declarations create the cycle, and so they define
-    &lsquo;<code class=css>$bar</code>&rsquo; and &lsquo;<code
-    class=css>$foo</code>&rsquo;, respectively, as <a
-    href="#invalid-variable"><i>invalid variables</i></a> instead of as the
-    values in the declarations. If the last rule were removed, however, there
-    would be no problem - &lsquo;<code class=css>$foo</code>&rsquo; would be
-    defined as &lsquo;<code class=css>red</code>&rsquo;, while &lsquo;<code
-    class=css>$bar</code>&rsquo; would be defined as &lsquo;<code
-    class=css>linear-gradient(transparent, red)</code>&rsquo;.</p>
+&lt;one>&lt;two>&lt;three />&lt;/two>&lt;/one>
+one   { data-foo: 10px; }
+two   { data-bar: calc(data(foo) + 10px); }
+three { data-foo: calc(data(bar) + 10px); }</pre>
+
+   <p>If I'm thinking correctly, one and two would get the value &lsquo;<code
+    class=css>10px</code>&rsquo; for &lsquo;<code
+    class=css>data(foo)</code>&rsquo;, but three overrides &lsquo;<code
+    class=property>data-foo</code>&rsquo; with a new definition. It gets the
+    *inherited* value of &lsquo;<code class=property>data-bar</code>&rsquo;,
+    which is &lsquo;<code class=css>calc(10px + 10px)</code>&rsquo; (or maybe
+    just &lsquo;<code class=css>20px</code>&rsquo; - &lsquo;<code
+    class=css>calc()</code>&rsquo; computed values aren't well defined yet),
+    so it seems like it validly sets &lsquo;<code
+    class=property>data-foo</code>&rsquo; to &lsquo;<code
+    class=css>30px</code>&rsquo;. Right?</p>
   </div>
 
-  <p>Before they are defined, all variables are <a
-   href="#invalid-variable"><i>invalid variables</i></a>.
+  <p>Variables can refer to other variables in their value. If a dependency
+   cycle is created, all the declarations that directly contribute to the
+   cycle define <a href="#invalid-variable"><i>invalid variables</i></a>.
+
+  <p>Before they are defined by a <a href="#data-property"><i>data
+   property</i></a>, all variables are <a href="#invalid-variable"><i>invalid
+   variables</i></a>.
 
   <h2 id=using-variables><span class=secno>3. </span> Using Variables</h2>
 
@@ -868,10 +879,10 @@ <h3 class=no-num id=normative-references>Normative references</h3>
    <dt id=CSS21>[CSS21]
 
    <dd>Bert Bos; et al. <a
-    href="http://www.w3.org/TR/2011/REC-CSS2-20110607/"><cite>Cascading Style
+    href="http://www.w3.org/TR/2011/REC-CSS2-20110607"><cite>Cascading Style
     Sheets Level 2 Revision 1 (CSS&#160;2.1) Specification.</cite></a> 7 June
     2011. W3C Recommendation. URL: <a
-    href="http://www.w3.org/TR/2011/REC-CSS2-20110607/">http://www.w3.org/TR/2011/REC-CSS2-20110607/</a>
+    href="http://www.w3.org/TR/2011/REC-CSS2-20110607">http://www.w3.org/TR/2011/REC-CSS2-20110607</a>
     </dd>
    <!---->
 
@@ -916,9 +927,9 @@ <h3 class=no-num id=other-references>Other references</h3>
    <dt id=CSS3COLOR>[CSS3COLOR]
 
    <dd>Tantek &#199;elik; Chris Lilley; L. David Baron. <a
-    href="http://www.w3.org/TR/2011/REC-css3-color-20110607/"><cite>CSS Color
+    href="http://www.w3.org/TR/2011/REC-css3-color-20110607"><cite>CSS Color
     Module Level 3.</cite></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>
+    href="http://www.w3.org/TR/2011/REC-css3-color-20110607">http://www.w3.org/TR/2011/REC-css3-color-20110607</a>
     </dd>
    <!---->
   </dl>
@@ -928,9 +939,6 @@ <h2 class=no-num id=index>Index</h2>
   <!--begin-index-->
 
   <ul class=indexlist>
-   <li>active, <a href="#active-var-rule"
-    title=active><strong>2.</strong></a>
-
    <li>authoring tool, <a href="#authoring-tool"
     title="authoring tool"><strong>6.2.</strong></a>
 
@@ -940,9 +948,6 @@ <h2 class=no-num id=index>Index</h2>
    <li>data property, <a href="#data-property"
     title="data property"><strong>2.</strong></a>
 
-   <li>inactive, <a href="#inactive-var-rule"
-    title=inactive><strong>2.</strong></a>
-
    <li>invalid at computed-value time, <a
     href="#invalid-at-computed-value-time"
     title="invalid at computed-value time"><strong>3.1.</strong></a>