W3C home > Mailing lists > Public > public-webplatform@w3.org > November 2012

Re: URL structure sanity check

From: Scott Rowe <scottrowe@google.com>
Date: Fri, 16 Nov 2012 11:38:07 -0800
Message-ID: <CAHZLcPr+ok4TPwRia4kk08iaF+Dsc-WhNVi3OWMEL++x3c+JDQ@mail.gmail.com>
To: Jonathan Garbee <jonathan@garbee.me>
Cc: "public-webplatform@w3.org" <public-webplatform@w3.org>
Oops. My example is not correct. I'll fix that. Instead, see
http://docs.webplatform.org/wiki/apis/file/events/onabort.
+SCott



On Fri, Nov 16, 2012 at 11:30 AM, Scott Rowe <scottrowe@google.com> wrote:

> Hi Mike,
>
> Perhaps I'm not gettin' it, but why would you strip out the "on"? We
> usually document them as event handlers (properties). Here's an old MDN
> doc: https://developer.mozilla.org/en-US/docs/DOM/FileReader, and here's
> my treatment of
> http://docs.webplatform.org/wiki/apis/webrtc/objects/MediaStreamTrack/properties/onmute
> .
>
> +Scott
>
>
>
>
>
> On Fri, Nov 16, 2012 at 4:49 AM, Jonathan Garbee <jonathan@garbee.me>wrote:
>
>>  I'm inclined to agree with Paul here.  Using his example of
>> PerformanceTiming there are about *twenty* subpages.  That seems pretty
>> excessive to me.  I think his idea of using one comprehensive page is good,
>> but making sure headings are setup properly so if people want to point to a
>> specific thing or know where they are going they can easily use a fragment
>> to do it.  I'm also seeing some with only two or three subpages; having
>> those seems almost wasted for so little content when one page could do just
>> fine with the information.
>>
>> I am not sure what was said during the telcon for this though.  If there
>> was a technical reason for wanting to use sub-pages then please let me
>> know.  I think we could get the forms/templates setup pretty well for
>> having one page handle all that is needed though.
>>
>> -Garbee
>>
>>
>> On 11/15/2012 6:33 PM, Paul Irish wrote:
>>
>> I've long proposed shorter URLs and still think they are a better match
>> for our audience than over-specifying and using spec vocabulary.
>>
>>  However,
>>
>>  Given this list, I feel like the larger issue is one of granularity.
>> There simply isn't a good reason all  the PerformanceTiming events (for
>> example) should get their own page. performance.timing deserves ONE page
>> that's comprehensive.
>>
>>  Our imported content defined these conventions, though, as far as I
>> know, no one considered them. In nearly every page in the linked file<https://github.com/mike-sierra/webplatform/blob/master/urls.txt>,
>> I would probably collapse it into its parent.
>>
>>  I don't think we'll find an URL structure that is consistent,
>> technically accurate, using precise terminology, using developer
>> terminology, and simultaneously user-friendly. And that's okay. The
>> important thing is having high-value documentation. Pages that developers
>> read and are hugely impressed so much valuable content is there.
>>
>>
>> On Thu, Nov 15, 2012 at 10:51 PM, Michael Sierra <msierra@adobe.com>wrote:
>>
>>> Turns out there are quite a few collisions in these examples once you
>>> strip out the 'on' prefixes from the event names:
>>>
>>> /apis/file/FileReader/abort
>>> /apis/file/FileReader/error
>>> /apis/push/PushService/error
>>> /apis/webcrypto/CryptoOperation/abort
>>> /apis/webcrypto/CryptoOperation/complete
>>> /apis/webcrypto/CryptoOperation/init
>>> /apis/webrtc/DataChannel/close
>>> /apis/websocket/WebSocket/close
>>>
>>> --Mike Sierra
>>>
>>>
>>>
>>> ________________________________________
>>> From: PhistucK [phistuck@gmail.com]
>>> Sent: Thursday, November 15, 2012 5:33 PM
>>> To: Michael Sierra
>>> Cc: public-webplatform@w3.org
>>> Subject: Re: URL structure sanity check
>>>
>>> In some cases (WebSocket, for example, if I am not mistaken), you cannot
>>> use addEventListener for listening to an event, like ws.onopen. Adding it
>>> as "open" might cause some confusion.
>>> It might be an implementation issue, because I think WebSocket is
>>> specified to subclass EventTarget as well, which means addEventListener
>>> should apply to it, but in Chrome, as far as I remember, it does not work.
>>> I have not tried other browsers.
>>> Anyway, in cases like these (assuming no browser implements
>>> addEventListener for that object), events should begin with the "on"
>>> prefix, I believe (but still have the regular Event template, I guess).
>>>
>>> What does everyone think?
>>>
>>> Also, does anyone have any information regarding other browsers (or
>>> current Chrome?) in this regard?
>>>
>>>
>>> ☆PhistucK
>>>
>>>
>>>
>>>  On Thu, Nov 15, 2012 at 11:18 PM, Michael Sierra <msierra@adobe.com
>>> <mailto:msierra@adobe.com>> wrote:
>>> Re the recent conf-call clarifying the apis/ URL space, here are a few
>>> random APIs generated from some test W3C specs:
>>>
>>> https://github.com/mike-sierra/webplatform/blob/master/urls.txt
>>>
>>> Of all the comments are marked "#",
>>>
>>> * I think of "deviceorientation" as belonging under apis/, but it seems
>>> to simply modify the window object.  Can/should it be represented here?
>>>
>>> * The File API defines a new URL scheme, and I wonder where that gets
>>> doc'ed
>>>
>>> * I noticed one instance of a namespace collision, where an abort()
>>> method collides with an "abort" event.  In this URL list, I kept it as it
>>> appears in the spec, "onabort," but current practice in the wiki is to
>>> strip the "on" prefix, which would cause a problem.
>>>
>>> --Mike Sierra
>>>
>>>
>>>
>>>
>>
>>
>
Received on Friday, 16 November 2012 19:38:35 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 8 May 2013 19:57:35 UTC