Disposition of comments for the Web Applications Working Group

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.

Comment from the i18n review of:
http://www.w3.org/TR/2009/WD-widgets-20090528/

Comment 2
At http://www.w3.org/International/reviews/0907-widgets-pc/
Editorial/substantive: E
Tracked by: AP

Location in reviewed document:
Section 8.3 [http://www.w3.org/TR/2009/WD-widgets-20090528/#attribute-types]

Comment:
Section 8.3 (Attribute Types) contains a subsection called "URI Attribute" which is relevant to our comment above. It says:

--

An attribute defined as containing a valid URI. A valid URI is one that matches the URI token of the [URI] specification or the IRI token of the [RFC3987] specification. The value of this kind of attribute is retrieved using the rule for getting a single attribute value. --

This is problematical, since all URIs are IRIs, but not the converse. We think this should favor IRI and note the relationship to URI.

Comment from the i18n review of:
http://www.w3.org/TR/2009/WD-widgets-20090528/

Comment 7
At http://www.w3.org/International/reviews/0907-widgets-pc/
Editorial/substantive: E
Tracked by: AP

Location in reviewed document:
Section 9.1, step 4 [http://www.w3.org/TR/2009/WD-widgets-20090528/#step-4--locate-and-process-the-digital-s]

Comment:
In this same step, substep 4 is unnecessary. It does save processing time, but it is not required for proper operation. Performing the specific change suggested also has the negative side-effect of altering the user's preferences ahead of the local configuration. The rightmost occurrence would be a better choice for elimination.

Marcos, all,

some more review comments for Widgets 1.0 Packaging and Configuration LC
(Working Draft 28 May 2009), this time of a more general nature (not so much
L10N-related).


/1/ RFC 2119 keyword usage

In writing specs, the work split between MAY and SHOULD is sometimes
problematic. I tend to use MAY when there is something that is slightly "out
of line" but permissible in some cases, and SHOULD when it is generally a
very good idea or almost mandatory to do something, but it can be skipped
given enough reasons.

This is why I reacted to this statement in section 3.1:
"A user agent MAY support the [Widgets-DigSig] specification ..."
And would have written it as:
"A user agent SHOULD support ..."

The same goes for section 3.2. I would say: "a user agent SHOULD support the
its:span element and the its:dir attribute, and MAY support other ITS
elements and attributes". Also, the right name for ITS is
"Internationalization Tag Set" ("ation" vs. "ed").

4 Conformance Checker
Last sentence in the section: "CCs are NOT REQUIRED to display all messages
at once". Here, "NOT REQUIRED" is not valid RFC 2119 keyword usage. Suggest
to remove this sentence altogether, and change the preceding sentence to
say: "The wording and presentation of the advisory messages are
implementation-dependent."

5 Zip Archive
It would be enough to say: "The packaging format for the files of a widget
is the Zip archive format as defined in the [ZIP] file format
specification."

For conformance (last paragraph in section before note) I suggest, for
clarity: "To conform to this specification, a Zip archive MUST contain one
or more file entries and MUST be a valid Zip archive." (c.f "MUST NOT be
invalid")

5.2 Version of Zip
For Zip version 2.0 features, the MAYs should not be marked up as keywords.

8.5 The widget element, definition of width attribute: "Which view modes
SHOULD honor the value of this attribute is defined in the the
[Widgets-Views] specification". This is invalid keyword usage, suggest to
replace with: "The view modes that honor the value of this attribute are
defined in the [Widgets-Views] specification."


/2/ UTF-8 encoding

So, we still can't mandate the use of UTF-8 as the path encoding? Of course,
RECOMMENDED is fairly strong, but I would prefer MUST. As soon as you move
out of US-ASCII range, the bytes CP437 and UTF-8 will be different even for
the limited number of non-US-ASCII chacters that CP437 can represent.

Marcin has already commented on the ABNF of utf8-chars, I'll participate in
that discussion if necessary.

5.4 Reserved Characters: suggest to reverse the order of the glyph and
character columns.

8.11 The content element, definition of charset attribute:
- Despite widespread use, the name "charset" is not good. A more accurate
name would be "encoding".
- Suggest to replace "(a user agent are REQUIRED to support [UTF-8])" with
"User agents MUST support [UTF-8]."


/3/ JPEG icons

This may have been beaten to death before, but I wondered why a JPEG file is
not allowed as the default icon.


/4/ Configuration document

It is not currently an error to have a file called 'config.xml' anywhere
inside the widget's folder structure. The only one that matters is the one
in the root folder. Maybe the CC should warn about the presence of multiple
config.xml documents?

In 8.2 Proprietary Extensions, first para, last sentence: "For the sake of
interoperability, extensions to the configuration document are NOT
RECOMMENDED". Two problems: 1) "NOT RECOMMENDED" is not valid keyword usage;
2) it is OK to extend the configuration document because there is a
well-defined mechanism that uses namespaces. Suggestion: remove this
statement.

Version attribute: in the ABNF, doesn't "1*2DIGIT" mean that a version
number like 123 would be invalid? Especially build numbers are often three
or four digits long. Of course, this is only a guideline, but still...

Numeric attribute: apparently all numeric attributes are non-negative. Isn't
there any use case for negative numbers, ever? Also, non-Western numerals
are not acceptable by this definition, but that might not be a showstopper
in this case.

Keyword attribute: Is the set of allowable characters inherited straight
from the XML spec? Is it self-evident that keywords can't contain spaces
because it is the keyword list separator? Couldn't comma also be used as a
separator?

Boolean attribute: it is stated that only "true" and "false" are valid
values, but that if the value is something else, the default is false. That
seems like a contradiction. Are values other than literal "true" and "false"
supposed to be actual errors, or are they silently coerced into false? (If I
accidentally type required="rue" it would come out as "false"...)


/5/ Rule for Parsing a Non-negative Integer

Couldn't we just refer to some well-established definition, if there is one
handy? Seems like this must have been done many times before. And what about
those negative numbers, then? Not needed? :-)

