Re: [Clipboard] Processing model feedback (and other)

Anne van Kesteren <annevk@opera.com> 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

Received on Thursday, 9 February 2012 13:21:35 UTC