Hi Ian,
On Fri, 31 Oct 2008 15:24:14 -0400, Ian Hickson [EMAIL PROTECTED] wrote:
http://dev.w3.org/2006/webapi/progress/Progress.html
I guess
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.25
in particular, since that was the latest draft when I received this email.
The draft says:
# The terms must, should, may, must not, should not, are used in this
# document in accordance with [RFC2119]...
However, I think the terms are used a bit loosely so far. I will attempt
to point out cases of this in the spec in this e-mail.
...
# User agent
# A user agent must implement all the requirements described for user
# agents throughout this specification in order to be a conforming user
# agent. A conforming user agent should implement all the recommendations
# for user agents as well.
Given the definition of must and should, this seems redundant.
Having received several comments asking for real clarity on what is
required (including from you), I am happy to stick with redundant
statements, where they serve to repeat a requirement and don't cause
confusion.
# Content
# Conforming content must generate and consume progress events in
# accordance with the definitions of those events in this
# specification, and in accordance with any additional conformance
# requirements defined by a specification which describes an operation
# that can lead to progress events being dispatched.
I think it is wrong to make content non-conforming because it fires
events in a fashion that isn't consistent with this draft.
These are conformance requirements. Nothing forces content to be
conforming, but it is valuable to have a clear explanation of what
conformance means (otherwise why would you have bothered commenting on the
need for such clarity).
There are many reasons for doing so...
There are some reasons why this might be done, but I don't see any example
sufficiently compelling to effectively abrogate a sense of conformance for
content.
# 2.1 Event definitions
The table comes before the concepts are introduced, which is confusing,
because there are must requirements in the table that don't really make
sense without context.
On the other hand, introducing the concepts before the table breaks the
principle of pyramid writing.
Having a simple summary of a longer section be the first part of that
section can aid overall comprehension of that section. Conversely,
presenting the reader with a lot of prose that must be waded through can
actually pose a significant barrier to efficient understanding of the
content.
The table does not stand on its own until the rest of the content is
known, but it provides a shorthand that can be used to understand the
whole section - and so for a repeat reader I believe it is a helpful
shorthand (so long as it does not contradict what follows, or provide a
misleading impression by omission of important data). Likewise for an
initial reader it gives them a conceptual framework they can then adorn
with the further information supplied afterwards, rather than requiring
them to digest a lot of data before they have such a conceptual framework
for processing it.
For example, what does it mean for an event to be
dispatched first? First relative to what?
First relative to other events defined by this specification. Do you find
that assumption unnatural? If so, what did you think it referred to?
(It is possible to misunderstand anything, with a small effort. My goal in
this spec is to make it *sufficiently clear*, so it is possible to
understand it correctly with less effort than it takes to imagine an
alternative meaning. Adding more prose to the specification /ipso facto/
makes misunderstanding more likely, so there is a tension between
comprehensiveness and comprehensibility).
However, in general I'm not sure that it makes sense for that table to
have these requirements anyway. load, for example, fires in many more
cases than the table suggests, and sometimes, indeed in the most common
cases in HTML, load and error are not alternatives but are unrelated.
I will look at clarifying the fact that statements are relative to things
defined within the specification.
Do these requirements mean that if a script calls dispatchEvent(), that
the UA would be non-conforming if it dispatched the event? e.g. if the
script fires 'abort', then 'load', then 'progress', then 'loadstart'
twice, is the UA non-conforming? The text is unclear.
If the script (content) calls for the events to be dispatched in a
non-conforming order, then the content is non-conforming. That a
conformant UA can support non-conformant content is unclear - I will
clarify that in the text.
I think it would be helpful to consider how to test this section without
another spec. I think one would find it impossible to do so. Thus, and
since another spec would define the order with MUST-level requirements
