Re: (no subject)

Hi Robin,

Here is a pre-publication review of Widgets 1.0: Widget URIs 08 
September 2009.

My main beef is that this spec does not clearly tell me how to construct 
a WURI UA... all the bits are there, however, just need a few editorial 
changes, IMHO.

> Widgets 1.0: Widget URIs
> W3C Working Draft 08 September 2009
> >
> Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C
> liability, trademark and document use rules apply.
> Abstract
> 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?

> Such a
> limitation has a number of implications which this document intends to
> address.

Just say what the tech is, IMO. Requirements section covers this better. 
Besides, once the spec is out, then the above is not a problem any more, 
so it's a tautology to have this line of reasoning here.

> Status of This Document
>
> This section describes the status of this document at the time of its
> publication. Other documents may supersede this document. A list of
> current W3C publications and the latest revision of this technical
> report can be found in the W3C technical reports index at
> http://www.w3.org/TR/.
>
> 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.

<snip>

> 1. Introduction
>
> This section is non-normative.
>
> This specification defines the widget URI scheme that is used to address
> resources inside a widget [WIDGETS].

change to "inside a widget package"

> 2. Conformance
>
> As well as sections marked as non-normative, all authoring guidelines,
> diagrams, examples, and notes in this specification are non-normative.
> Everything else in this specification is normative.
>
> The key words must, must not, required, should, should not, recommended,
> may, and optional in this specification are to be interpreted as
> described in [RFC2119].
> 3. Not in this specification
>
> This section is non-normative.
>
> 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

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

> In fact, it is possible that both this scheme and another
> defined to access Zip archive content would be used jointly, with little
> or no overlap in functionality.
>
> 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.

> 4. Requirements

All this should be moved to the widgets requirements doc.

> This section is non-normative.
>
> Must allow addressing resources inside a widget
> The scheme must be able to address Zip relative paths as defined in the
> Widgets: Packaging and Configuration [WIDGETS] specification.

yep

> Must allow resolving relative URL references inside a widget
> It must be possible for a document inside a widget to use a relative
> reference to another without any specific knowledge of the scheme being
> used. For instance, if a document located at dahuts/dextrogyrous.html
> features a link to levrogyrous.html that link must resolve to
> dahuts/levrogyrous.html.

yep

> Must not allow addressing resources outside a widget
> There is no requirement on how widgets are stored and potentially
> unpacked within a given user agent, but irrespective of how that is
> performed, including for instance by storing the unpacked widget on the
> local file system, it must be impossible to address resources outside of
> the widget using this scheme.

yep

> Must provide an origin IRI for widget-contained documents
> Many mechanisms in widgets (e.g. cookies, local storage, XMLHttpRequest)
> key off the IRI or part thereof from which they are used. Since widgets
> are for all intents and purposes local applications that do not have an
> origin, this scheme must provide integration with these mechanisms.

double yep!

> Must be independent of any file system
> Addressing based on this scheme must only map onto Zip relative paths
> and remain independent of any file system on which the widget may be
> stored.
> Must not conflict with existing IRI usage in web runtimes
> This scheme must enable maximal reuse of existing web runtimes, and
> therefore not conflict with the architecture of existing IRI usage.

yep

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

> Must be compatible with the Widgets 1.0: Packaging and Configuration
> localisation model
> Widgets 1.0: Packaging and Configuration [WIDGETS] defines a runtime
> localisation model that allows IRI references to be resolved to
> different resources depending on the user agent's locale settings, this
> IRI scheme must enable such resolution.

Yep

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

> 5. Widget URIs
>
> Widget URIs are primarily IRIs that are synthesised by the user agent as
> it absolutises IRI references found in documents contained in widgets or
> defines base IRIs for them.
>
> Note that using widget URIs directly when authoring content is
> discouraged, and authors should stick to using schemeless relative IRI
> references.
 >
> As a widget is initialised the user agent may generate an identifier

initialised > initialized.

"may" > will (statement of fact)

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

the widget > the widget's

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

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

> If
> present, the authority will be said to be opaque.

"will be said to be" > is

"opaque" needs to be defined.

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


Also, that is not a valid URI.

> Its ABNF syntax [ABNF] is
> therefore:
>
> widget-scheme = "widget"

Please merge the above and the Syntax section below. It's all the same 
thing.

> 5.2 Syntax
>
> The ABNF syntax [ABNF] for widget IRIs is as follows, a widget URI must
> adhere to this syntax:
>
> widget-URI = widget-scheme "://" [ iauthority ] "/" zip-rel-path [ "?"
> iquery ] [ "#" ifragment ]

add: widget-scheme = "widget"


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

> Example widget IRIs could thus be:
> widget://beefdead/dahuts/sightings/alpes-franēaises.svg (assuming the
> generated opaque authority is beefdead) or
> widget:///secret-identities/marcoscąceres/batman.foaf

Nananana! Batman! :D

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

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

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

I don't understand the sentence above.

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

> If the
> <scheme> component obtained after step 5 is widget, then the tuple that
> is returned must be "widget", optionally the opaque authority part, and
> nothing for the <port> component. Furthermore, the ASCII and Unicode
> serialisations for widget origins are as defined in HTML 5 for other
> schemes, except that the port must always be the default one for the
> given protocol.

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

> 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

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.

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

> 1. Let uri be the IRI reference to resolve. If uri is a relative IRI
> reference, make it absolute as defined in [URI].

Mkay.

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


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

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

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

Again, nice work Robin! :)

Kind regards,
Marcos

Received on Thursday, 3 September 2009 12:17:48 UTC