[css-variables] Rewrite the text in the 'custom properties' section.

Author: tabatkins

css-variables/Overview.html

@@ -137,22 +137,17 @@ <h2 class="no-num no-toc" id=contents>Table of contents</h2>
     </ul>
 
    <li><a href="#defining-variables"><span class=secno>2. </span> Defining
-    Variables With Custom Properties</a>
+    Custom Properties: the ‘<code class=css>var-*</code>’ family of
+    properties</a>
 
    <li><a href="#using-variables"><span class=secno>3. </span> Using
-    Variables</a>
+    Variables - the ‘<code class=css>var()</code>’ notation</a>
     <ul class=toc>
-     <li><a href="#var-glyph"><span class=secno>3.1. </span> The $ Prefix</a>
-      
-
-     <li><a href="#var-function"><span class=secno>3.2. </span> Default
-      Values - the ‘<code class=css>var()</code>’ notation</a>
-
-     <li><a href="#parent-var-notation"><span class=secno>3.3. </span>
+     <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.4. </span>
+     <li><a href="#using-invalid-variables"><span class=secno>3.2. </span>
       Using Invalid Variables</a>
     </ul>
 
@@ -245,8 +240,9 @@ <h3 id=values><span class=secno>1.2. </span> Values</h3>
    when combined with this module, expands the definition of the
    &lt;color&gt; value type as used in this specification.
 
-  <h2 id=defining-variables><span class=secno>2. </span> Defining Variables
-   With Custom Properties</h2>
+  <h2 id=defining-variables><span class=secno>2. </span> Defining Custom
+   Properties: the ‘<a href="#var-"><code class=css>var-*</code></a>’
+   family of properties</h2>
 
   <p> This specification defines an open-ended set of properties called <a
    href="#custom-property"><i>custom properties</i></a>, which are used to
@@ -262,7 +258,7 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Variables
     <tr>
      <th>Values:
 
-     <td><a href="#value-type"><var>&lt;value></var></a>
+     <td><var>&lt;value></var>
 
     <tr>
      <th>Initial:
@@ -291,54 +287,53 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Variables
      <td>all
   </table>
 
-  <p> The <dfn id=value-type><var>&lt;value></var></dfn> type used in the
-   syntax above is defined as anything matching the "value" production in <a
-   href="http://www.w3.org/TR/CSS2/syndata.html#tokenization">CSS 2.1 Chapter
-   4.1</a> <a href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>.
-   This puts almost no restrictions on what kinds of values you can store in
-   variables. Obviously, any valid property value or component of a property
-   is allowed. Additionally, this allows things that aren't yet valid CSS,
-   like unknown keywords or functions, blocks, at-rules, and other kinds of
-   custom micro-syntaxes like what's allowed in calc(). There <em>are</em>
-   still rules, however; for example, unbalanced parentheses are invalid.
-
-  <p> The term <dfn id=custom-property
-   title="custom property|custom properties">custom property</dfn> refers to
-   any property whose name is composed of a "var-" prefix followed by
-   something matching the IDENT production in <a
-   href="http://www.w3.org/TR/CSS2/syndata.html#tokenization">CSS2.1 Chapter
-   4</a>. A <a href="#custom-property"><i>custom property</i></a> defines a
-   value for a corresponding <a href="#variable"><i>variable</i></a> with the
-   same name as the property except that the "var-" prefix is replaced with a
-   "$" prefix.
-
-  <p> The initial value of a <a href="#custom-property"><i>custom
-   property</i></a> is an empty invalid value. This means that, until a <a
-   href="#custom-property"><i>custom property</i></a> is explicitly defined
-   otherwise by a style sheet, it defines an <a
-   href="#invalid-variable"><i>invalid variable</i></a>
-
-  <p class=issue> As defined here, the syntax for variable usage is different
-   from the syntax for variable definition (i.e. var-foo for definition, $foo
-   for usage). It might be nice to have the syntaxes match, using "$foo" as
-   the property name as well. This would require a minor change in the Core
-   Grammar.
-
-  <p> <a href="#custom-property"><i>Custom properties</i></a> are defined to
-   be valid but meaningless as they are meant solely for allowing authors to
-   pass custom data around their page, similar to the <a
-   href="http://www.w3.org/TR/html5/global-attributes.html#embedding-custom-non-visible-data-with-the-data-attributes">custom
-   data attributes</a> in HTML. Other specifications and user agents must not
-   assign a particular meaning to <a href="#custom-property"><i>custom
-   properties</i></a> or attach a specific effect to them beyond the bare
-   minimum that comes from them being valid properties.
-
-  <p> For each <a href="#custom-property"><i>custom property</i></a>, there
-   is an associated variable with the same name save for the "var-" prefix.
-   For example, a custom property named "var-foo" is associated with the
-   variable named "foo". See the next chapter for details on how to use
+  <p> A <dfn id=custom-property
+   title="custom property|custom properties">custom property</dfn> is any
+   property whose name is composed of "var-" followed by an
+   <code>&lt;ident></code> <a href="#CSS3VAL"
+   rel=biblioentry>[CSS3VAL]<!--{{!CSS3VAL}}--></a> <a
+   href="#custom-property"><i>Custom properties</i></a> are solely for use by
+   authors and users; CSS will never give them a meaning beyond what is
+   presented here.
+
+  <p> <a href="#custom-property"><i>Custom properties</i></a> have an
+   extremely permissive value grammar, defined as the "value" production in
+   <a href="http://www.w3.org/TR/CSS2/syndata.html#tokenization">CSS 2.1
+   Chapter 4.1</a> <a href="#CSS21"
+   rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>. This implies that any valid
+   CSS value can be used, but it's much wider than that. Roughly, anything
+   can be used except for unclosed quotes, parens, braces, or square
+   brackets, or any character that would normally end a declaration (a
+   top-level semicolon or close brace).
+
+  <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
+   value. This means that, until a <a href="#custom-property"><i>custom
+   property</i></a> is explicitly defined otherwise by a style sheet, it
+   defines an <a href="#invalid-variable"><i>invalid variable</i></a>.
+
+  <p> The primary purpose of <a href="#custom-property"><i>custom
+   properties</i></a> is to define <a href="#variable"><i>variables</i></a>.
+   In CSS, a <dfn id=variable>variable</dfn> is a value that can be
+   substituted into other properties, allowing authors to "abstract" parts of
+   their page's CSS out. Every <a href="#custom-property"><i>custom
+   property</i></a> defines a corresponding <a
+   href="#variable"><i>variable</i></a> with the same name, minus the "var-"
+   prefix. For example, the custom property ‘<code
+   class=property>var-foo</code>’ defines a variable named ‘<code
+   class=css>foo</code>’. See the next chapter for details on how to use
    variables.
 
