Re: [widgets] WURI Review pre-LC review

(additional typo found, at bottom of email)

On Thu, Sep 3, 2009 at 2:25 PM, Marcos Caceres<marcosc@opera.com> wrote:
> (Apologies for sending this twice, screwed up the subject on the last one...
> email is hard!:) )
>
> 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
>
>

Also,
"widget:///secret-identities/marcosc/batman.foaf" note the "///"

Kind regards,
Marcos

-- 
Marcos Caceres
http://datadriven.com.au

Received on Thursday, 3 September 2009 14:19:30 UTC