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
:)..?
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.
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?
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.
You will still need a section that defines when the operations are
invoked.
If section 4 were to be removed, or generally?
Alternatively, you could leave that out of scope for the HTML Editing
APIs specification.
For execCommand() I'll do that, I think.
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..?
* 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 :)
* 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.)
* "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?
* 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..).
* 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.
* Since ClipboardEvent is new we do not need to introduce
initClipboardEvent() and go solely for an event constructor.
Removed the init method.
* 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?
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?
--
Hallvord R. M. Steen
Core tester, Opera Software
