Widgets 1.0: Packaging and Configuration LCWD review

Dear Marcos and WG,

Here follows my set of remarks on Widgets 1.0: Packaging and Configuration which I hope you'll find valuable during LC review. It's based on the 17th June Editor's Draft.

> http://www.w3.org/TR/2009/WD-widgets-??/
Error 404. "TBD" in place of IRI would be better.

> Latest Editor's draft:
In other places the word "draft" is also capitalized.

> Marcos Cįceres
This remark is positive: nice to see the name spelled correctly. (Some WGs and the server at lists.w3.org have problems with mine.)

> a class of software application
Was plural intended?

> while processing the packaging format, configuration document, and other relevant files
I can accept that the non-webby notion of files is used in the Zip spec and as such adequate for what's contained in Zip archives. But, as we have already discussed, for other uses please write "resources".

> Rich Web Clients Activity
This is not an issue of the document itself, but worth mentioning, especially since it's your Activity. The W3C site uses inconsistent naming: sometimes it's "Clients" and in other places "Client". Be sure to pick the correct one.

> 1 Introduction
Is the text before 1.1 normative?

> While a conforming user agent may support other legacy/proprietary widget types in order to conform to this specification, a user agent must treat widget packages as according to this specification.
I find this sentence unclear.

> The magic numbers for a Zip archive is the byte sequence
Aren't those officially called octets?

> other compression formats will cause the widget package to be treated as an invalid Zip archive.
In the context of definitions present in the document this would effectively render the OPTIONAL (so says 3.1) support for other compression formats useless. As an authoring guideline, this text isn't normative, so if included in the final spec, should be considered false. Of course false statements are to be avoided.

> If a CC encounters a compression method that is not one of the valid compression methods,then the CC must inform the author that the Zip archive is an invalid Zip archive.
This, on the other hand, is normative. So the problem is serious. I suggest lowering this to a warning by CC that user agents will be allowed to treat the Zip archive as invalid.

> For the sake of comparison and matching, it is recommended that a user agent internally treats all Zip-relative paths as [UTF-8].
What does "internally treats" mean? Is there a risk of violating Charmod, or are Zip archive internals believed to be out of its scope?

> cp437-chars
This nonterminal seems undefined.

> If the widget package does not contain a start file, or the start file is not one that is supported by a particular user agent, then the CC must inform the author.
How can a CC have knowledge of all user agents? Or do you mean a CC is a user agent (indeed, in general terminology, but this term has been narrowed for this spec in 2)?

> then Make sure that the widget is labeled
Typo.

> Failure to correctly label a widget package will result in it being treated as an invalid Zip archive.
Only if it's first considered to be a potential Zip archive. A generic user agent may process other resources (e.g. image/svg+xml) and only defer to its subcomponent that implements widget specs on encountering application/widget.

> If it is anticipated that the widget will be distributed by non-HTTP means, then include the widget file extension.
Replace "non-HTTP means" by "means lacking MIME support".

> Author Guidelines:
In other places it's 
"Authoring guideline:".

> Example of recommended version tags:
They don't belong to the language generated by {rec-version-tag}.

> A URI attribute that represents a link that is associated with the author (e.g. the homepage of the author). It is optional for authors to use this attribute.
This really should be specified as the URI of the author himself. Nowadays still many authors will probably just point to their homepages, but semantically mean themselves, which they'll be able to make explicit at the time they decide they want to, using the techniques described in http://www.w3.org/TR/cooluris/.

> If the file pointed to by the src attribute is of a vector graphic format, then this value must be used.
Why? Vector formats may include preferred sizes specified. Even if not, some environments require specific sizes and it should be assumed that whatever else is specified, will be scaled. In case of vector graphics without intrinsic dimensions I believe it's the environment's responsibility to apply a reasonable default.

> The its:dir attribute and the its:span element may each be used as a child
What data model are you using to call attributes children?

> such as "en-us", "en-gb", and so on
Canonical spelling is "en-US", "en-GB", and so on. Do you intend to require deviating from it?

> However, widget packages localized at any folder level (e.g. "locales/zh/") needs to be fully functional as a localized widget. That is, authors cannot simply put shared files into a language level folder, but need to put all files needed into the language level folder for the widget to work (for example, having "a.gif" in both the "/locales/zh-Hans/" folder and "/locales/zh/").
The "Fallback Behavior Example" in 8.4 suggests otherwise. Could you clarify this issue in the spec, please?

> The steps for processing a widget package involves nine steps that a user agent SHOULD follow
Why not just MAY, given the next paragraph?
It also seems that RFC 2119 keywords are sometimes all-capitalized by style and sometimes in the markup (probably by mistake).

> The rule for determining if a potential Zip archive is a Zip archive are as follows:
Here and in other places probably plural was intended.

> Each item in the unprocessed locales must be a string shorter than eight characters, in lowercase form
I find both of these requirements objectionable. "x-klingon" is 9 characters, country subtags are canonically upper-case and script subtags mixed-case.

> remove all duplicate ranges except the left most one.
s/left most/first (There's international consensus that lists are undirectional data structures.)

> or fileis not present
Typo.

> two or more bits of information
Bit is a unit, so I suggest calling those pieces.

> The term text node refers to any Text node, including CDATASection node
This term is unused.

> This is in error and the user agent must ignore it.
Although in principle naming things arbitrarily doesn't change meaning, it's somewhat difficult to accept that comments are proclaimed to be "in error".

> Once all the elements in the elements list have been processed, go to Step 8.
Overzealous implementation would then perform Step 8 twice, since it's been already instructed before to perform all 9 steps in sequence.

Received on Sunday, 21 June 2009 23:23:53 UTC