[css-variables] Rewrite the 'using variables' section to only have var().

Author: tabatkins

css-variables/Overview.html

@@ -22,15 +22,15 @@
 
    <h1>CSS Variables Module Level 1</h1>
 
-   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 23 August 2012</h2>
+   <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 24 August 2012</h2>
 
    <dl>
     <dt>This version:
-     <!--<dd><a href="http://www.w3.org/TR/2012/WD-css-variables-20120823/">http://www.w3.org/TR/2012/ED-css-variables-20120823/</a>-->
+     <!--<dd><a href="http://www.w3.org/TR/2012/WD-css-variables-20120824/">http://www.w3.org/TR/2012/ED-css-variables-20120824/</a>-->
 
 
     <dd><a href="http://dev.w3.org/csswg/css-variables/">Editor's draft</a>
-     (version of 23 August 2012)
+     (version of 24 August 2012)
 
     <dt>Latest version:
 
@@ -143,23 +143,11 @@ <h2 class="no-num no-toc" id=contents>Table of contents</h2>
    <li><a href="#using-variables"><span class=secno>3. </span> Using
     Variables - the ‘<code class=css>var()</code>’ notation</a>
     <ul class=toc>
-     <li><a href="#parent-var-notation"><span class=secno>3.1. </span>
-      Getting the Parent's Variable - the ‘<code
-      class=css>parent-var()</code>’ notation</a>
-
-     <li><a href="#using-invalid-variables"><span class=secno>3.2. </span>
+     <li><a href="#using-invalid-variables"><span class=secno>3.1. </span>
       Using Invalid Variables</a>
     </ul>
 
    <li><a href="#cssom"><span class=secno>4. </span> CSSOM</a>
-    <ul class=toc>
-     <li><a href="#cssom-cssvariable"><span class=secno>4.1. </span>
-      Interface CSSVariableComponentValue</a>
-
-     <li><a href="#cssstyledeclaration-interface"><span class=secno>4.2.
-      </span> Additions to the <code>CSSStyleDeclaration</code> Interface</a>
-      
-    </ul>
 
    <li><a href="#conformance"><span class=secno>5. </span> Conformance</a>
     <ul class=toc>
@@ -306,6 +294,15 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Custom
    brackets, or any character that would normally end a declaration (a
    top-level semicolon or close brace).
 
+  <p class=issue> This should be defined as "any sequence of tokens that can
+   be parsed, starting from the ‘<code class=css>declarative-value
+   mode</code>’ in Syntax, without switching out of that mode".
+
+  <p class=note> Note: Custom properties can contain a trailing ‘<code
+   class=css>!important</code>’, but this is automatically removed from the
+   property's value by the CSS parser, and makes the custom property
+   "important" in the CSS cascade.
+
   <p> There are an infinity of <a href="#custom-property"><i>custom
    properties</i></a>, but the initial value of a <a
    href="#custom-property"><i>custom property</i></a> is an empty invalid
@@ -488,10 +485,14 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Custom
   <h2 id=using-variables><span class=secno>3. </span> Using Variables - the
    ‘<code class=css>var()</code>’ notation</h2>
 
-  <p> A <a href="#custom-property"><i>custom property</i></a> automatically
-   defines The value of a <a href="#custom-property"><i>custom
-   property</i></a> on an element can be substituted into another property
-   using the ‘<code class=css>var()</code>’ function.
+  <p> Every <a href="#custom-property"><i>custom property</i></a>
+   automatically defines a corresponding <a
+   href="#variable"><i>variable</i></a>, which can then be substituted into
+   another property with the ‘<code class=css>var()</code>’ function. The
+   syntax of ‘<code class=css>var()</code>’ is:
+
+  <pre><dfn
+   id=default-var-type>&lt;variable></dfn> = var( <var>variable-name</var> [, <var>&lt;value></var> ]? )</pre>
 
   <p> A variable can be used in place of any component value in any property
    on an element. Variables can not be used as property names, selectors, or
@@ -500,6 +501,54 @@ <h2 id=using-variables><span class=secno>3. </span> Using Variables - the
    attribute selector, produces a valid value that nonetheless has no
    relation to the variable of that name.
 
