Re: widgets feedback

Hi Josh,

Addressed your second set of comments  below.

If satisfied with the corrections, please give us
an OK for the DoC :)

On Thu, Jun 18, 2009 at 3:27 PM, timeless<timeless@gmail.com> wrote:
> Date: Tue, Jun 16, 2009 at 11:42 AM
>
> 8:42 AM me: A conformance checker (CC) is a user agent that verifies
> if a widget package and a configuration document conform to this
> specification.
>   if => whether
>

Fixed
________________________________
> 56 minutes
> 9:38 AM me: <li>when the <a class="no-toc no-num"
> href="#rule-for-verifying-a-file-entry0">rule for Verifying a File
> Entry</a><span></span> is applied to the file, it returns
>   the empty span is probably a bug

Fixed.

> 9:39 AM 6.3 Reserved File and Folder Names
>   Reserved File Names
>   you need to change 'xml' to '.xml' and similar

Fixed.

> 9:40 AM The [Widgets-DigSig] specification also defines the naming
> conventions for a distributor signature and the naming convention for
> an author signature.
>   i think you want 'for distributor signatures' and 'for author
> signatures' (plural for both)

There is only one author signature. I don't want to imply there there
can be more.

> ________________________________
> 19 minutes
> 10:00 AM me: via a an access control policy.
>   drop "a"

Fixed.

> 10:19 AM me: so, i'm not a fan of "out of scope of" (very few google
> hits), i prefer "beyond the scope of" (millions of hits)

Fixed.

> 10:21 AM me: The start file of a widget package is a file that is used
> by the user agent when the widget is instantiated.
>   kinda useless statement

Used "A start file designates the file from the widget package to be
loaded by the user agent when it instantiates the widget."

>   you use the configuration file when the widget is instantiated too

Kinda... what you really use are the Configuration Defaults which are
the result of processing the start file.

> 10:22 AM you kinda want to somehow explain that it's more than a file
> that's used. although w/o limiting things to DOM style :)
> 10:25 AM does Default Start File actually specify the order in which
> one is found

Yes, in Step 8. "For each file name in the default start files table
(from top to bottom) that has a media type that is supported by the
user agent:".

>   and if so, does it define a name for the thing that's found?

Not sure what you are asking here. The spec says the following in Step 8:

"If potential-start-file is a file, then:
  * Let widget start file be the value of potential-start-file.
  * Let start file content-type be the media type given in the media
type column of the default start files table.
Terminate this algorithm and go to Step 9."

In other words, "widget start file" is stored in the configurations
defaults, which is then initialized by the UA.

>   When a start file is not explicitly declared via the content
> element, then start file will be one of the default start files.
> 10:26 AM it'd be better if you could just reference the
> algorithmically determined start file instead of hand waving at a list

I have "Note: See Step 8 for instructions on finding a default start file."

The algorithm depends on the Default Start Files Table. I agree that
it would be cleaner if everything was in one place, but I don't think
we should bother moving it now (because we would need to fix all other
places that use a similar table/lookup structure). I think it's clear
enough.

> ________________________________
> 31 minutes
> 10:58 AM me: might not be supported on all user agents.
>   on => by

Fixed

>   then Make sure that the widget is labeled with an
>   why is Make capitalized?

Fixed.

> 11:00 AM me: you use case-sensitively 5 times and as case-sensitive 4 times
>   i don't like the latter :)
>   "as case-sensitive" => "case-sensitively"

Fixed where appropriate.

> ________________________________
> 17 minutes
> 11:19 AM me: <feature name="http://example.com/camera">
>
> <param name="autofocus" value="true"/>
>   random blank line between those two?
>   width = "200"
> viewmodes = "application fullscreen">
> 11:20 AM most things line up in this tag's attribute list, except viewmodes

Fixed

>   <preference name ="apikey"
> 11:21 AM this tag doesn't get spaces after =,... if you're trying to
> demo lots of different styles, ok, but please note that somewhere,
> otherwise, ick :)

Fixed. Made more consistent.

>   Be sure to declare the widget namespace as part of the widget
> element. If the namespace is absent, then Zip archive will be treated
> as an invalid Zip archive.
> 11:22 AM it's odd to mark a zip file as invalid because of an error in
> the widget
>   shouldn't the widget be invalid instead
>   ?

Correct. That is a bug.

> 11:24 AM Some general rule
>   rules (plural)

Fixed.

> 11:28 AM Keyword list attribute
>   oh fun, "this,is,forbidden"

It sure is. Unless that's a keyword, of course.


> 11:30 AM do we need to say that ".", "..", "...", .... are interesting?

that is the domain of the Widgets URI spec

> 11:33 AM either by default as part of the [XML] specification (as is
> the case with xml:lang) or if the user agent implements the optional
> [ITS] specification.
>   i don't think "either .. if" is a well accepted concept :)
> 11:34 AM drop "either" (it only fits "either .. or")

Changed to:
"This section describes the behavior and expected usage of other
relevant attributes that are part of the [XML] specification and the
[ITS] specification."

> ________________________________
> 5 minutes
> 11:40 AM me: Avoid subtags from the IANA Language Subtag Registry
> marked as deprecated, grandfathered, or redundant. The intended
> purpose of the xml:lang attribute is to declare the primary language
> of an element, its attributes, and its descendent nodes.
>   shouldn't CC's complain about them too?

Fixed (added CC' complaint).

> 11:42 AM A valid URI that denotes an identifier for the widget. It is
> optional for authors to use this attribute.
>   why mention 'authors'?
>   does anyone else write this file? :)

It's to be clear that that is OPTIONAL for authors, not user agents,
to use. Otherwise, it looks like it's optional for user agents to
implement (which in this case it is, but that is mentioned elsewhere).


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

Received on Friday, 3 July 2009 15:13:27 UTC