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

Hi,

 

Just wanted to add some technical notes! :)

 

The good news: SMW adds itself to the MW API [1], so that could be used for querying.

 

The bad news: redirects don’t support semantic properties, they are treated as synonyms for their target by SMW. That means …/error and …/onerror (if it redirects to …/error) are the same thing and only “error” would be returned by a query. I say that, because we basically define what a page’s parent is, on the page itself (via semantic properties like “Applies to”).

Possible solution: define siblings that got merged into that page *on that page* (though I don’t have a working solution for that thought up yet)

 

The other bad news (yeah, sorry!): if we use something like listing subpages [2], we’d obviously also need to show redirects. But some redirects are used to redirect faulty pages or ones created by accident to the proper location (sometimes even under another parent).

Possible solution: delete *those kinds* of redirects

 

 

[1] http://docs.webplatform.org/w/api.php?action=ask <http://docs.webplatform.org/w/api.php?action=ask&query=%5b%5bEvent%20applies%20to::dom/HTMLMediaElement%5d%5d> &query=[[Event%20applies%20to::dom/HTMLMediaElement]]

[2] http://docs.webplatform.org/w/api.php?action=query <http://docs.webplatform.org/w/api.php?action=query&list=allpages&apprefix=apis/audio-video/&aplimit=1000> &list=allpages&apprefix=apis/audio-video/&aplimit=1000

 

-fro

 

From: Lance Leonard [mailto:Lance.Leonard@microsoft.com] 
Sent: Donnerstag, 14. Februar 2013 20:05
To: PhistucK; Scott Rowe
Cc: Doug Schepers; Chris Mills; Julee; public-webplatform@w3.org
Subject: RE: A categorization/placing problem - event/property pages

 

A redirect makes a lot of sense, especially for the set of events that have simple corresponding event properties.  I can imagine benefits for long term maintenance (fewer, more focused places for people to make comments), SEO, etc.

 

It also makes sense that there are APIs where you can’t and shouldn’t combine the pages, such as the IDBTransaction.onerror property.  Combination will depend on the API.  

 

It also makes sense to clearly document the events supported by individual objects; however, that can be done without creating separate pages for each occurrence.  You wouldn’t expect, for example, to have two copies of the DOMError object. (Not only would that lead to a maintenance nightmare, it would dilute SEO and complicate life for the reader.)   Instead, you would expect that the list of events shown on the IDBTransaction page to include a link to the error event topic under the DOM hierarchy (or wherever it’s located).

 

If an event property page is redirected to an event handler page, the event handler page should contain a syntax line showing the event property so that the connection between the two is explicit, rather than implicit.  Ideally, there would be nice code samples (with feature detection and fallback) that folks can reuse and recycle.

 

I like Janet’s idea of a solid overview regarding general event handling; that seems like a useful way to set expectation and to talk about the gritty details.

 

Hope this helps…

 

-- Lance

 

From: PhistucK [mailto:phistuck@gmail.com] 
Sent: Thursday, February 14, 2013 10:19 AM
To: Scott Rowe
Cc: Doug Schepers; Lance Leonard; Chris Mills; Julee; public-webplatform@w3.org
Subject: Re: A categorization/placing problem - event/property pages

 

I did not suggest there would not be URLs for these properties, I just suggested that the information for practically the same thing should be combined.

There should definitely be apis/indexeddb/IDBTransaction/error and apis/indexeddb/IDBTransaction/onerror, but the latter should redirect to the former.

 

This should only be the case if both of them practically mean same thing, however(!), I believe your mentioned example is not a relevant one. error is simply a property, it is not an event. It contains data about the error, yes, but it is not an event of any kind (correct me if I am wrong).

By contrast, the onfocus property, the onfocus HTML attribute and the focus event (using addEventListener) are the same thing for this purpose. The focus method is not the same thing and should not be combined.

(I am not sure regarding the FocusEvent constructor/object - but I believe it is not the same and should not be combined)

And all three of them should have their own URLs, but onfocus should redirect to the focus event page.

 

Furthermore, I believe tools should use an API, rather than crawl the actual wiki and the API should reflect all of the properties/methods/events for this purpose (using the meta data found on the combined event pages, just like I mentioned that the listing/API object method/event/property listing pages on the wiki should).

 

It is true that these are different entities, but duplicating asynchronous information causes much greater inaccuracy here, which benefits the users much less.

I am totally in favor of correctness, but I do not think duplicate pages adds to the correctness of the information.

 

☆PhistucK

 

On Thu, Feb 14, 2013 at 8:01 PM, Scott Rowe <scottrowe@google.com> wrote:

Hmm. Let's not overlook the importance of semantics and structure here. Semantics matter. The onerror event handler is a property, a separate property of the IDBTransaction object. Structure matters. The onerror event belongs under the IDBTransaction object, not within or under the error property. You wouldn't write this:

 

transaction.error.onerror = function(event) {

  // Do something

};

 

rather, this:

 

transaction.onerror = function(event) {

  // Do something

};

 

Likewise, the documentation's structure, reflected in the URL, should look like this:

 

apis/indexeddb/IDBTransaction/onerror

 

not this:

 

apis/indexeddb/IDBTransaction/error          (with onerror hidden in this location)

 

When the purpose of the URL is to describe the model. 

 

There are two reasons for following this methodology. First, we want other consumers of WPD to be able to use our documentation, without depending on some kind of lookup or reference intermediary. The most relevant example is the very use case we have in mind for the CSS properties - as content for the Chrome Developer Tools, which will find the relevant CSS property based on the property's URL.

 

Looking forward, toward a tools use case for our APIs, when the user hits the tab key (or whatever), she should get a list that looks like this:

 

IDBTransaction.<hits tab or whatever>

                         db

                         error

                         mode

                         onabort

                         oncomplete

                         onerror

 

Also, hovering over that "onerror" will pop up a summary and a link to the documentation. 

 

In the absence of "onerror" from the model, are we expecting the user to  hit the tab key, select "error" then backarrow over and insert the "on"?  Are we expecting the user to "intuit" that the documentation for "onerror" will be found by hovering over the "error".

 

Second, and likewise, to use the wiki's established content management paradigm: unambiguous organization (apis/indexeddb/IDBTransaction/onerror is what it is) and regardless of how the user finds this information, through search or navigation, she knows that this is the canonical location and description of the "onerror" event handler.

 

As soon as we start pulling fast ones with our structure, folding related properties into single pages, we lose not only the ability to reference those separate properties but we build ambiguity into a model that, defined in the specifications, is designed to be unambiguous. We have to honor the API's design, not presume to take shortcuts with it.

 

Do you really want to charge down the road of building a bunch of complicated templates and forms to make the model more complicated?

 

+Scott

 

 

On Thu, Feb 14, 2013 at 12:07 AM, Doug Schepers <schepers@w3.org> wrote:

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)
         >
         >
         >
         >