+  <div class=example>
+   <p> For example, the following code incorrectly attempts to use a variable
+    as a property name:
+
+   <pre><!--
+		-->.foo {
+<!--
+		-->  var-side: margin-top;
+<!--
+		-->  var(side): 20px;
+<!--
+		-->}</pre>
+
+   <p> This is <em>not</em> equivalent to setting ‘<code
+    class=css>margin-top: 20px;</code>’. Instead, the second declaration is
+    simply thrown away as a syntax error for having an invalid property name.
+    
+
+   <p> Similarly, you can't build up a single component value where part of
+    it is provided by a variable:
+
+   <pre><!--
+		-->.foo {
+<!--
+		-->  var-gap: 20;
+<!--
+		-->  margin-top: var(gap)px;
+<!--
+		-->}</pre>
+
+   <p> Again, this is <em>not</em> equivalent to setting ‘<code
+    class=css>margin-top: 20px;</code>’ (a length). Instead, it's
+    equivalent to ‘<code class=css>margin-top: 20 px;</code>’ (a number
+    followed by an ident), which is simply an invalid value for the ‘<code
+    class=property>margin-top</code>’ property. Note, though, that ‘<code
+    class=css>calc()</code>’ can be used to validly achieve the same thing,
+    like so:
+
+   <pre><!--
+		-->.foo {
+<!--
+		-->  var-gap: 20;
+<!--
+		-->  margin-top: calc(var(gap) * 1px);
+<!--
+		-->}</pre>
+  </div>
+
   <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 <a
@@ -510,15 +559,20 @@ <h2 id=using-variables><span class=secno>3. </span> Using Variables - the
    <p> For example, the following usage is fine from a syntax standpoint, but
     results in nonsense when the variable is substituted in:
 
-   <pre>
-:root { var-looks-valid: 20px; }
-p { background-color: $looks-valid; }</pre>
+   <pre><!--
+		-->:root { var-looks-valid: 20px; }
+<!--
+		-->p { background-color: $looks-valid; }</pre>
 
    <p> Since ‘<code class=css>20px</code>’ is an invalid value for
     ‘<code class=property>background-color</code>’, this instance of the
     property computes to ‘<code class=property>transparent</code>’ (the
     initial value for ‘<code class=property>background-color</code>’)
     instead.
+
+   <p> If the property was one that's inherited by default, such as ‘<code
+    class=property>color</code>’, it would compute to the inherited value
+    rather than the initial value.
   </div>
 
   <p> In some cases, it can be useful to provide a "default" value for a
@@ -531,95 +585,24 @@ <h2 id=using-variables><span class=secno>3. </span> Using Variables - the
    about, rather than being forced to provide values for all of them.
 
   <p> The ‘<code class=css>var()</code>’ notation allows a default value
-   to be specified when referencing a variable. The syntax of ‘<code
-   class=css>var()</code>’ is:
+   to be specified when referencing a variable. After the variable name,
+   insert a comma and then provide any value, just like the value of a <a
+   href="#custom-property"><i>custom property</i></a>.
 
-  <pre><dfn
-   id=default-var-type>&lt;default-var></dfn> = var( <var>&lt;var></var> [, <var>&lt;value></var> ]? )</pre>
+  <p class=issue> The syntax for custom properties and var fallbacks are
+   actually slightly different - you can't use an unbalanced ) in the
+   fallback, since it ends a function, but you *can* use a semicolon or an
+   unbalanced }. This should be defined as "any sequence of tokens that can
+   be parsed by the ‘<code class=css>consume a function</code>’ algo in
+   Syntax without returning the function".
 
   <p> If the variable named by the first argument is valid, the variable's
    value is substituted as normal. If it's invalid, and a second argument was
    provided, the value of the second argument is substituted instead.
    Otherwise, the ‘<code class=css>var()</code>’ represents an <a
    href="#invalid-variable"><i>invalid variable</i></a>.
 
