Re: A categorization/placing problem - event/property pages

Hi, PhistucK-

Yes, I think we all agree with this.

Maintaining separate pages for the 'foo' event, the 'onfoo' object 
property, and the 'onfoo' attribute (where they are all equivalent) 
would not only be a maintenance nightmare, but would also be a bit 
inaccurate.

Regards-
-Doug


On 2/14/13 3:02 AM, PhistucK wrote:
> I do not quite understand your example, sorry.
>
> Anyway, I meant that this check box should make the event appear as an
> onevent property on the page of the object (as part of drawing events,
> properties and methods), so the information will still be there and the
> links, events and properties will still be listed, but all of them will
> go to the same page (that includes the combined information) of that
> event. The template should, of course, have generic text for explaining
> all of the ways of adding that event listener (property, HTML attribute
> and addEventListener) that are supported for this event.
>
> I am not sure all of this is feasible, others may know, but I think this
> is the correct way to handle this situation.
> This also has the benefit of synchronizing the information, preventing
> it from being outdated in one page and up to date in another.
>
> It is a maintenance win and an accuracy win. Everyone is happy (except
> the one who has to implement this beast ;)).
>
> ☆*PhistucK*
>
>
> On Thu, Feb 14, 2013 at 12:34 AM, Scott Rowe <scottrowe@google.com
> <mailto:scottrowe@google.com>> wrote:
>
>     Consider the IDBTransaction onerror event. It fires not on the
>     IDBTransaction error event, but on the DOMError event.
>
>     Do you propose to remove the onerror event handler property from the
>     IDBTransaction object, and assume that by providing the DOMError doc
>     with a checkbox that the user of IDBTransaction will just "know"
>     that there is an event handler in IDBTransaction for the error event?
>
>     I think that is a dangerous assumption, as it relies on "implicit"
>     knowledge. We achieve greater clarity if we are explicit about which
>     events the object handles.
>
>     Even though the IDBTransaction object does have an error property,
>     which returns the DOMError event, without the onerror event handler,
>     explicitly, the developer does not know how to name the function
>     that handles the DOMError event.
>
>     No, folks, our job is not to make it easier to document these APIs.
>     Our job is to make them easier to use - even for novices who are not
>     yet steeped in the JavaScript event handling model. This is why we
>     follow the specifications to the letter, we do not take shortcuts to
>     please ourselves, and we are explicit about every object in the
>     model and how it is used. I strongly recommend we keep it that way.
>
>     +Scott
>
>
>
>     On Wed, Feb 13, 2013 <tel:2013> at 1:01 PM, Lance Leonard
>     <Lance.Leonard@microsoft.com <mailto:Lance.Leonard@microsoft.com>>
>     wrote:
>
>         We had a similar conversation when we reorganized our content
>         and ended up combining the property page with the event page[1].
>
>         The general thinking was that it was easier on the novice to
>         have a single page to land on using search than to maintain
>         separate pages with similar content.
>
>         I'm fine either way, but do tend to prefer simplifying a
>         presentation when it makes sense to.
>
>         Hope this helps...
>
>         -- Lance
>
>         Links:
>
>         [1] - The current version of the abort event from MSDN:
>         http://msdn.microsoft.com/en-us/library/ie/ms536785(v=vs.85).aspx
>
>         -----Original Message-----
>         From: Chris Mills [mailto:cmills@opera.com
>         <mailto:cmills@opera.com>]
>         Sent: Wednesday, February 13, 2013 <tel:2013> 11:56 AM
>         To: PhistucK
>         Cc: Julee; Scott Rowe; public-webplatform@w3.org
>         <mailto:public-webplatform@w3.org>
>         Subject: Re: A categorization/placing problem - event/property pages
>
>         This kind of approach would make sense to me, however I will
>         defer decision making/handling of these to the professionals
>         (i.e. Scott) in future ;-)
>
>         Chris Mills
>         Opera Software, dev.opera.com <http://dev.opera.com>
>         W3C Fellow, web education and webplatform.org
>         <http://webplatform.org> Author of "Practical CSS3: Develop and
>         Design" (http://goo.gl/AKf9M)
>
>         On 13 Feb 2013 <tel:2013>, at 18:49, PhistucK
>         <phistuck@gmail.com <mailto:phistuck@gmail.com>> wrote:
>
>          > When I posted about this (among other issues) a few months
>         ago, I think the initial conclusion was that we should only have
>         event pages (abort) and have a check box in the event template
>         in order to specify whether it may function as a property
>         (onabort) and another check box in the event template in order
>         to specify whether it may function as a standard event listener
>         (object.addEventListener("abort", handler, false)).
>          >
>          > I think having two (or more, if you include the dreadful
>         inline HTML event listeners) pages for most events is wasteful.
>          > Perhaps we should also have a check box for its inline HTML
>         event listeners attribute and a field for the HTML element, I do
>         not know.
>          >
>          > ☆PhistucK
>          >
>          >
>          > On Wed, Feb 13, 2013 <tel:2013> at 8:39 PM, Julee
>         <julee@adobe.com <mailto:julee@adobe.com>> wrote:
>          > Is there any place where we are drawing the relationship
>         between html element attributes (onerror), object properties
>         (onerror), events (error), and event listeners (error, handler)?
>          >
>          > Or are we planning on separating out each manifestation and
>         documenting them separately?
>          >
>          > Thanks much.
>          >
>          > Julee
>          > ----------------------------
>          > julee@adobe.com <mailto:julee@adobe.com>
>          > @adobejulee
>          >
>          > From: Scott Rowe <scottrowe@google.com
>         <mailto:scottrowe@google.com>>
>          > Date: Wednesday, February 13, 2013 <tel:2013> 9:48 AM
>          > To: Chris Mills <cmills@opera.com <mailto:cmills@opera.com>>
>          > Cc: "public-webplatform@w3.org
>         <mailto:public-webplatform@w3.org>" <public-webplatform@w3.org
>         <mailto:public-webplatform@w3.org>>
>          > Subject: Re: A categorization/placing problem -
>         event/property pages
>          >
>          > Hi Chris,
>          >
>          > Let me lend some perspective to this, in line...
>          > +Scott
>          >
>          >
>          > On Wed, Feb 13, 2013 <tel:2013> at 9:03 AM, Chris Mills
>         <cmills@opera.com <mailto:cmills@opera.com>> wrote:
>          > Hi all,
>          >
>          > I am mailing to discuss a consistency problem we have come up
>         against in the properties/events pages on webplatform.org
>         <http://webplatform.org>; I have been discussing this with
>         Frederic Hemberger, who took part in the Berlin doc sprint. The
>         question is, how to categorise properyy and event pages.
>          >
>          > Crawling through the properties list
>         (http://docs.webplatform.org/w/index.php?title=Category:API_Object_Properties)
>         we have 40 event related properties:
>          >
>          > apis/file/properties/onabort
>          > apis/indexeddb/IDBTransaction/onabort
>          > apis/webrtc/RTCPeerConnection/onaddstream
>          > apis/webrtc/MediaStreamTrackList/onaddtrack
>          > apis/webaudio/ScriptProcessorNode/onaudioprocess
>          > apis/indexeddb/IDBOpenDBRequest/onblocked
>          > apis/indexeddb/IDBVersionChangeRequest/onblocked
>          > apis/appcache/ApplicationCache/oncached
>          > apis/appcache/ApplicationCache/onchecking
>          > apis/indexeddb/IDBTransaction/oncomplete
>          > apis/webrtc/RTCPeerConnection/ondatachannel
>          > apis/appcache/ApplicationCache/ondownloading
>          > apis/webrtc/MediaStream/onended
>          > etc.
>          >
>          > First, to level-set here, these are termed "event handlers"
>         and treated in the specifications as properties. We've followed
>         suit in the API docs.
>          >
>          >
>          > (Also, the File API is the only API listing those as
>          > "apis/file/properties/<propertyName>" instead of
>          > "apis/file/<propertyName>".)
>          >
>          > This was a mistake. This property belongs to the
>         msStreamReader object, and it's page is now located properly at
>         apis/file/MSStreamReader/onabort.
>          >
>          > However, it may be argued that all of the
>         Microsoft-proprietary documentation should be removed from WPD
>         as it is not standard. But that's an issue for a separate thread.
>          >
>          >
>          > On the other hand, the event page lists 54 API (61 if you
>         include SVG) and 107 DOM event pages, rather than their related
>         properties.
>          >
>          > The questions is, how should we make these more consistent?
>          >
>          > DOM events and API object events are treated differently.
>         Consistency would confuse the issue rather than clarify.
>          >
>          >
>          > 1. We could list these as event pages primarily, but then
>         have another
>          > page for the event property in each case. So for example
>          >
>          > http://docs.webplatform.org/wiki/apis/file/events/onabort
>         could be the
>          > main page, with all the info on the event and its related
>         property
>          > (but we'd be best changing onabort to abort)
>          >
>          > No. Under no circumstance should we change the names of API
>         object properties. These are defined in the spec. The event is
>         "abort," the event handler is "onabort."
>          >
>          > Incidentally, the "abort" event has yet to be documented.
>         We're on it.
>          >
>          >
>          > http://docs.webplatform.org/wiki/apis/file/properties/onabort
>         could
>          > just have a minimum of information on it, but point to the
>         above page
>          >
>          > 2. We could do basically the same, but have the property
>         pages as the main pages, and point the event pages to those.
>          >
>          > 3. We could just have the event pages, and make them cover
>         both the properties and events:
>          >
>          > http://docs.webplatform.org/wiki/apis/file/events/abort
>          >
>          > And maybe have a silent redirect on the similar property page.
>          >
>          > We (myself and Frederic) would rather go with moving the
>         40odd existing property pages to the Events listing and not
>         treat them as "real" properties for the sake of documentation
>         consistency (although this might be less precise from an
>         implementation point of view).
>          >
>          > The way we are currently representing events and event
>         handlers in the API documentation is correct. We maintain the
>         structure prescribed in the specifications.
>          >
>          >
>          > Otherwise, we'd need to move all API events to properties (if
>         you think of DOM events as a "special breed"), and/or make
>         duplicate (or at least very similar) pages. We are more
>         interested here in what is most implementable/findable, rather
>         than what is most technically correct.
>          >
>          >
>          > DOM events, on the other hand, do appear to warrant a
>         different treatment, particularly because they are shared across
>         many different objects.
>          >
>          >
>          >
>          > Thoughts?
>          >
>          > Chris Mills
>          > Opera Software, dev.opera.com <http://dev.opera.com>
>          > W3C Fellow, web education and webplatform.org
>         <http://webplatform.org> Author of "Practical
>          > CSS3: Develop and Design" (http://goo.gl/AKf9M)
>          >
>          >
>          >
>          >
>
>
>
>
>
>

Received on Thursday, 14 February 2013 08:08:18 UTC