[widgets] conformance requirements review

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"; 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
 * similarly, conformance requirements that use the passive voice are
suspect (since they often don't tell to which class they apply)
 * "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;
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
 * 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)
 * "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
 * 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."
 * "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
 * "a user agent must to decompress" is not correct English
 * "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
 * "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
 * "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"
 * "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.

HTH,

Dom

1. http://dev.w3.org/2006/waf/widgets/tests/extractTestAssertions.xsl

Received on Wednesday, 17 June 2009 08:04:37 UTC