RE: Reminder: January 31 comment deadline for LCWD of Widgets 1.0: Packaging & Configuration spec

Hi Marcos,

Many thanks for the thorough feedback - I'm glad the comments were
useful.

Some quick responses below for the editorial comments (marked [mp]). I
will address your other comments in the next couple of days.

Thanks again,

Mark


> -----------------------------------------------
> 6 Widget Resources
>
> First 5 bullets should say "and/or" rather than "or" ?

"Zero and/or more" sounds weird to me (i.e., "Zero and more"). If you
feel strongly about this, I will change it; otherwise, I would prefer to
leave it as is.

[mp] Sorry my comment wasn't clear - I meant the second or in the
sentence ;) For example:

"One or more start files, located at the root of the widget
<insert>and/</insert> or in localized folders."

Not a big thing so I'll leave it to your discretion.

> -----------------------------------------------
> 6.5 Content Localization
>
> "The container for localized content is a folder at the root of the 
> widget whose the first five characters of the folder-name case 
> insensitively match the string 'locales/'." Why the first five 
> characters only?

That was a mistake, the sentence now reads:
"The container for localized content is a folder at the root of the
widget whose folder-name case insensitively match the string 'locales/'.
A container for localized content may contain zero or more localized
folders."

> Also sentence has an extra "the" in the middle, i.e. "whose *the*
first"

fixed.

[mp] Great - thanks

> -----------------------------------------------
> 6.6 Start file and Default Start Files Sentence
>
> For consistency with other sections I suggest to add:
>
> "A default start file is a start file whose file-name case 
> insensitively matches a file-name given in the first column of the 
> default start files below and whose MIME type matches the MIME type 
> given in the second column of the table."
>
> before the sentence starting: "A default start file is a start file 
> that a widget user agent..."

Ok, I think there was a more significant problem: I've defined "custom
start files" and "default start files". As a result, I changed that
whole section.

> And then to combine the last two sentences before the default start 
> files table to:
>
> "A widget user agent will attempt to locate a file entry whose 
> file-name case insensitively matches one of the default start files 
> based on the order they appear in the table below (from top to
bottom). "

Can you please check that section again and let me know if the rewrite
is ok?

[mp] Looks good to me - thanks

> -----------------------------------------------
> 7.1 Namespace
>
> It seems a bit tough that an invalid configuration document results in

> a invalid widget as the configuration document is optional. Also, if 
> the configuration document in the localised folder is invalid, it 
> could be the case that there is a valid configuration document at the 
> root of the widget.
>
> I don't have a strong opinion on this and have no objection to leaving

> the text as it is, I just wondered if there was a reason why this 
> approach had been taken?

Although I agree that it's a bit cruel on developers, we made this
decision to make the behaviour of configuration documents predictable.
I feel pretty strongly that we should leave it as is.

[mp] Fine for me

> -----------------------------------------------
> 7.2 Proprietary Extensions
>
> Should the "may" be a "should"? Otherwise, it could be interpreted as 
> suggesting that vendors may equally use other approaches?

Right, fixed. This should, in fact, be a must (i.e., if you want to
extend, then you must use your own namespace).

[mp] Agree and thanks

> -----------------------------------------------
> 7.9 The icon Element
>
> (disclaimer - I may well be talking rubbish here as the following 
> comments are based on a _very_ basic understanding of graphics 
> formats)
>
> The text says that if the icon is vector format then the height and 
> width attributes will be used, however, isn't one the point of using 
> vector graphics that they could be re-sized to fit the available
space.

Yes and no. Beyond certain sizes (e.g., too little, too big), the
rendering engine may have undesirable effects on a design (think, for
example, of a really tiny font having anti-alias applied to it:
because of sub-pixel interpolation, it becomes too blurry to read. The
same can happen with graphics, very thin lines can vanish or become
blurry, which can make a design look crappy). In such cases, it may be
desirable to use a bitmap.

[mp] OK, I understand this point but... see next response

