Re: Widgets 1.0: Packaging and Configuration LCWD review

WG members,
The following comments are all editorial in nature (and the most
significant of Krzysztof issues were also raised by others during the
LC review period). Hence, I felt no harm in addressing his comments
while we wait to "officially" go to CR (I'd actually started
addressing these comments a few days after they came in, before the
decision was made not to include them in the Disposition of Comments).

Also, Krzysztof has committed significant time to the Widgets work in
the past, and, out of respect, I strongly believe his comments should
be considered (even if they were a little late:)).

Hi, Krzysztof!
Thanks again for the detailed review! Inline comments below...

2009/6/22 Krzysztof Maczyqski <1981km@gmail.com>:
> 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.
>

Fixed.

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

Fixed.

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

Yeah, a number of times I've searched for your emails only to find
your name had been chopped in half!

>> a class of software application
> Was plural intended?

Plural?

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

We are reserving "resources" for resources. The specification tries to
define what constitutes a file.

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

Used "Client".

>> 1 Introduction
> Is the text before 1.1 normative?

I tried to make this more clear by adding more "this is non-normative"
labels where appropriate.

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

Agreed.
"A user agent may support other legacy/proprietary widgets."

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

I will leave that as is.

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

Right. Removed it.

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

Yes, this was also pointed out by another commenter. I have now fixed
this by allowing UA's to support any compression formats they like,
but asking CC's to warn if anything but the recommended ones are used.

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

Removed the word "internally".

>> cp437-chars
> This nonterminal seems undefined.

Right, fixed by removing its mention. Now reads:

"If an author chooses to use the utf8-chars, they need to thoroughly
test their widgets on various platforms prior to distribution".

>> 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)?
>

Whoops, fixed!

>> then Make sure that the widget is labeled
> Typo.

Fixed.

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

Right, I said instead "Failure to correctly label a widget package
_CAN_ result"... leaving the possibility that it can not too. This is
a non-normative authoring guide, so hopefully people will get it.

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

Fixed.

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

Fixed.

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

You mean that they don't conform? I ran some tests using a tool called
abnfgen, the best results came out of the following ABNF:

rec-version-tag = 1*DIGIT "."  1*DIGIT [ "." 1*DIGIT]
                            *[ 1*ALPHA / SP / 1*DIGIT ]

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

I went with "An IRI attribute whose value represents a IRI that the
author associates with himself or herself (e.g., a homepage, a profile
on a social network, etc.)."

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

I think we will specify the rendering of icons in detail elsewhere.
But I agree.

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

Woops. Is this any better:

"The its:span element may be used as a child element of the following
elements of the configuration document. In addition, the its:dir
attribute may be used in the following elements of the configuration
document:"

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

There is no canonical spelling in BCP 47, because the tags are treated
as case-insensitive. BCP 47 sez: "The tags and their subtags,
including private use and extensions, are to be treated as case
insensitive: there exist conventions for the capitalization of some of
the subtags, but these MUST NOT be taken to carry meaning."

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

Yes, another commenter also pointed this out earlier.  I have now
corrected this in the spec.

>> The steps for processing a widget package involves nine steps that a user agent SHOULD follow
> Why not just MAY, given the next paragraph?

Ok, MAY it is.

> It also seems that RFC 2119 keywords are sometimes all-capitalized by style and sometimes in the markup (probably by mistake).

I've made them all lowercase. Let the stylesheet handle the upper-casing

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

Fixed globally.

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

Woops, fixed (removed that restriction).

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

Fixed (did not know that, thanks!:)).

>> or fileis not present
> Typo.

fixed

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

fixed

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

Moved it to where it is used ("Rule for Getting Text Content").

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

I got rid of "This is in error and", so it just says "The user agent
must ignore it"

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

True, I removed it.

Thanks again for all your help!!!

-- 
Marcos Caceres
http://datadriven.com.au

Received on Friday, 10 July 2009 14:59:29 UTC