Re: [widgets] Editorial Comments on 18-Aug-2009 LCWD of A&E spec

Hi Artb,

On Wed, Sep 9, 2009 at 8:32 PM, Arthur Barstow <art.barstow@nokia.com> wrote:
> A few editorial comments on Sections 1-3 of the 18-August-2009 LCWD of the
> A&E spec:
>
>  http://www.w3.org/TR/2009/WD-widgets-apis-20090818/
>
> -Regards, Art Barstow
>
> 1. Section 1: given this spec does no longer includes the notification
> methods, delete the following bullet:
>
> [[
> # and requests the user's attention in a device independent manner.
> ]]

Fixed.
> (There is also a "programmbe" typo in the 1-Sep-2009 ED of the widget
> Interface spec.)

Fixed.

> 2. Section 1.1: since none of the documents in the list are Recommendations
> and hence by definition are subject to change, delete the list and replace
> it with a pointer to a non-normative "living document" (e.g. a wiki page).

Ok, deleted the list and left:
[[
The Widget Family of Specifications
This section is non-normative.
This specification is part of the Widgets 1.0 family of
specifications, which together standardize widgets as a whole. Please
see the working group's wiki for more information.
]]

Can I be a PITA and ask you to set up the wiki page and just reuse the
old text. Then I will link to it.

> 3. Section 1.2: since [Widgets-Reqs] documents requirements but doesn't
> formally "address" any requirements, change "... are addressed ..." to "...
> are documented ...".

Fixed. Fixed also in P&C TSE.

> 4. Section 1.2: I don't think the spec should enumerate stuff it does not
> define thus I would remove the "not addressed in this spec" paragraph and
> its list.

Deleted.

> 5. Section 2: change the order of the definitions to alphabetic ordering

done (you owe me a beer for that one!)

> 6. Section 2: typo for Author script - should be "A script ..."

fixed

> 7. Section 2: Feature: this is defined in a Normative section but includes
> as part of its definition the non-normative "widgets spec family". Its
> definition should only use normative text.

I changed it to:

"A runtime component (e.g. a device API, video decoder, etc.) that is
made available by the user agent to the widget context as a direct
result of an author requesting its availability via a feature element
in the widget's configuration document."

> 8. Section 2: Viewport: The second sentence puts a normative requirement on
> the UA without any rationale. It also doesn't seem appropriate in the
> Definitions section (if at all in this spec).

Woops. Copied it to width and height.

> 9. Section 2: Getting and Setting: seems like there should a [Reference]



> 10. Section 2: Initialization: I don't understand this sentence, which when
> shortened is effectively "The first run through X, prior to runtime.".

How about:

"When a user agent first runs a widget package through the Steps for
Processing a Widget Package, as specified in the [Widgets-Packaging]
specification, prior to runtime."

That boils down to:

When a user agent first runs a widget package through X, prior to runtime.

> 11. Section 3: The preface "As well as sections marked as non-normative,"
> isn't necessary.

Although I agree, I'll leave it (according to google, quite a few
other specs use that exact same wording.)


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

Received on Friday, 11 September 2009 18:48:21 UTC