+  <p> <a href="#custom-property"><i>Custom properties</i></a> can be put to
+   several other uses, of course. For example, they can be used to
+   conveniently attach values to elements so that JavaScript can later use
+   those values. Another example is providing "custom CSS" by treating "var-"
+   as a kind of "author prefix" (similar to a vendor prefix) that allows an
+   author to write custom CSS properties without having them thrown away as
+   invalid by the CSS parser, and then having JavaScript come along afterward
+   to actually implement the functionality.
+
   <div class=example>
    <p> This style rule:
 
@@ -363,7 +358,7 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Variables
     class=property>var-header-color</code>’ property on the root element.
   </div>
 
-  <p> custom properties are ordinary properties, so they can be declared on
+  <p> Custom 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 ‘<code class=css>@media</code>’ and other
    conditional rules, can be used in HTML's <code>style</code> attribute, can
@@ -490,14 +485,13 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Variables
                                                                      gggggg  
 -->
 
-  <h2 id=using-variables><span class=secno>3. </span> Using Variables</h2>
+  <h2 id=using-variables><span class=secno>3. </span> Using Variables - the
+   ‘<code class=css>var()</code>’ notation</h2>
 
-  <p> A <dfn id=variable>variable</dfn> allows the value of a <a
-   href="#custom-property"><i>custom property</i></a> on an element to be
-   substituted into another property on the element. There are several ways
-   to use variables: by name, via the ‘<code class=css>var()</code>’
-   notation, or via the ‘<code class=css>parent-var()</code>’ notation to
-   get at a variable on the element's parent.
+  <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> 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
@@ -527,36 +521,6 @@ <h2 id=using-variables><span class=secno>3. </span> Using Variables</h2>
     instead.
   </div>
 
-  <h3 id=var-glyph><span class=secno>3.1. </span> The $ Prefix</h3>
-
-  <p> The simplest way to use a variable is to refer to it by its name, which
-   is the same as the <a href="#custom-property"><i>custom property</i></a>
-   defining it, except with the "var-" prefix swapped out for a "$" prefix.
-   Formally, the syntax of a variable is:
-
-  <pre><dfn id=type-var>&lt;var></dfn> = "$" <var>IDENT</var></pre>
-
-  <p> ...where <var>IDENT</var> is anything matching the IDENT production in
-   <a href="http://www.w3.org/TR/CSS2/syndata.html#tokenization">CSS2.1
-   Chapter 4</a>.
-
-  <div class=example>
-   <p> For example, the following code defines and uses a variable named
-    "main-color".
-
-   <pre>
-:root { 
-	var-main-color: blue;
-}
-
-h1 { 
-	color: $main-color;
-}</pre>
-  </div>
-
-  <h3 id=var-function><span class=secno>3.2. </span> Default Values - the
-   ‘<code class=css>var()</code>’ notation</h3>
-
   <p> In some cases, it can be useful to provide a "default" value for a
    variable in case the variable isn't defined or is invalid.
 
