[widgets] P&C LC, general comments

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

Received on Wednesday, 3 June 2009 10:50:51 UTC