Hope this helps,
Jere @ Nokia

Marcos, all,

here's a bunch of comments related to the I18N/L10N related parts of the
Widgets 1.0: Packaging and Configuration spec (Last Call i.e. Working Draft
28 May 2009).

/1/ Order of material

>From an editorial standpoint, I think that the "7.2 Examples" subsection
should really be the last one in this section.

Information about element-based localization, which now is 8.15, should
appear in section 7, because the concepts are used in Section 8 before they
are even defined. It would be good to have all related info in the same
section.

My suggestion for the organization of the material is:

7 Internationalization and localization
7.1 Localization guidelines
7.2 Folder-based localization (used to be 7.3)
7.3 Element-based localization (used to be 8.15)
7.4 Localization examples (used to be "7.2 Examples", note new name)

This would make the material flow better and have all the concepts defined
before they are used.

Also, the whole of Section 7 should actually appear right before the
processing steps (i.e., after the current Section 8).


/2/ Content of examples

The localization examples are non-normative, but many developers are going
to study them closely, so it pays to fine-tune them a little (and fix a few
bugs).

In the simple example, the second file "/sp/index.html" should be labeled
"/locales/es/index.html". Similarly, in the complex example, "/locales/sp/"
should be "/locales/es".

The complex example refers to several files which really have the same
purpose. I think they should also have the same name, otherwise they cannot
be found by the same reference. That is, "/locales/es/gatos.html" should be
called "/locales/es/cats.html". Or is it intentional?

In "Fallback Behaviour Example", first paragraph, last sentence should read:
"The purpose of this 'fallback' model is to reduce the number of files that
need to be created in order to achieve localization of a widget package."
(remove 'n' from 'then', add 'in order')


/3/ Folder-based localization

Suggested addition to the authoring guideline: "A Conformance Checker (CC)
SHOULD issue a warning if there are empty locale folders in the widget
package."

This statement in the authoring guideline is puzzling: '[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 "/locales/zh-Hans/" folder and
"locales/zh").' Isn't this the opposite of what is supposed to happen in the
fallback model? If the same "a.gif" is good for both zh-Hans and zh, it
should be possible for the author to include it just once in "/locales/zh".
If the user's language list includes 'zh-Hans', it will also include 'zh',
as per Step 5. So "a.gif" will be found eventually.

Replace '"shared1.gif, shared2.gif"' with '"shared1.gif" and "shared2.gif"'.

Priority is probably a bad term to use with regard to localized folders.