-  <p class=note> Note that using ‘<code class=css>var()</code>’ without a
-   second argument offers no benefits over using the variable by itself. This
-   is allowed for consistency with ‘<code class=css>parent-var()</code>’,
-   which <em>does</em> do something useful with only one argument. Future
-   variable functions will likely be similar.
-
-  <h3 id=parent-var-notation><span class=secno>3.1. </span> Getting the
-   Parent's Variable - the ‘<code class=css>parent-var()</code>’ notation</h3>
-
-  <p> Several advanced use-cases for variables need the ability to reference
-   the value that a variable has on the element's parent, rather than on the
-   element itself. This can be accomplished with the ‘<code
-   class=css>parent-var()</code>’ notation:
-
-  <pre><dfn
-   id=parent-var-notation-type>&lt;parent-var></dfn> = parent-var( <var>&lt;var></var> [, <var>&lt;value></var> ]? )</pre>
-
-  <p> If the element has a parent, and the variable named by the first
-   argument is valid on the parent, the variable's value on the parent is
-   substituted as normal. Otherwise, if a second argument was provided, the
-   value of the second argument is substituted instead. Otherwise, the
-   ‘<code class=css>parent-var()</code>’ represents an <a
-   href="#invalid-variable"><i>invalid variable</i></a>.
-
-  <div class=example>
-   <p> For example, ‘<code class=css>parent-var()</code>’ can be used to
-    implement a behavior that's very similar to the ‘<code
-    class=css>toggle()</code>’ notation from [[CSS3VALUES]]. In this
-    example, each nested comment alternates between a white and silver
-    background.
-
-   <pre>
-&lt;div class='comment'>
-	&lt;div class='main'>
-		...
-	&lt;/div>
-	&lt;div class='actions'>&lt;a>Reply&lt;/a> &lt;a>Comment&lt;/a> ...&lt;/div>
-&lt;/div>
-&lt;div class='comment'>
-	&lt;div class='main'>
-		&lt;div class='comment'>
-			&lt;div class='main'>
-				...
-			&lt;/div>
-			&lt;div class='actions'>&lt;a>Reply&lt;/a> &lt;a>Comment&lt;/a> ...&lt;/div>
-		&lt;/div>
-	&lt;/div>
-	&lt;div class='actions'>&lt;a>Reply&lt;/a> &lt;a>Comment&lt;/a> ...&lt;/div>
-&lt;/div>
-&lt;style>
-.comment {
-	var-bg:  parent-var($bg2, white);
-	var-bg2: parent-var($bg, silver);
-	background: url(comment.png) $bg;
-}
-&lt;/style></pre>
-
-   <p> The ‘<code class=css>toggle()</code>’ notation can't be used here,
-    because ‘<code class=property>background-color</code>’ isn't
-    inherited (and thus the nested comments see the initial value of ‘<code
-    class=css>transparent</code>’ rather than ‘<code
-    class=css>white</code>’ or ‘<code class=css>silver</code>’). Even
-    if the author explicitly sets ‘<code
-    class=css>background-color:inherit</code>’ on <code>&lt;div
-    class='main'></code> so that ‘<code class=css>toggle()</code>’ can
-    actually see the right value, that will make the ".main" elements cover
-    up the ‘<code class=property>background-image</code>’ that ".comment"
-    has on it as well. Because variables don't have any effect on rendering
-    until they're used, they can pass these values through the document
-    without these kinds of side effects.
-
-   <p> The ‘<code class=css>var()</code>’ notation can't be used here
-    either as it would immediately produce a cycle between $bg and $bg2,
-    making them both invalid.
-  </div>
-
-  <h3 id=using-invalid-variables><span class=secno>3.2. </span> Using Invalid
+  <h3 id=using-invalid-variables><span class=secno>3.1. </span> Using Invalid
    Variables</h3>
 
   <p> When a <a href="#custom-property"><i>custom property</i></a> has its
@@ -642,10 +625,12 @@ <h3 id=using-invalid-variables><span class=secno>3.2. </span> Using Invalid
   <div class=example>
    <p> For example, in the following code:
 
-   <pre>
-:root { var-not-a-color: 20px; }
-p { background-color: red; }
-p { background-color: $not-a-color; }</pre>
+   <pre><!--
+		-->:root { var-not-a-color: 20px; }
+<!--
+		-->p { background-color: red; }
+<!--
+		-->p { background-color: $not-a-color; }</pre>
 
    <p> the &lt;p> elements will have transparent backgrounds (the initial
     value for ‘<code class=property>background-color</code>’), rather
