Re: [widgets] Request for review for 14th of April

Marcos Caceres wrote:

>
> Hello again,
> This is a request for review of the *Widgets 1.0: Packaging and
> Configuration* Spec prior to publication:

Some comments:

In section "1.2 Definitions":

| A widget resource is digitally signed is it contains [...]

"is it" -> "if it".


"6. Configuration Document":

| Authoring requirement:It is recommended [...]

Missing space after the colon.

The first example uses a "title" element, which should be "name".

The second example does not declare the namespace, but "6.1 Namespace"  
says that this must be done.


"6.1 Namespace":

| [...]. If it is omited [...]

Missing a "t".


"6.2 Attribute Values and Types", "Boolen Attributes":

| [...]. A valid boolean value is must is a string [...]

Sounds strange ;-)


For the element types, some say "Contexts in which this element must/may  
be declared" and some says "present" instead of "declared". The same word  
should be used for consistency. (The word used in the HTML 5 spec is  
"used" btw. That may be even better).

The name element is the only one that has "Expected children: None.". It  
should be removed.


"7. Steps for Processing a Widget Resource":

| The steps listed as follows and are specified verify the
| zip archive its file entriesin detail in the following sub-
| sections.

"entriesin" -> "entries in". This sentence also sound extremely weird IMO.  
Is it missing some commas or something?


"7.3 Defaults":

| Icons
|   empty list of URIs

"Empty list" alone sounds better IMO, because if it's empty, there  
certainly aren't any URIs.


"7.4 Parsing Rules":

| User agents may optimize any of the parsing [...]

This is pretty much a repetition of the first note under "7. Steps for  
Processing a Widget Resource".

"Step 6 - Process the configuration document", first example:

| [...] walking an through an element's children [...]

The first "an" should be removed.

Also, in the same example there should be a "name" element, not "title".


In the schema, "title = element name" should be "name = element name".


Nitpick: Some headers (e.g. "4. Zip Archive") are bolder than others  
(because of <dfn>'s I presume). Maybe this should be fixed for consistency.

-- 
David Håsäther

Received on Friday, 4 April 2008 15:02:54 UTC