[css-variables] Comments on WD-css-variables-20130312

Hi,

  Regarding <http://www.w3.org/TR/2013/WD-css-variables-20130312/>:

Section 1.1 says "This module defines a new type of primitive value,
the variable, which is accepted by all properties." I think something
more elaborate is required here; consider for instance that DOM Level
2 Style considers font descriptors "properties" that can be accessed
using `getPropertyValue` and friends.

In section 1.2 the text

  Other CSS modules may expand the definitions of these value
  types: for example [CSS3COLOR], when combined with this module,
  expands the definition of the <color> value type as used in this
  specification.

seems confused, for one thing, the css-variables proposal does not
actually use the <color> type. It seems the text can be removed.

In section 2

  A custom property is any property whose name is composed of "var-"
  followed by an <ident> [CSS3VAL] Custom properties are solely for
  use by authors and users; CSS will never give them a meaning beyond 
  what is presented here.

There is a full-stop missing after "[CSS3VAL]". The referenced version
of "CSS Values and Units Module Level 3" does not actually explain the
`<ident>` symbol. The reference to <ident> is misleading, the author-
defined part of the name would not be a token on its own; say something
like 'A custom property is any property whose name starts with "var-"'
instead.

Example 1 makes surprising use of `var(...)` which hasn't been defined
or otherwise been mentioned before. There should be at least a forward
reference in the prose preceding the example like "Variables are refer-
enced using the `var(...)` notation" with a corresponding link.

The Example 1 style sheet code seems to lack the `var-` prefix.

In Example 1, avoid phrases like "tons of edits", and "in the project"
should probably refer to "web page" or "web site" or somesuch concept.

In section 2,

  Custom properties have an extremely permissive value grammar. The
  <value> in its grammar corresponds to the "value" production in CSS
  2.1 Chapter 4.1 [CSS21], while <CDO> and <CDC> correspond to the
  tokens of the same name from the same chapter (they represent HTML
  comments showing up in CSS text - "<!--" and "-->"). 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).

This should simply say that the value of custom properties can be any
value that the core syntax allows ... plus cdo and cdc. There is no
value in discussing the other bits here. If the text is kept, there
would have to be some changes, like clarifying what `a "!important"
that's not at the end` is.

  Further, the value of a custom property must retain its original
  author-given casing, unlike most CSS values which can be safely
  lower-cased (because most of CSS is case-insensitive in the ASCII
  range). (This requirement does not apply when a custom property's
  value is substituted into another property via a variable.)

This text should be rewritten to remove the parentheticals, among
other things. I gather the idea is to say that value of custom pro-
perties is case-sensitive up until it's re-interpreted as part of a
proper property value, but that is not coming across well.

Example 3 encourages authors to put script code into style sheets.
That strikes me as a very bad idea. Without clarification that this
script code will never be executed by the browser unless authors let
custom scripts evaluate it this also seems rather misleading. Find
something else to use in the example, or at the least make it some
arithmetic expression rather than using control flow statements.

In section 2

  There are an infinity of custom properties, but the initial value
  of a custom property is an empty invalid value. This means that,
  until a custom property is explicitly defined otherwise by a style
  sheet, it defines an invalid variable.

I would expect readers to have trouble understanding what the purpose
of the text in its current context is. It seemingly define what the
`var(...)` notation evaluates to, rather than anything to do with the
declaration mechanism that's the subject of the section, so perhaps it
would be better placed in the section on `var(...)`.

In section 4.2 text like "invoke getPropertyValue() by passing varName
as its argument, and return the returned value." does not adequately
define the required behavior e.g. when the `getPropertyValue` member
has been replaced if that is possible. The text also isn't really clear
on what you call the method or what happens if the call does not return
a value but rather throws an exception (which can happen e.g. under low
memory conditions).

The draft seems to normatively depend on "cssom" but fails do identify
that dependency in the References section.

In Example 13 "The following lines of script all return something
useful" should be rephrased (lines do not return things). Those
following lines invoke a `print()` function. Given what the `print`
method of the `window` object does in web browsers, something else
should be used instead. I would suggest to use a table with the
ecmascript expression, corresponding value, and a column for notes.

regards,
-- 
Björn Höhrmann · mailto:bjoern@hoehrmann.de · http://bjoern.hoehrmann.de
Am Badedeich 7 · Telefon: +49(0)160/4415681 · http://www.bjoernsworld.de
25899 Dagebüll · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

Received on Friday, 29 March 2013 00:04:19 UTC