On Thu, 09 Feb 2012 14:20:57 +0100, Hallvord R. M. Steen
<[email protected]> wrote:
Anne van Kesteren <[email protected]> skreiv Fri, 09 Sep 2011 16:48:36
+0200
As a high-level comment it seems to me the organization of the
specification needs some changing. The processing model is about how to
deal with a "copy/paste/cut operation" it is not about firing an event
(that is mainly part of it). The events section meanwhile is about how
users invoke a "copy/paste/cut operation" and not so much about firing
an event either (the event summary boxes are not needed I think).
I agree that the event summary tables aren't really required, and have
removed them. I'm not quite sure what else I should do specifically to
address the comment that the "organization of the specification needs
some changing". For example regarding
The processing model is about how to deal with a "copy/paste/cut
operation" it is not about firing an event (that is mainly part of it).
..it happens to be *the* part of the processing this spec is all about
:)..?
I mean that the way it is defined currently does not make much sense. The
user initiates a "copy operation". A "copy operation" is a long list of
steps that will eventually fire a "copy" event as part of that "copy
operation".
So you should not have "When the user initiates a paste operation, the
implementation must fire a paste event." But instead you should have "When
the user initiates a paste operation, run the /paste operation steps/." or
some such.
You can also invoke such actions from script via the execCommand() APIs
apparently, but that does not appear to be described in detail.
It's mentioned in the #integration-with-other-scripts-and-events section
(8). I'm not sure where else to mention it or what more detail is
needed. execCommand() is presumably spec'ed in Aryeh's rich text editing
work.
You need some kind of hook for that though.
So first I think it would make sense to clearly distinguish between
operations and events.
Can you give me an example of a specific change to the spec's outline or
vocabulary that would help make this distinction?
I think what you want to do for maximum clarity is to define "paste
operation steps" / "copy operation steps" / etc. and include all the
details there. Including the dispatching of the event, handling of the
canceled flag of the event object being set, etc.
I think the current specification is pretty close. Section 4 just needs to
go and become part of 5.
Because there is a processing model that includes dispatching events
the section on events can probably be removed. The requirements made
therein are redundant.
Indeed. The spec evolved this way, section 4 with normal prose
description of how things are expected to work predates section 5 and
the processing model that give more exact implementation details. So we
could drop all of section 4 and just keep the processing model. However,
I think keeping the short prose description for each event in section 4
makes sense. It makes the spec more readable (and implementors are
readers too) and makes it clear what behaviour the processing model
intends to dictate.
Then you should clearly indicate section 4 is non-normative and not use
words such as "must". Specifications should not have duplicate conformance
requirements.
You will still need a section that defines when the operations are
invoked.
If section 4 were to be removed, or generally?
Well section 4 does not really say the operation is invoked; it just talks
about events somewhat confusingly (imo).
Apart from this I noticed a few other things:
* "the BODY element" should probably be defined as reference to what it
is in HTML.
Added generic reference to HTML5 after both instances of "BODY element".
Would it be better to refer to a specific section directly? I'd happily
just link the text "the BODY element" directly to
http://www.w3.org/TR/html5/sections.html#the-body-element but it seems
like specs must be a bit more pedantic about things and list references
at the bottom etc..?
Both are okay. What happens by the way if there is no body element? HTML
also defines a specific term "the body element" (or some such) that means
something different from the HTML body element.
* If you define an internal flag do not use <code> for it, but <var> or
maybe <dfn>.
Fixed. I think I've once read a spec or recommendation dealing with best
markup for a spec, but I can't find it now. If you know what document
I'm likely thinking about please send me a link :)
http://wiki.whatwg.org/wiki/How_to_write_a_spec has some advice.
* If you reference externally used terms mention that somehow. E.g.
DataTransfer's mode flag is actually called "drag data store mode".
DataTransfer in HTML is defined in terms of "drag data store" so it
would make sense to talk about the same thing here. (Maybe get it
renamed from drag to something more neutral?)
Changed instances of "mode" to "drag data store mode", "kind" to "drag
data item kind" etc. Added a reference for the HTML5 DnD chapter, and
some more referencing to this on first usage of DataTransfer. (IMO it
becomes harder to read though - as long as we're dealing with properties
of a precisely specified object it should be OK to refer to their
property names like "item" and "type". "Mode" is a bit special in that
it is AFAIK an internal flag and not visible to script authors.)
That depends as properties can be overwritten by web developers.
* "If the current clipboard part contains HTML- or XHTML-formatted
text" seems really vague (how do you tell whether it contains that?) as
are the steps that lead to creating some kind of tree. They probably
need to reference something specific in HTML.
Slightly elaborated - better now?
I guess. Clipboards are weird.
* The "Fire the event" step should be more elaborated:
http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#firing-events
"Firing an event" surely should be specified elaborately elsewhere. I
added another reference to DOM2-Events (though "fire" probably is used
without being precisely spec'ed there..).
Yes, you need to reference DOM4. Otherwise EventInit and such are
undefined too.
* The "Process the default action" step should instead talk about
whether or not the
http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#canceled-flag
of the event ended up being set and what to do when it is not.
Seems pretty readable and precise to me as-is.
Except there's no such thing as default action really...
* I think having section 7 is confusing. Cross-references would be
better.
I'm not sure. IMHO the exact semantics of certain DataTransfer object
properties when (re-)used for clipboard events should be noted
somewhere. For example the fact that an implementation of
clipboardData.items must enable "pasting multi-part or non-textual data"
should be written down. If I remove section 7, where should this
information go?
HTML. We only want a single definition of APIs.
If you want to perform cross-references between HTML, DOM, and your
specification it might be an idea to use
https://bitbucket.org/ms2ger/anolis I can help out if needed.
Think I tried to get anolis running earlier, then I came across reSpec
and just used that instead. It's very simple to just use JavaScript to
manipulate the spec - it's in HTML after all ;-). I could perhaps use
both though? Can you show me an example of how using anolis would help
cross-referencing terms/definitions from another spec, HTML5
specifically?
http://wiki.whatwg.org/wiki/Anolis has tips on how to use it. E.g. to
reference HTML fetch you would use:
<span data-anolis-spec=html>fetch</span>
--
Anne van Kesteren
http://annevankesteren.nl/