> Therefore shouldn't there be a statement saying that the widget user 
> agent MAY ignore these values?

No, the width and height attributes represent the _minimum_ size at
which an image may be used. Then, the vector graphic can behave in the
manner you describe (i.e., can be used to fill a rendering context
larger than the width and height).

[mp] Hmm, in this case shouldn't the spec explicitly state that these
are minimum height and widths for vector graphics and that the widget
user agent may use bigger heights and widths if it wants to? 

>Equally should there be default sizes in case the attribute is not
used?

Hmm... good point. I've added that as an issue in the relevant section.

[mp] OK - no strong opinion on this I was just really asking a question

> In terms of raster graphics the text currently says "If the file 
> pointed to by the src is a supported raster graphic, this value may be

> ignored by the widget user agent." but shouldn't the "may" in this 
> case be a "should"?

Correct, but that "should" should be a "must". Fixed.

[mp] Even better, thanks.


> -----------------------------------------------
> 7.13 The feature Element
>
> In the sentence "The feature is used by an author to denote that, at 
> runtime, a widget may require access to a feature." the use of "may 
> require" is very slightly confusing given that the next attribute is 
> "required". Suggest changing "require" to "try to" or "attempt to".

Changed "require" to "attempt to".

[mp] Thanks

> Likewise in the definition of the name attribute in the sentence "A 
> URI attribute that identifies a feature required by the widget at 
> runtime (such as an API)." change "required by" to "that may be used".

Done.

[mp] Thanks


> -----------------------------------------------
> 8 Steps for Processing a Widget Resource
>
> The sentence "The steps for processing a widget resource involves ten 
> steps that a widget user agent must follow, in sequential order, 
> responding accordingly if any of the steps result in an error." could 
> be slightly misleading as some of the steps are skipped depending on 
> the processing in a preceding step. I'm not sure if this is always in 
> a response to an error?

Ok, I changed it to: "The steps for processing a widget resource
involves ten steps that a user agent must follow, in sequential order,
responding accordingly if any of the steps result in an error or if the
specification asks for the user agent to skip a step."

Is that any better?