@@ -570,9 +534,8 @@ <h3 id=var-function><span class=secno>3.2. </span> Default Values - the
    to be specified when referencing a variable. The syntax of ‘<code
    class=css>var()</code>’ is:
 
-  <pre><dfn id=default-var-type>&lt;default-var></dfn> = var( <a
-   href="#type-var"><var>&lt;var></var></a> [, <a
-   href="#value-type"><var>&lt;value></var></a> ]? )</pre>
+  <pre><dfn
+   id=default-var-type>&lt;default-var></dfn> = var( <var>&lt;var></var> [, <var>&lt;value></var> ]? )</pre>
 
   <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
@@ -586,7 +549,7 @@ <h3 id=var-function><span class=secno>3.2. </span> Default Values - the
    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.3. </span> Getting the
+  <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
@@ -595,9 +558,7 @@ <h3 id=parent-var-notation><span class=secno>3.3. </span> Getting the
    class=css>parent-var()</code>’ notation:
 
   <pre><dfn
-   id=parent-var-notation-type>&lt;parent-var></dfn> = parent-var( <a
-   href="#type-var"><var>&lt;var></var></a> [, <a
-   href="#value-type"><var>&lt;value></var></a> ]? )</pre>
+   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
@@ -658,7 +619,7 @@ <h3 id=parent-var-notation><span class=secno>3.3. </span> Getting the
     making them both invalid.
   </div>
 
-  <h3 id=using-invalid-variables><span class=secno>3.4. </span> Using Invalid
+  <h3 id=using-invalid-variables><span class=secno>3.2. </span> Using Invalid
    Variables</h3>
 
   <p> When a <a href="#custom-property"><i>custom property</i></a> has its
@@ -956,6 +917,16 @@ <h3 class=no-num id=normative-references>Normative references</h3>
     </dd>
    <!---->
 
+   <dt id=CSS3VAL>[CSS3VAL]
+
+   <dd>Håkon Wium Lie; Tab Atkins; Elika J. Etemad. <a
+    href="http://www.w3.org/TR/2012/WD-css3-values-20120308/"><cite>CSS
+    Values and Units Module Level 3.</cite></a> 8 March 2012. W3C Working
+    Draft. (Work in progress.) URL: <a
+    href="http://www.w3.org/TR/2012/WD-css3-values-20120308/">http://www.w3.org/TR/2012/WD-css3-values-20120308/</a>
+    </dd>
+   <!---->
+
    <dt id=RFC2119>[RFC2119]
 
    <dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key
@@ -1010,17 +981,17 @@ <h2 class=no-num id=index>Index</h2>
     title="custom property"><strong>2.</strong></a>
 
    <li>&lt;default-var>, <a href="#default-var-type"
-    title="&lt;default-var>"><strong>3.2.</strong></a>
+    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.4.</strong></a>
+    title="invalid at computed-value time"><strong>3.2.</strong></a>
 
    <li>invalid variable, <a href="#invalid-variable"
-    title="invalid variable"><strong>3.4.</strong></a>
+    title="invalid variable"><strong>3.2.</strong></a>
 
    <li>&lt;parent-var>, <a href="#parent-var-notation-type"
-    title="&lt;parent-var>"><strong>3.3.</strong></a>
+    title="&lt;parent-var>"><strong>3.1.</strong></a>
 
    <li>renderer, <a href="#renderer" title=renderer><strong>5.2.</strong></a>
 
@@ -1031,15 +1002,9 @@ <h2 class=no-num id=index>Index</h2>
       title="style sheet, as conformance class"><strong>5.2.</strong></a>
     </ul>
 
-   <li><a href="#value-type"><var>&lt;value></var></a>, <a href="#value-type"
-    title="&lt;value>"><strong>2.</strong></a>
-
-   <li>&lt;var>, <a href="#type-var"
-    title="&lt;var>"><strong>3.1.</strong></a>
-
    <li>var-*, <a href="#var-" title="var-*"><strong>2.</strong></a>
 
-   <li>variable, <a href="#variable" title=variable><strong>3.</strong></a>
+   <li>variable, <a href="#variable" title=variable><strong>2.</strong></a>
   </ul>
   <!--end-index-->