- From: PhistucK <phistuck@gmail.com>
- Date: Thu, 14 Feb 2013 21:50:04 +0200
- To: Julee <julee@adobe.com>
- Cc: Scott Rowe <scottrowe@google.com>, Doug Schepers <schepers@w3.org>, Lance Leonard <Lance.Leonard@microsoft.com>, Chris Mills <cmills@opera.com>, "public-webplatform@w3.org" <public-webplatform@w3.org>
- Message-ID: <CABc02_KT6p_3zGirY7dwdidwhE5+Vi6Zxn5wDY-Qh=owJzbo4w@mail.gmail.com>
I think the distinction in this case is relevant.
API properties, methods and (sometimes) events can be accessed the same way
(only adding a () for methods, but that is a programming language
distinction, really).
CSS properties differ a lot from selectors and from values or functions.
These are totally different contexts.
While inconsistent, I think the semantic value of it is essential.
☆*PhistucK*
On Thu, Feb 14, 2013 at 9:24 PM, Julee <julee@adobe.com> wrote:
> Hi, Scott:
>
> This is all making sense to me, but do we intend to use the node
> "properties" in the CSS URLs and not in the APIs?
>
> So:
>
> apis/indexeddb/IDBTransaction/onerror
>
> But:
>
> css/properties/box-shadow
>
> ?
>
> Thanks.
>
> Julee
>
> ----------------------------
> julee@adobe.com
> @adobejulee
>
> From: Scott Rowe <scottrowe@google.com>
> Date: Thursday, February 14, 2013 10:01 AM
> To: Doug Schepers <schepers@w3.org>
> Cc: PhistucK <phistuck@gmail.com>, Lance Leonard <
> Lance.Leonard@microsoft.com>, Chris Mills <cmills@opera.com>, julee <
> julee@adobe.com>, "public-webplatform@w3.org" <public-webplatform@w3.org>
> Subject: Re: A categorization/placing problem - event/property pages
>
> 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<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<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 <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>>"
>>> <public-webplatform@w3.org
>>> <mailto:public-webplatform@w3.**org <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<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<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 <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<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 19:51:17 UTC