Re: An question aside (Re: A categorization/placing problem - event/property pages)

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