Re: [widgets] WURI Review pre-LC review

On Sep 3, 2009, at 14:25 , Marcos Caceres wrote:
>> Many specifications in the Web stack depend on a context being  
>> defined
>> that includes a current IRI. This is easily provided for documents
>> retrieved over HTTP, or from the local file system, but is currently
>> undefined for documents extracted from within a widget package.
>
> I don't like the above. Why are you starting this as an argument?

It's not an argument, but I see how to change it.

>> This document was published by the Web Applications WG as a Last Call
>> Working Draft. This document is intended to become a W3C  
>> Recommendation.
>> If you wish to make comments regarding this document, please send  
>> them
>> to public-webapps@w3.org (subscribe, archives). The Last Call period
>> ends 10 November 2009. All feedback is welcome.
>
> This LC period is too long. Make it 10th of October or mid October.  
> This
> is to facilitate two LCs.

We'll change that when we really do go to LC. As things stand, we  
might be delayed a little more so I can address Jere's comments which  
require some rearchitecting.

>> This specification defines the widget URI scheme that is used to  
>> address
>> resources inside a widget [WIDGETS].
>
> change to "inside a widget package"

That text is gone, but I've changed it elsewhere.

>> There are many different efforts that have specified URI schemes to
>> access the content of Zip archives, or endeavour to do so. While  
>> these
>
> endeavour > endeavor

Perhaps the day you pry my spellchecker from the unflinching grip of  
my cold, dead fingers.

>> efforts have merit, and while W3C Widgets rely on Zip as a packaging
>> format, the use cases that this specification addresses are radically
>> different.
>
> "radically" is unnecessary. You make grand statements, but then don't
> back them. What is so radical about what we are doing? Don't tell me  
> (I
> know how awesome we are!), put in the spec :)

Hmmm, it seems to me that you don't know what "radically" means. It  
means "at its root". We're doing something that is "at its roots"  
different. Something that is "radically different" isn't necessarily  
"radical", in fact there is little connection other than etymological.  
That being said I've changed it to "substantially" to make it more K12  
compliant :)

>> The scheme defined in this specification could be used to implement
>> inter-widget communication, but that is outside the scope of this
>> current document.
>
> This is not proven. I would just say that cross-widget is out of scope
> and, may be future work, but not that it could be used for that.

"Uniquely identifying widgets, or multiple instances of the same  
widget package, as well as using that to enable inter-widget  
communication are outside the scope of this document."

>> 4. Requirements
>
> All this should be moved to the widgets requirements doc.

I don't have a strong opinion but I'm not sure. The widgets  
requirements document holds requirements for the whole family, but it  
stops before the technical implications. I don't think that there's a  
requirement to have a URI scheme when you go and create a widget  
platform, it just so happens that the technical decisions we made lead  
to a place where we need one.

But I'm happy to remove them if you want to past them in the WR — the  
shorter the better!

>> Must not require widget developers to be aware of it for basic tasks
>> Using this scheme as the IRI of resources inside a widget must not  
>> force
>> widget developers to be aware of its existence for simple tasks  
>> such as
>> linking between widget resources, and would ideally not require such
>> knowledge for advanced tasks either.
>
> Yep... but I would qualify this as "the whole scheme" or "must not  
> need
> to know about every component part of the scheme", as you need to at
> least know about the path component.

I see what you mean — technically if you use the path bit then you  
"know about the scheme", but that's not what I meant, really. People  
shouldn't have to learn anything to use it for basic tasks (e.g. just  
do a path). I think most developers don't think that they're using the  
ipath-noscheme followed by ifragment when they link to  
"marcos.xhtml#nose". So I'm unsure how to change this to reflect both  
sides.

>> A careful review of existing schemes has found that none matches the
>> needs above.
>
> "existing schemes" needs references to all the ones we looked at.
>
> "careful review" > "review" and link it to the wiki or my presentation
> on the wiki. You might also link to the landscape doc, though I can't
> remember if I covered that in there or not.

It's not in the landscape and I'd really rather not link to a wiki  
page. Before starting I looked at the list of all IANA-registered  
schemes, plus Wikipedia's list of commonly used non-registered schemes  
(it's not that much work, most can be immediately discarded). I'd  
rather not list them all...

I'm dropping this sentence, if we had found something that worked we'd  
have used it.

>> As a widget is initialised the user agent may generate an identifier
>
> initialised > initialized.

Perhaps the day a pack of transgenic hyenas will have licked clean the  
cold, slushy part of my brain that handles spelling.

> "may" > will (statement of fact)

Actually no, it's a may (in the spec it's even a MAY). There is no  
requirement for it to do so, return widget:///foo/bar is correct.

This will be clearer after I'm finished including a discussion of  
conformant widget producers and consumers.

>> that will be used as the authority part of the widget absolute IRI.
>
> the widget > the widget's

Yup.

> I'm wondering if we should use the word "origin" here.

