[css-variables] Tweak grammar, per dbaron's comments.

--HG--
extra : rebase_source : 6fa9f4bd4ca6d0e97f47478d5de31c308a840c5b

Author: tabatkins

css-variables/Overview.html

@@ -261,7 +261,9 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Custom
     <tr>
      <th>Values:
 
-     <td><var>&lt;value></var>
+     <td><a href="#ltvalue"><var>&lt;value></var></a> | <a
+      href="#ltcdo"><var>&lt;CDO></var></a> | <a
+      href="#ltcdc"><var>&lt;CDC></var></a>
 
     <tr>
      <th>Initial:
@@ -313,20 +315,32 @@ <h2 id=defining-variables><span class=secno>2. </span> Defining Custom
   </div>
 
   <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).
+   extremely permissive value grammar. The <dfn id=ltvalue>&lt;value></dfn>
+   in its grammar corresponds to 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>,
+   while <dfn id=ltcdo>&lt;CDO></dfn> and <dfn id=ltcdc>&lt;CDC></dfn>
+   correspond to the tokens of the same name from the same chapter (they
+   represent HTML comments showing up in CSS text - "&lt;!--" and "--&gt;").
+   This is a very technical way of saying that nearly anything can be used in
+   the value of a custom property, save unmatched closing brackets ("]", ")",
+   or "}"), a top-level semicolon (as it will end the property), a
+   "!important" that's not at the end, or invalid tokens (such as BAD_STRING
+   and BAD_URL).
 
   <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.
 
+  <div class=example> For example, the following is a valid custom property:
+   <pre>var-foo: if(x > 5) this.width = 10;</pre>
+
+   <p> While this value is obviously useless as a <a
+    href="#cascading-variable"><em>variable</em></a>, as it would be invalid
+    in any normal property, it might be read and acted on by JavaScript.
+  </div>
+
   <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
@@ -1029,6 +1043,10 @@ <h2 class=no-num id=index>Index</h2>
    <li>cascading variable, <a href="#cascading-variable"
     title="section 2."><strong>2.</strong></a>
 
+   <li>&lt;CDC>, <a href="#ltcdc" title="section 2."><strong>2.</strong></a>
+
+   <li>&lt;CDO>, <a href="#ltcdo" title="section 2."><strong>2.</strong></a>
+
    <li>creator, <a href="#cssvariablesdeclaration-creator"
     title="section 4.2."><strong>4.2.</strong></a>
 
@@ -1072,6 +1090,9 @@ <h2 class=no-num id=index>Index</h2>
       title="section 5.2."><strong>5.2.</strong></a>
     </ul>
 
+   <li>&lt;value>, <a href="#ltvalue"
+    title="section 2."><strong>2.</strong></a>
+
    <li>var-*, <a href="#var-" title="section 2."><strong>2.</strong></a>
 
    <li>variable, <a href="#cascading-variable"
@@ -1106,7 +1127,7 @@ <h2 class=no-num id=property-index>Property index</h2>
     <tr>
      <th><a class=property href="#var-">var-*</a>
 
-     <td>&lt;value>
+     <td>&lt;value> | &lt;CDO> | &lt;CDC>
 
      <td>(nothing, see prose)
 

css-variables/Overview.src.html

@@ -124,7 +124,7 @@ <h2 id="defining-variables">
 			<td><dfn>var-*</dfn>
 		<tr>
 			<th>Values:
-			<td><var>&lt;value></var>
+			<td><var>&lt;value></var> | <var>&lt;CDO></var> | <var>&lt;CDC></var>
 		<tr>
 			<th>Initial:
 			<td>(nothing, see prose)
@@ -165,19 +165,34 @@ <h2 id="defining-variables">
 	</div>
 
 	<p>
-		<i>Custom properties</i> 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> [[!CSS21]].
-		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).
+		<i>Custom properties</i> have an extremely permissive value grammar.
+		The <dfn>&lt;value></dfn> in its grammar corresponds to the "value" production
+		in <a href="http://www.w3.org/TR/CSS2/syndata.html#tokenization">CSS 2.1 Chapter 4.1</a> [[!CSS21]],
+		while <dfn>&lt;CDO></dfn> and <dfn>&lt;CDC></dfn> correspond to the tokens of the same name
+		from the same chapter
+		(they represent HTML comments showing up in CSS text - "&lt;!--" and "--&gt;").
+		This is a very technical way of saying that nearly anything can be used in the value of a custom property,
+		save unmatched closing brackets ("]", ")", or "}"),
+		a top-level semicolon (as it will end the property),
+		a "!important" that's not at the end,
+		or invalid tokens (such as BAD_STRING and BAD_URL).
 
 	<p class='note'>
 		Note: Custom properties can contain a trailing ''!important'',
 		but this is automatically removed from the property's value by the CSS parser,
 		and makes the custom property "important" in the CSS cascade.
 
+	<div class='example'>
+		For example, the following is a valid custom property:
+
+		<pre>var-foo: if(x > 5) this.width = 10;</pre>
+
+		<p>
+			While this value is obviously useless as a <em>variable</em>,
+			as it would be invalid in any normal property,
+			it might be read and acted on by JavaScript.
+	</div>
+
 	<p>
 		There are an infinity of <i>custom properties</i>,
 		but the initial value of a <i>custom property</i> is an empty invalid value.