Re: [widgets] P&C Last Call comments, 4

On Mon, Jun 1, 2009 at 12:44 AM, Marcin Hanclik
<Marcin.Hanclik@access-company.com> wrote:
> 8.12
> in which case a user agents that
> should be
> in which case a user agent that

Fixed.

> In other words, the required attribute denotes that a feature is absolutely needed by the widget to function correctly,
> and without the availability of this feature the widget serves no useful purpose or won't execute properly.
> should be
> In other words, the required attribute denotes WHETHER a feature is absolutely needed by the widget to function correctly,
> and WHETHER without the availability of this feature the widget serves any useful purpose or WHETHER it will execute properly.
> or
> In other words, the value "true" of the required attribute denotes that a feature is absolutely needed by the widget to function
> correctly, and without the availability of this feature the widget serves no useful purpose or won't execute properly.
>

I met you half way: "When set to true, the required attribute...". I
also clarified what it means when it is set to false. It now reads:

"When set to true, the required attribute denotes that a feature is
absolutely needed by the widget to function correctly, and without the
availability of this feature the widget serves no useful purpose or
won't execute properly. When set to false, it denotes that a widget
can function correctly without the feature being supported or
otherwise made available by the user agent."


> ... meaning that the feature must be made available to the widget by the widget at runtime.
> should be
> ... meaning that the feature must be made available to the widget at runtime.
> or
> ... meaning that the feature must be made available to the widget by the user agent at runtime.

Right, used number 3 of your suggestions.

> 8.13
> "Outside the context of a feature  element, a param element does not represent anything and a user agent must ignore it."
> This sentence seems redundant, because the "Context in which this element may be used:" part is normative enough.
>

Right, I just wanted to make sure it is clear as its the only nestable
element. I think I might keep that in for the sake of clarity.

> 8.14
> "Unless an end-user explicitly requests that these values be reverted to the values as declared in the configuration document, a
>
> user agent must not revert to these values on subsequent initialization of the widget."
> More information about management of these values is needed. What is reverting? How can the end-user explicitly request that these values are reverted to the value from config.xml? This is UI/UX aspect that needs specification.
>

I second what Robin said wrt UI. I rewrote and moved the rest as: "A
user agent must not reset the value of the widget preferences variable
on subsequent initialization of the widget." This sentence is now part
of the "widget preferences" configuration default.

Regarding management, the spec tries to make it clear that management
of the values is handled via the Widgets A&E spec:

"A user agent that supports the [Widgets-APIs] specification must
expose any declared preference to the author at runtime via scripting
in the manner described in the [Widgets-APIs] specification. In
addition, unless a preference is explicitly marked as read-only (via
the readonly attribute), it must be possible for authors to override
and delete preference values at runtime via the relevant methods
defined in the [Widgets-APIs] specification."

> 8.15
> I suggest to move this section before section 8.5, because it defines what "Localizable" (used from 8.5) means.
>

Ok, moved.

> 8.16
> The its:dir attribute and the <its:span> element can each be used as a child of ...
> should be
> The <its:span> element with the its:dir attribute MAY each be used as a child of ...

I added the "may". Also, the its:dir attribute can be used
independently of <its:span>, for example:

<hello ...>
     <bla its:dir="rtl">Look Ma! no its:span! </bla>
     <its:span>Wow! that's great!</its:span>
</hello>

> 9.
> Rule for getting a list of keywords from an attribute
> There are dropping and chopping (operations not clearly defined). Maybe the algorithm could be defined more precisely?
> It returns a list, takes a string as input.

I've made sure all algorithms now say what they return.

> So the first suggestion is to use different variable name from the temporary "result" and the actual "result".
>

I think the algorithm is fine as is. I've replaced the words "drop"
and "chop" with "remove" and "split", respectively. Hopefully remove
and split are more clear without needing write the actual algorithms
as to how to perform them.


> 9.1 Step 7
> "During the processing of a configuration document, an error condition can ask the user agent ignore an object (e.g., a file or a DOM node)."
> Not sure what it means.
Let me try that again,

"The term in error is used in this Step to mean that an element, or
attribute, or file in a configuration document is non-conforming to
the rules of this specification. How an element, or attribute, or file
is to be treated when it is in error is always given when the term is
used; but will generally require the user agent to ignore any element,
attribute, or file that is in error. To ignore means user agent must
act as if the element, or attribute, or file is not present."

Is that any better?


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

Received on Tuesday, 2 June 2009 13:42:25 UTC