No, at least not unless you want Thomas banging on your head (I  
don't). One can define the origin to be derived from the authority,  
but it could just as well be defined by the phase of the moon. Here  
we're just talking about URIs, there's no origin.

>> As
>> of this specification that identifier has no semantics and must be
>> ignored while resolving the IRI reference to a representation.
>
> The above is confusing. Ignored by who? When?

Widget consumers. When they're hungry.

>> If
>> present, the authority will be said to be opaque.
>
> "will be said to be" > is
>
> "opaque" needs to be defined.

If present, the authority is said to be <dfn title='opaque  
authority'>opaque</dfn>, which
means that it has a syntax as defined by [[!RFC3987]] but that it is  
devoid of semantics.

>> Future versions of
>> this specification may define more precise syntax and semantics for  
>> this
>> opaque authority.
>> 5.1 The widget URI scheme
>>
>> The URI scheme for widget URIs must be widget.
>
> must be widget > is a string that matches the production of
> <code>widget-URI</code>.
>
> You can't use "must" here, is just is.

It's a must given valid widget URIs as a conformance class.

> Also, that is not a valid URI.

What is not?

>> Its ABNF syntax [ABNF] is
>> therefore:
>>
>> widget-scheme = "widget"
>
> Please merge the above and the Syntax section below. It's all the same
> thing.

Actually that's all going to change thanks to Jere's investigation.


>> Where the zip-rel-path non-terminal is defined in the Widgets 1.0:
>> Packaging and Configuration specification [WIDGETS] and the others
>> reference RFC 3987 [RFC3987].
>
> Change:
>  Widgets 1.0: Packaging and Configuration specification [WIDGETS]
> to just:
>   [WIDGETS] specification.

I'm not sure what you mean, the first one is more readable for non- 
academics I think, and there are more than one widget specifications?

>> 5.3 Base IRI and Relative IRI Reference Resolution
>>
>> The base IRI for a resource contained in a widget must be  
>> constructed by
>> concatenating widget://, optionally the opaque authority, and the Zip
>> relative path to the resource.
>
> Base IRI needs a reference to something or needs to be defined.

Yup.

>> Resolution of relative IRI references is performed using the  
>> mechanism
>> appropriate for the language in the context of which the reference
>> appears, typically following chapter 5 of [URI] or possibly [HTML5].
>
> I would put "(or, for instance, [HTML5])".
>
> We just don't want to risk a normative dependency. Another option is  
> you
> make the last sentence a note.

Or kill the reference, which is less confusing and still just as true.



>
>> 5.4 Usage as Origin
>>
>> Mapping from a widget IRI to an origin is depends on the rules  
>> defined
>> for this purpose by the document type being referenced.
>
> "origin is depends" > "origin depends"

Yup.

> I don't understand the sentence above.

It is just a reminder that what the origin is depends on the language  
of the document which is at that location.

>> Within an HTML 5 context [HTML5], the origin of a resource inside a
>> widget is defined by an extension to the HTML5 origin algorithm.
>
> Oh $#@$! seriously? Should this section be an Appendix or something?  
> Are
> we really going to start screwing with HTML5? This section is  
> currently
> normative.

Well, how else? I'm certainly open to making it into an Appendix, but  
as things stand I'm not sure we can work around this any other way.

Currently step 4 says that "If url does not use a server-based naming  
authority (...) then return a new globally unique identifier." This  
means that two documents inside a given widget will not get the same  
origin. That means that you can't share things like cookies and  
localStorage across documents in a widget — a rather steep limitation.  
We also need to indicate how serialisation happen, otherwise we're not  
getting the interop we came for.

It doesn't imply that we have a normative dependency on HTML5 (I  
think). Here's a suggestion: we kill this section (other specs can  
figure out how to handle origin), devolve the HTML5 content to an  
appendix called "Determining the origin for widget resources that  
follow HTML5's origin-defining rules", and just put this in. Yes it's  
normative, but it's only normative for implementations of HTML5 (or  
that follow its origin rules).

> Again, "must" doesn't make sense to me in this context. Apply it to a
> user agent.

Yup.

>> 5.5 Mapping widget IRIs to Widget Resources
>
> Terminology is wrong in this heading:
>
> Change:
>  Mapping widget IRIs to Widget Resources
>
> To:
> Mapping Widget IRIs to files within a widget package

Yup.

> Also, consistently switching between URI and IRI is giving me
> reader-sickness (a form of metaphorical motion sickness). I think we
> should just use IRI throughout and be done.

It now uses URI throughout, stating that it really means IRI. I don't  
care if it's clumsy, most English speakers I know can't even pronounce  
"IRI" anyway.

>> The process of resolving a widget IRI to a resource within a given
>> widget is must operate as follows (or in a manner that guarantees the
>> same result):
>
> "is must" ? Please convert the above to something that applies to a
> product. Also, this spec lacks a conformance section that lists the
> products.

Yup, incoming.

>> 2. Let path be the path component of uri. Remove the leading U+002F
>> SOLIDUS ("/") from path.
>
> You don't need 2, the rule for finding a file within a widget package
> already does this for you.

Okay, cool.

>> 3. Run the algorithm defined in Rule for finding a file within a  
>> widget
>> package using path as its parameter. What it returns is the file  
>> entry
>> being sought.
>
> It return a "file". A file entry is a different thing (sorry about the
> confusion).

Yup.

> Or may return an error, which needs to be handled.

So the problem here is that we're not in the business of creating a  
protocol. I think we should pass the buck: if it returns an error,  
it's up to the context in which this request is being made to handle  
it. It might display an error or it might fallback, that's not up to us.

>> Note that neither the query nor the fragment parts of the widget  
>> IRI are
>> used in the resolution process. They must nevertheless be kept as  
>> part
>> of the IRI and processed according the rules defined by the content  
>> type
>> being referenced.
>
> Ok, we have a problem here: the P&C's rule for finding a file within a
> widget package can't cope with fragments and queries, so in 3, make is
> super clear that the UA needs to chop off the query and fragment  
> parts.
> That's kinda clear already, but, it does not hurt to be a little bit
> more clear.

Right, I've added that it excludes these.

Thanks man!

-- 
Robin Berjon - http://berjon.com/

Received on Thursday, 17 September 2009 12:50:20 UTC