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

On Thu, Mar 28, 2013 at 5:03 PM, Bjoern Hoehrmann <derhoermi@gmx.net> wrote:
> 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.

That's a misuse of the term, but one that's limited to the OM side.
If a clarification is needed, it's in the OM; otherwise, CSS is clear
that properties and descriptors are different things (though they're
both declarations).

> 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.

This is part of our boilerplate.  I'll amend it to be more
theoretical, so it doesn't imply that this spec actually uses <color>.

> 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.

Hm, that's a mistake on our part.  Too bad we *just* published a new
CR. ^_^  I'll just refer to "identifier" instead.

> 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.

Nope, the part after "var-" needs to conform to the <ident> grammar,
so you can use it as a bare value in the var() function.  I've
reworked this a little bit to be clearer that it's not a token on its
own, but it must conform to the token's grammar.  I've also added an
example a bit further down that illustrates it.

> 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.

Done, in that first example.

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

Weird, fixed.

> 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.

Done.

> 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.

Sure.

>   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.

I've tried rewriting it a bit to make the intent clearer.

> 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.

I think that I already clarify exactly that, with the text implying
that this is only useful if acted on by JavaScript.

> 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(...)`.

You're right. I've rewritten it to be more clearly just about the
custom property, and left a note about it having a special interaction
with '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.

It's not clear to me whether extending CSSOM interfaces implies a
normative dependency on CSSOM or not.  Technically, if you don't
implement CSSOM at all, you can just ignore these sections and still
have a valid variables implementation.

> 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.

Done!  I like this a little better than what I had.

~TJ

Received on Friday, 29 March 2013 23:31:46 UTC