@@ -671,53 +656,13 @@ <h2 id=cssom><span class=secno>4. </span> CSSOM</h2>
    properties, and can be read or modified using all of the existing CSSOM
    APIs for reading or modifying properties.
 
-  <p> The specification extends the IDL definitions in the CSSOM spec to
-   represent the use of the ‘<code class=css>var()</code>’ function.
-
-  <h3 id=cssom-cssvariable><span class=secno>4.1. </span> Interface
-   CSSVariableComponentValue</h3>
-
-  <p> The CSSVariableComponentValue interface represents a use of the
-   ‘<code class=css>var()</code>’ function.
-
-  <dl>
-   <dt>IDL Definition
-
-   <dd>
-    <pre class=idl>
-[NoInterfaceObject] interface CSSVariableComponentValue {
-           attribute DOMString variableName;
-  readonly attribute any variableValue;
-}</pre>
-
-   <dt>Attributes
-
-   <dd>
-    <dl>
-     <dt><code>variableName</code> of type <code>DOMString</code>
-
-     <dd>This attribute represents the argument to the function. Changing
-      this attribute changes the <a href="#custom-property"><i>custom
-      property</i></a> being referred to.
-
-     <dt><code>variableValue</code> of type <code>any</code>, readonly
-
-     <dd>This attribute represents the value of the <a
-      href="#custom-property"><i>custom property</i></a> the function is
-      referencing.
-    </dl>
-  </dl>
-
-  <h3 id=cssstyledeclaration-interface><span class=secno>4.2. </span>
-   Additions to the <code>CSSStyleDeclaration</code> Interface</h3>
-
-  <p class=issue> The set of custom properties is open-ended, so it's not
-   clear how best to represent this. Ideally, the CSSOM would expose the
-   current set of properties with a non-initial value and allow setting of
-   arbitrary properties. The most natural way seems to be to first, set up a
-   getter behavior on the interface somehow that deals with custom
-   properties, and second, set up a <code>vars</code> map that exposes the
-   custom properties that aren't set to their initial value.
+  <p class=issue> Right now, the CSSStyleDeclaration interface can be specced
+   and implemented as a normal interface that just has a *ton* of attributes.
+   (In practice, we don't spec it this way, because it was difficult to
+   extend before partial interfaces were created, but I think it's
+   implemented this way.) However, variables mess this up - there's an
+   infinite number of them. Ideally we'd only expose the valid ones (those
+   set to a non-initial value). How to spec this?
 
   <h2 id=conformance><span class=secno>5. </span> Conformance</h2>
 
@@ -980,18 +925,12 @@ <h2 class=no-num id=index>Index</h2>
    <li>custom property, <a href="#custom-property"
     title="custom property"><strong>2.</strong></a>
 
-   <li>&lt;default-var>, <a href="#default-var-type"
-    title="&lt;default-var>"><strong>3.</strong></a>
-
    <li>invalid at computed-value time, <a
     href="#invalid-at-computed-value-time"
-    title="invalid at computed-value time"><strong>3.2.</strong></a>
+    title="invalid at computed-value time"><strong>3.1.</strong></a>
 
    <li>invalid variable, <a href="#invalid-variable"
-    title="invalid variable"><strong>3.2.</strong></a>
-
-   <li>&lt;parent-var>, <a href="#parent-var-notation-type"
-    title="&lt;parent-var>"><strong>3.1.</strong></a>
+    title="invalid variable"><strong>3.1.</strong></a>
 
    <li>renderer, <a href="#renderer" title=renderer><strong>5.2.</strong></a>
 
@@ -1005,6 +944,9 @@ <h2 class=no-num id=index>Index</h2>
    <li>var-*, <a href="#var-" title="var-*"><strong>2.</strong></a>
 
    <li>variable, <a href="#variable" title=variable><strong>2.</strong></a>
+
+   <li>&lt;variable>, <a href="#default-var-type"
+    title="&lt;variable>"><strong>3.</strong></a>
   </ul>
   <!--end-index-->