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

On Thu, 09 Feb 2012 14:20:57 +0100, Hallvord R. M. Steen  
<hallvord@opera.com> wrote:
> 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  
> :)..?

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/

Received on Thursday, 16 February 2012 13:36:23 UTC