/4/ The xml:lang attribute

Does the XML specification state that the values of xml:lang attributes must
be unique across instances of the same element? If yes, it is probably
redundant to repeat that in the context of all the elements in the
configuration document. If not, the statement about uniqueness could still
be factored out, for example to section 8.4, to avoid repetition.


/5/ Processing steps

Step 3: the concept of "localized config doc" appears in the Configuration
Defaults table, but that doesn't seem to exist anymore. (See also Step 6.)

Step 5: replace "unprocessed locales lists" with "unprocessed locales list"
throughout.

Consider replacing "user agent's locales" with "user agent locales"
throughout the spec.

In the first example of Step 5, why would en and en-au be swapped around
when decomposed? Would 'canonicalization' be a more suitable term here than
'decomposition'?


/6/ Runtime resolution of localized resources

What specification should describe how a reference to a resource (which
could be in a localized folder) is resolved at runtime, based on the user's
language range? That is not quite in the domain of the packaging
specification, given that it is runtime behavior. This functionality is
sketched in the fallback behavior example, but it is non-normative.


Thanks for considering these comments.

Best regards,
Jere @ Nokia

I think the first paragraph here can be dropped as you cannot test it. Optionally you could rephrase it as a non-normative note.

Why are "Reserved Characters", "control characters", and "space characters" presented in such a different way? It seems that they can be done in a single style in a single place.

It would actually be nice if a Zip archive with a single folder was allowed so you could just package a folder as Zip and ship it. Is that deliberately excluded?

On Wed, 10 Jun 2009 17:20:25 +0200, Marcos Caceres <marcosc@opera.com> wrote:
> On Wed, Jun 10, 2009 at 4:57 PM, Anne van Kesteren<annevk@opera.com>
> wrote:
>> "TO BE WRITTEN, PLEASE IGNORE" if normative material is yet to be
>> written you cannot enter Last Call. Per
>> http://www.w3.org/2005/10/Process-20051014/tr.html#return-to-wg it
>> seems you have to publish this as Working Draft again.
>
> You are reviewing the (bleeding-edge) editor's draft, Anne. Not the
> published one. That is obviously not in the published draft [1], it's
> just something I put in there yesterday during the F2F and have not
> had a chance to finish yet... I will finish that bit tomorrow.
> Obviously, that won't be in the final draft.
>
> [1] http://www.w3.org/TR/widgets/

Oh ok. All the more reason the cited process document applies though, methinks.

This has the same problem with file-extension requiring a leading dot and the table not having any.

The prose also does not make it clear that the entries in the first column may be comma-separated (and can have leading spaces, to be pedantic).

Why not use audio/wav or audio/wave for WAVE files?

An additional column mentioning the format might be nice for readers.

There's no need to recommend something twice so everything after the last semicolon can be dropped.

The usage of "inform" here assumes the user agent in question is a conformance checker. However, it is far more likely that this is a normal user agent that can run widgets. As such, the usage of inform here is inappropriate for that class of products.

Why does this not reuse the general definition of space characters? Same comment applies to "Rule for getting a list of keywords from an attribute" it seems.

I don't really like the optional ITS behavior. Also, what is the effect of having it there?

If this is a feature needed by authors it also seems better for them if they have it without all the additional namespaces.

textContent is an attribute, not a property. In bindings it might turn into a property, but that is not relevant I think.

This introduces yet another definition of whitespace, good times!

It also talks about elements in a completely different way than the algorithm just before it. This would also do well with a consistent style I think.

The algorithm itself deals with leading and trailing spaces. The additional requirement about them makes matters confusing. Please remove it.

For SVG "none, see comment." does not help as the comment does not clarify what is supposed to happen. I think the correct answer here is that SVG only works if you use the proper extension and it would be worthy to point that out crystal clear.

Also, following the definition of file-extension _none_ of the entries in the table would be matched. I.e. file-extension requires a leading dot.

The example does not match the prose description. The prose does not say anything about using an element without an xml:lang attribute. (Strangely enough.)

"This means that the user agent must match all elements of a particular type whose xml:lang attribute matches the language ranges held by the user agent locales." I do not get this definition. Is it about all elements named X having an xml:lang attribute that contains a value out of list Y? If so it might be more clear to say something like that.