Re: [widgets] conformance requirements review

Hi Dom,

Responses inline...

As before, for the sake of the Disposition of Comments, please let us
know if you are satisfied with the responses below.

On Wed, Jun 17, 2009 at 10:04 AM, Dominique Hazael-Massieux<dom@w3.org> wrote:
> Hi,
>
> I wrote a simple XSLT to extract the conformance requirements from the
> Widgets spec [1], with the following output:
> http://www.w3.org/2005/08/online_xslt/xslt?xslfile=http%3A%2F%
> 2Fdev.w3.org%2F2006%2Fwaf%2Fwidgets%2Ftests%
> 2FextractTestAssertions.xsl&xmlfile=http%3A%2F%2Fcgi.w3.org%2Fcgi-bin%
> 2Ftidy-if%3FdocAddr%3Dhttp%253A%252F%252Fwww.w3.org%252FTR%252Fwidgets%
> 252F
>
> Based on these, here is a review of the Widgets spec based on
> conformance requirements analysis:

>  * ideally, only the classes of products would appear as subjects of the
> conformance requirements; e.g. "A folder may contain zero or more file
> entries or zero or more folders" would be rephrased as "A valid widget
> package may contain folders with zero or more file entries or zero or
> more folders";

FWIW, I added the above...

>this would have two benefits: simplify the analysis of
> conformance requirements for building test suites, and identify possible
> ambiguities as to what is affected when the conformance requirements is
> not respected; that said, I don't think it is crucial so feel free to
> not go through all the conformance requirements if that's too much work

We have agreed to do this in CR. These would be editorial changes,
albeit really important ones!

>  * similarly, conformance requirements that use the passive voice are
> suspect (since they often don't tell to which class they apply)

As above.

>  * "For sniffing the content type of images formats, a user agents must
> use the rule for Identifying the media type of an image" -> this assumes
> that the user agent already knows the file it is sniffing is an image;

Yes, the UA knows it is sniffing and image because of the context
(this rule is only ever used for icons).

> if that's true, the text should make it clear why, and if not, it should
> probably be reworded to say that a user agent must sniff for images
> format first

I've removed the following assertions as they were misleading:

[[
As there is no notion of a media type within Zip, a user agent must
perform file-extension to media-type mapping, followed by content-type
sniffing, in order to determine the media type of a file.

For sniffing the content type of images formats, a user agent must use
the rule for Identifying the media type of an image. For other file
formats, a user agent must use the rule for Identifying the media type
of a file.
]]

Sniffing of images and files is controlled by Step7. Step 7 always
gives the context of what is being looked for (either a file or an
image).

To the "Rule for Identifying the Media Type of an Image" i've added
the following note:
[[
Note:This rule is only to be applied when explicitly instructed to by
the specification (during Step 7).
]]

>  * rather than say "Reserved file names must be treated as
> case-sensitive", I would amend the previous sentence to say "The
> reserved file names table, below, contains a *case-sensitive*
> list..." (and similarly for folder names)

Done.

>  * "If [...] the start file is not one that is supported by a particular
> user agent, then the CC must inform the author": does that mean that a
> CC need to know all the supported formats by all user agents? That seems
> a bit excessive - I guess I can see cases where a conformance checker
> could be configured to report knowledge on a special user agent, but
> that would need to be made explicit, and clearly shouldn't be a must
>  * "a widget may attempt to access the feature identified by the feature
> element's name attribute" I think the "may" here is not intended as a
> conformance requirement, so it probably shouldn't be marked as such

Used "can" instead of MAY

>  * there is a spurious empty <em class="ct"></em> element in "A feature
>   can<em class="ct"></em> have zero or more <a href="#parameter0"
>   title="parameter">parameters</a> associated with it."

Fixed.

>  * "The steps for processing a widget package involves nine steps that a
> user agent SHOULD follow" ; the "should" appear in upper case in the
> source, while other conformance requirements are lower case

fixed.

>  * "a user agent must to decompress" is not correct English
fixed

>  * "If a user agent encounters an unusable file entry, it must ignore
> the file entry:" is ended by a colon, but followed by a new sentence

Fixed.

>  * "The algorithm always returns a string, which may be empty": again,
> this "may" doesn't look like a conformance requirement so shouldn't be
> marked as such

Fixed.

>  * "that must eventually be presented to the end-user" - I don't think
> this is meant as a conformance requirement (e.g. a conformance checker
> is a user agent, but will probably never present any of the widget
> content to the end-user); I would reword it as "to be presented to the
> end user"

Fixed. Used your text.

>  * "an error condition can ask the user agent ignore an object" I don't
> think error conditions can ask anything to anyone in general, so I would
> rephrase it; I think "ignore" needs a preceding "to" too.
>

Ok, rewrote the section. Now reads:

"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 an attribute 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 that a user agent
must act as if the element, attribute, or file that is in error is not
present."

Is that any better?

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

Received on Tuesday, 7 July 2009 18:12:08 UTC