Re: [widgets] P&C LC, general comments

On Wed, Jun 3, 2009 at 12:50 PM,  <Jere.Kapyaho@nokia.com> wrote:
> 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.

right.

> 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 point of it being a MAY is that all the user agents are
independent. The architecture of each spec is designed to work
independently of each other where possible.

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

Woops, fixed :) This is now a MAY.

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

I changed it to:  "It is OPTIONAL for a CC to display all messages at once."

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

Yes, that is better (I had a bunch of things linking to the various
parts of the original statement, but I'll fix that up).

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

Used your text.

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

fixed.

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

Nice! Fixed for both width and height.

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

We can, but it would be a waste of time. I don't know any zip
implementation that supports this properly.

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

Right.

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

I updated the draft by using the UTF-8 ranges defined in the IRI spec
(but extended it to cover %x80 and beyond). I also relaxed language
tag requirement.

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

done.

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

changed globally.

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

Oh wwhoooooppppsss, how did I miss that one!?! In there now!

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

I don't think this is relevant, as a config file in a folder has no
special meaning. Also, if in the future we migrate to the using
multiple config files for localization, then this might not be
desirable. Is that ok?

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

Argh, true.

> 2) it is OK to extend the configuration document because there is a
> well-defined mechanism that uses namespaces. Suggestion: remove this
> statement.

Ok, I think it has served it's purpose already :) I've removed it.

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

Right. I made it 1*DIGIT throughout the ABNF.

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

I think this is ok for now. If we need negatives and non-western
number support, we can create a new attribute type.

> Keyword attribute: Is the set of allowable characters inherited straight
> from the XML spec?

Yes, this is implied.

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

That's ok, I think. The keyword is just a concept, and the whole value
of attribute is used so spaces, commas or whatever are ok. So
att="this is a keyword with spaces, and comas" would be fine and
treated as an opaque string.

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

That is correct. The same would hold for required="TRUE", which would
be "false". Not sure if we should change this or not, or keep it
strict.

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

The algorithm is based on HTML5's, but modified to handle " 100px" or
"100 200" (where 100 would be returned). It's how browses handle
img@width and img@height. I also don't want to  reference more specs,
it's a pain to have to jump around different specs looking for
definitions... especially for little ones like this one.



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

Received on Wednesday, 3 June 2009 15:30:21 UTC