[mp] Yep - sorry if I was being over pedantic :(

> A minor comment on section 8 as a whole - some of the steps have an 
> explicit link to go to the next step while others (like 9) don't. It 
> would be nice if this was consistent.

Ok, I checked every step and made sure things are consistent. Once all
the comments are done, I'll do another editorial round to make sure
everything is more consistent.

> In addition, some of the algorithms, for example step 7, could be made

> clearer by explicitly stating when to go to the next step (i.e. in 
> case of success in 7.1 and 7.2).

Ok, I did what you said for step 7 and Step 8. Can you let me know which
other ones need a rewrite?

> Finally, in Step 6 there is a sentence "Else, remove the last subtag 
> of the range and repeat this step 2.d. (e.g., if the range ...". Just 
> to be super clear perhaps "this step 2.d." could be change to "and go 
> to 2.d of this algorithm"

Made the change you suggested.

[mp] All of the above changes for Section 8 look good to me- thanks.

 

>-----Original Message-----
>From: Marcos Caceres [mailto:marcosscaceres@gmail.com] 
>Sent: 04 February 2009 17:35
>To: Priestley, Mark, VF-Group
>Cc: Arthur Barstow; public-webapps
>Subject: Re: Reminder: January 31 comment deadline for LCWD of 
>Widgets 1.0: Packaging & Configuration spec
>
>Hi Mark,
>On Thu, Jan 29, 2009 at 6:29 PM, Priestley, Mark, VF-Group 
><Mark.Priestley@vodafone.com> wrote:
>>
>> Hi Marcos, Art, All,
>>
>> Please find below Vodafone's comments on the Widgets 1.0: Packaging 
>> and Configuration specification. I have divided them into what I 
>> consider to be substantive comments and editorial comments.
>>
>> Thanks,
>>
>> Mark
>>
>>
>> 
>----------------------------------------------------------------------
>> --
>> ----------------------
>> Substantive comments
>> 
>----------------------------------------------------------------------
>> --
>> ----------------------
>> Step 5 Process the Digital Signatures
>>
>> We disagree with the stage 2, specifically "If the file entry is 
>> deemed by the [Widgets-DigSig] to be an invalid widget, then 
>a widget 
>> user agent must treat this widget as an invalid widget.", on 
>two grounds:
>>
>> (1) Because one signature is invalid it doesn't mean that all of the 
>> signatures are invalid;
>> (2) Just because one signature or all signatures are invalid 
>does not 
>> mean that the widget should not be installed, only that it should 
>> _not_ be treated as a signed widget. The security policy of 
>the device 
>> might be configured not to install an unsigned widget or a 
>widget with 
>> an invalid signature but this should be dependent on the security 
>> policy implemented.
>
>Sorry, I think you might have misunderstood what I was trying 
>to say here (probably I did not write it clearly enough). This 
>assertion is here to deal with instances where the digital 
>signature deemed by the Widgets Dig Sig spec to be somehow 
>fully broken or completely non-conforming in such a way that 
>all processing must stop. I don't yet know if Widgets Dig Sig 
>will spit out such a result for any digsig it is processing, 
>but it seemed like a good idea to put this in here at the time.
>
>In other words, this is something that is controlled by the 
>Widgets Dig Sig spec. If it turns out that Widgets Dig Sig 
>never results in an invalid widget situation, then I will take 
>this out. I've created a red note in the spec that says 
>"Issue: [Widgets-DigSig] may never identify a widget package 
>as invalid" as a reminder that we need to sort this out.
>
>FWIW, I think step 5  is buggy and needs a rewrite (I've added 
>another issue to the spec stating as such). I'll need to work 
>with you to fix it as we progress the Dig Sig spec.
>
>> -----------------------------------------------
>> Step 4 Locate Digital Signatures for the Widget
>>
>> I'm not sure whether the packaging and configuration 
>specification is 
>> the correct place to do this but IMHO there needs to be a statement 
>> that a files with a file name corresponding to the naming convention 
>> for digital signatures are not accessible from the widget once the 
>> widget is installed / instantiated. Failure to impose this 
>restriction 
>> will make it possible to include a signature and then reference it 
>> from the signed code, which presents a security hole.
>
>Good point. This seems like something that needs to be in the 
>yet to be written a widget runtime security spec.  I've added 
>an issue note to the spec so we don't forget about this.
>
>Just out of interest, can you present the nature of the security hole?
>i.e., once an attacker has the signature, say, via an XSS 
>attack, what could they do with it?
>
>> -----------------------------------------------
>> 7.10 The access Element
>>
>> The access element defines a network attribute as "A boolean 
>attribute 
>> that indicates that the widget might need to access network 
>resources 
>> as specified in [Widgets-Security]. "
>>
>> Based on this description we would like to make the following 
>> observations and suggestion:
>>
>> The access element contains security permissions that will 
>be used as 
>> hooks in the yet to be written [Widgets-Security] specification. The 
>> problem is that the permissions haven't yet been discussed in detail 
>> and so we may find that we want to represent additional 
>context other 
>> than a black and white "is network access required?". For 
>example, it 
>> may be the case that it is important from a security point 
>of view to 
>> know which bearer or protocol will be used, or to nest a set of 
>> domains/URLs with which the widget wants to communicate. I 
>do not have 
>> a strong view on what might be relevant here, and I am not 
>suggesting 
>> that it needs to be considered as part of the last call of the 
>> Packaging and Configuration spec, only that it is likely that the 
>> permission will need to be more complex when we look at it 
>from a security perspective.
>
>I think we better start this soon, then. My feeling is that we 
>will need some kind of <domain> access declarations, and I 
>would like to see them in the configuration document.
>
>__This has the potential to block progress of this specification.__
>
>> There is also the case in which the network permission may 
>be used to 
>> determine whether or not the user wants to install a widget,
>
>This sounds reasonable.
>
>> or by the
>> widget user agent may want to indicate whether or not the widget can 
>> run when there is no available network connection. Some widgets may 
>> only operate when there is a network connection, whereas others may 
>> degrade gracefully.
>
>This sounds like something authors need to deal with, not user agents.
>
>> So to provide a degree of future-proofing we would like to suggest 
>> something like:
>>
>> <access>
>>    <network use="true/false" required="true/false"/> </access>
>
>We might not need this at all, actually: If we go down the 
>declaring domain route, then network is off unless a domain is 
>declared.
>
>> (I realise that the "use" attribute in the above example is 
>a horrible 
>> name but I couldn't think of another word for access...There are 
>> probably also better ways of capturing the meaning - we open to 
>> suggested improvements)
>
>This needs further discussion.
>
>> Sorry for not raising this earlier but it has only become apparent 
>> when considering in more detail how the access element would be used.
>
>No probs.
>
>>
>> 
>----------------------------------------------------------------------
>> --
>> ----------------------
>> Editorial comments
>> 
>----------------------------------------------------------------------
>> --
>> ----------------------
>> 6 Widget Resources
>>
>> First 5 bullets should say "and/or" rather than "or" ?
>
>"Zero and/or more" sounds weird to me (i.e., "Zero and more"). 
>If you feel strongly about this, I will change it; otherwise, 
>I would prefer to leave it as is.
>
>> -----------------------------------------------
>> 6.5 Content Localization
>>
>> "The container for localized content is a folder at the root of the 
>> widget whose the first five characters of the folder-name case 
>> insensitively match the string 'locales/'." Why the first five 
>> characters only?
>
>That was a mistake, the sentence now reads:
>"The container for localized content is a folder at the root 
>of the widget whose folder-name case insensitively match the 
>string 'locales/'. A container for localized content may 
>contain zero or more localized folders."
>
>> Also sentence has an extra "the" in the middle, i.e. "whose 
>*the* first"
>
>fixed.
>
>> -----------------------------------------------
>> 6.6 Start file and Default Start Files Sentence
>>
>> For consistency with other sections I suggest to add:
>>
>> "A default start file is a start file whose file-name case 
>> insensitively matches a file-name given in the first column of the 
>> default start files below and whose MIME type matches the MIME type 
>> given in the second column of the table."
>>
>> before the sentence starting: "A default start file is a start file 
>> that a widget user agent..."
>
>Ok, I think there was a more significant problem: I've defined 
>"custom start files" and "default start files". As a result, I 
>changed that whole section.
>
>> And then to combine the last two sentences before the default start 
>> files table to:
>>
>> "A widget user agent will attempt to locate a file entry whose 
>> file-name case insensitively matches one of the default start files 
>> based on the order they appear in the table below (from top 
>to bottom). "
>
>Can you please check that section again and let me know if the 
>rewrite is ok?
>
>> -----------------------------------------------
>> 7.1 Namespace
>>
>> It seems a bit tough that an invalid configuration document 
>results in 
>> a invalid widget as the configuration document is optional. Also, if 
>> the configuration document in the localised folder is invalid, it 
>> could be the case that there is a valid configuration 
>document at the 
>> root of the widget.
>>
>> I don't have a strong opinion on this and have no objection 
>to leaving 
>> the text as it is, I just wondered if there was a reason why this 
>> approach had been taken?
>
>Although I agree that it's a bit cruel on developers, we made 
>this decision to make the behavior of configuration documents 
>predictable.
>I feel pretty strongly that we should leave it as is.
>
>> -----------------------------------------------
>> 7.2 Proprietary Extensions
>>
>> Should the "may" be a "should"? Otherwise, it could be 
>interpreted as 
>> suggesting that vendors may equally use other approaches?
>
>Right, fixed. This should, in fact, be a must (i.e., if you 
>want to extend, then you must use your own namespace).
>
>> -----------------------------------------------
>> 7.9 The icon Element
>>
>> (disclaimer - I may well be talking rubbish here as the following 
>> comments are based on a _very_ basic understanding of graphics 
>> formats)
>>
>> The text says that if the icon is vector format then the height and 
>> width attributes will be used, however, isn't one the point of using 
>> vector graphics that they could be re-sized to fit the 
>available space.
>
>Yes and no. Beyond certain sizes (e.g., too little, too big), 
>the rendering engine may have undesirable effects on a design 
>(think, for example, of a really tiny font having anti-alias 
>applied to it:
>because of sub-pixel interpolation, it becomes too blurry to 
>read. The same can happen with graphics, very thin lines can 
>vanish or become blurry, which can make a design look crappy). 
>In such cases, it may be desirable to use a bitmap.
>
>> Therefore shouldn't there be a statement saying that the widget user 
>> agent MAY ignore these values?
>
>No, the width and height attributes represent the _minimum_ 
>size at which an image may be used. Then, the vector graphic 
>can behave in the manner you describe (i.e., can be used to 
>fill a rendering context larger than the width and height).
>
>>Equally should there be default sizes in case the attribute 
>is not used?
>
>Hmm... good point. I've added that as an issue in the relevant section.
>
>> In terms of raster graphics the text currently says "If the file 
>> pointed to by the src is a supported raster graphic, this 
>value may be 
>> ignored by the widget user agent." but shouldn't the "may" in this 
>> case be a "should"?
>
>Correct, but that "should" should be a "must". Fixed.
>
>> -----------------------------------------------
>> 7.13 The feature Element
>>
>> In the sentence "The feature is used by an author to denote that, at 
>> runtime, a widget may require access to a feature." the use of "may 
>> require" is very slightly confusing given that the next attribute is 
>> "required". Suggest changing "require" to "try to" or "attempt to".
>
>Changed "require" to "attempt to".
>
>> Likewise in the definition of the name attribute in the sentence "A 
>> URI attribute that identifies a feature required by the widget at 
>> runtime (such as an API)." change "required by" to "that may 
>be used".
>
>Done.
>
>> -----------------------------------------------
>> 8 Steps for Processing a Widget Resource
>>
>> The sentence "The steps for processing a widget resource 
>involves ten 
>> steps that a widget user agent must follow, in sequential order, 
>> responding accordingly if any of the steps result in an 
>error." could 
>> be slightly misleading as some of the steps are skipped depending on 
>> the processing in a preceding step. I'm not sure if this is 
>always in 
>> a response to an error?
>
>Ok, I changed it to: "The steps for processing a widget 
>resource involves ten steps that a user agent must follow, in 
>sequential order, responding accordingly if any of the steps 
>result in an error or if the specification asks for the user 
>agent to skip a step."
>
>Is that any better?
>
>> A minor comment on section 8 as a whole - some of the steps have an 
>> explicit link to go to the next step while others (like 9) don't. It 
>> would be nice if this was consistent.
>
>Ok, I checked every step and made sure things are consistent. 
>Once all the comments are done, I'll do another editorial 
>round to make sure everything is more consistent.
>
>> In addition, some of the algorithms, for example step 7, 
>could be made 
>> clearer by explicitly stating when to go to the next step (i.e. in 
>> case of success in 7.1 and 7.2).
>
>Ok, I did what you said for step 7 and Step 8. Can you let me 
>know which other ones need a rewrite?
>
>> Finally, in Step 6 there is a sentence "Else, remove the last subtag 
>> of the range and repeat this step 2.d. (e.g., if the range 
>...". Just 
>> to be super clear perhaps "this step 2.d." could be change 
>to "and go 
>> to 2.d of this algorithm"
>
>Made the change you suggested.
>
>Very much appreciate Vodafone taking the time to conduct this review.
>
>Kind regards,
>Marcos
>--
>Marcos Caceres
>http://datadriven.com.au
>

Received on Thursday, 5 February 2009 14:35:55 UTC