- From: Marcos Caceres <marcosscaceres@gmail.com>
- Date: Thu, 7 Aug 2008 17:38:22 +1000
- To: "Krzysztof Maczyński" <1981km@gmail.com>
- Cc: public-webapps@w3.org
Hi Krzysztof, I've made most of the changes you recommended but I was not able to resolve everything. Please see below. I would really appreciate if you could take the time to help me resolve outstanding issues. However, if you are happy with leaving things as they are, please let me know so I can close this thread in the disposition of comments. 2008/7/26 Krzysztof Maczyński <1981km@gmail.com>: > > Dear WG, > > I have written my comments below. > > Please take into account the difference between IRI and IRI reference defined in RFC 3987. I'll look that up. In the mean time, it would be really helpful if you could tell me any place in particular where I've used the terms incorrectly? > Should there be a requirement (probably only may or should for the first version) to specify some way of exposing custom APIs on instances of a widget (like XBL bindings do)? Hmm.... R30 was supposed to cover this (and from my reading, I think it does). Can you recommend some additional text or a change to that requirement that would satisfy what you mean? >> email checkers > s/email/E-mail fixed (but kept E in lowercase, which, according to wikipedia, is ok). >> This document does not address the requirements of "web widgets", such as iGoogle Gadgets or Windows Live Gadgets. > Why not? Aren't they similar enough to be covered by one set of specs and one requirements document (perhaps with a bit of inline tailoring)? No. Web widgets are just <iframe>s or <div>s: They are not packaged or use widget-specific APIs. Hence, they are covered by HTML4 and HTML5. Please see section 3.1 of the Widgets 1.0 Landscape document [1] for a detailed discussion on this issue. We don't address embedding of W3C Widgets using <embed> or <object>. We might leave that for version 2.0. >> A conforming specification is one > Not necessarily, since you plan to have 4. Should it be called conforming set of specifications? Yeah, probably. But it's not so much that all the specs need to address the one requirement (although it is true that some requirements are addressed by the interplay of multiple specs, eg. digital signatures). So even though I agree with you, and technically you are correct, I think it's pretty clear what we mean here. Also, the Widget specs are split into multiple specs for ergonomic reasons, not technical reasons: we figured that having lots of little specs are easier for people to read/review, then one monolithic one. Hopefully you (and others) can live with "conforming specification". >> a widget resource should be easy for authors to create without requiring special software > This is why ZIP (or whatever ends up decided upon) compression should be optional (also see below). Deflate is implemented in all common Zip implementations. However, it might be good for me to document the use of Deflate in the Widgets Landscape document. In the Landscape document, I have documented that all widget user agents support Zip and Deflate, but not that all operating systems support the creation of Zip files that make use of deflate. >Furthermore, I don't envision taking advantage of the Security design goal by a typical author when creating widgets without special software. To be clear, are you saying that an author will need special tools to make use of the the security features? If you are, then it is too early to say that yet. For example, generation of digital signatures *may* require specialized software, but we are working hard so this is not the case. There is open source software that can generate a (XML) digital signatures from a bunch of files and folders. See for instance, http://www.aleksey.com/xmlsec/index.html. >> R1. Packaging Format > There are arguments for enabling compression, and ZIP is discussed on the list. I'm in favour of it as long as it's optional, i.e. there can also be uncompressed widget resources. R10 satisfies this, but uniformity between these two forms should be maximized. Is Store method of ZIP considered? It fails the previous quote. MIME features (Content-Transfer-Encoding comes to mind) then? Agreed. You'll be happy to hear that support for Stored is specified in the Widgets Packaging spec. I've altered R11. Data Compression to read "A conforming specification SHOULD recommend a packaging format that supports both uncompressed data and OPTIONAL data compression." >> R2. File Extension > It seems contrary to AWWW (see also "Cool URIs don't change" by Tim Berners-Lee). In what sense is this contrary to AWWW? locally, widget resources are treated as files not as `representations of resources'. Eventually a widget ends up on a server where it enters the URI space (and where they can follow the URI rules/concepts and AWWW). If giving a file an extension violates AWWW, then every .html, .css, .gif, .png, etc. file also violates AWWW(?). However, I may be misunderstanding what you are trying to say here about R2:) >Also, how Device independence design goal is interpreted to support this? I >see no hardship for supporting MIME types on various devices instead of sniffing >(or mapping, if it's defined for a file system by design) them by file name extensions. I don't see any hardship either, so I don't understand if you want me to change the wording of this requirement. In reality, vendors will probably sniff and they will have to sniff or use the extension any time they get a widget from local storage or over bluetooth or other non-MIME means or where MIME is not supported. >> In addition, the packaging format should allow authors to add and remove resources of a widget resource without needing to recreate the widget resource. > Leverage MIME multipart and Content-Location, please. Motivation: Compatibility with other standards. I disagree. This would be going against the grain of what widget engines currently support: Zip. Also, there is no tool support for MIME in the widget space or included in operating systems. All Widget user agents support Zip and developers are well accustomed to working with Zip. Switching to MIME would require specialized tools to be developed just for widgets. I don't see any advantage MIME has over Zip. >> The addressing scheme must not expose the underlying file system > Please add "(if any)" after that. Added. >> must not be able to address resources outside the widget resource via the addressing scheme > Such ability may be useful (in some future version or even in this one), although I can see the concerns. But it seems harmless, for example, to use URNs (with semantics handled by widget user agent, such as accessing the default instance (forms in older versions of VB have those) or some operating environment motives and artifacts - these are "outside the widget resource", right?). I presume there will be places where IRIs unconstrained by this addressing scheme can be used to allow such usage. Still, I think this must not cannot be enforced syntactically without disallowing relative IRI references (and I can see no reason for disallowing them). Another issue with this is that other instances of the same widget are themselves "resources outside the widget resource" (but not widget resources). Even though R5 currently only provides for addressing resources contained in the widget resource associated withj a given instance of the widget, I believe the goal is (or should be) to enable addressing the instances themselves as well. I would therefore suggest the wording given below for the entire paragraph. Also please clarify that "addressing scheme" means some recipe for minting URIs, not necessarily a URI scheme (which may or may not result from ongoing discussion as the best solution). > -- > A conforming specification must specify an addressing scheme (a new URI scheme or some prescribed use of an existing one) which must or should be used to address at runtime the individual resources within the widget resource in association with the current or another instance of the widget, as well as these instances themselves. This does not preclude allowing use of arbitrary IRI references in some contexts defined by a conforming specification. When the addressing scheme is used, the widget user agent must be required not to expose any other resources to the widget instance. For this purpose a conforming specification may require that accessing resources identified by IRIs using the addressing scheme which leave the allowed space described above must fail. If addressing resources outside the allowed set described above is possible with the addressing scheme, determining that this is the case for a given IRI reference should be easy for the author, at least for absolute IRI references. The addressing scheme should be one that web authors would feel comfortable using or are already accustomed to. > -- I'm moving this to a new thread so that TAG members can also participate here. > Some specific caveats can be mentioned in the rationale extended thus: > -- > To disable access by widget instances to the underlying file system (if any) or other resources which are not instances of the same widget or resources contained in the widget resource used to create the current set of widget instances. > -- Added the text to the rationale. >> how resources need be structured > Insert "to". Added. >> R9. Device Independence > Please rename to "Device independent delivery" or something. "Device andependence" is already a design goal. Changed name to "Device independent delivery". >> where by only widgets that meet a particular level of quality > s/where by/whereby fixed. >> A conforming specification must recommend that a conforming widget resource be sent over HTTP with a formally registered MIME Type. > It must be assigned the right MIME type. HTTP has nothing to do with that. Please also consider that it's the MIME type that tells the user agent it's a widget. Changing the MIME type requires different semantics of processing the resource, even if the representation remains the same (see http://www.w3.org/2001/tag/doc/mime-respect). With text/plain it's not a widget anymore (so out of scope for this spec) but a body of plain text. Correct. I've changed the text to "A conforming specification MUST recommend that a conforming widget resource be sent over HTTP with a formally registered MIME Type that is specific to the Widgets 1.0 Family of specifications. The Working Group MUST formally register the MIME type with the Internet Assigned Numbers Authority (IANA). A conforming specification MUST specify how to process a widget resource that was not served with the appropriate MIME type." >> A conforming specification must specify the structure and semantics of elements > Are those XML elements? Yes. I moved R22 and made it R13. That way, it is now more clear that elements will be in XML. I changed the text so it now reads "semantics of XML elements" >> The metadata must be extractable, processable and reusable in other contexts > Informative reference to GRDDL in the spec would satisfy this. I've added the following text to the rationale: "An example of reuse of metadata could include the ability to combine the widget metadata with GRDDL to produce RDF metadata descriptions about a widget".... (of course, I still think JSON output would be more useful;-)) >> To provide authors with a practical set of metadata elements > I believe that metadata should be extensible, so a generic hook should be included in addition to some required items. The only extensibility mechanism we provide is namespaces... but that does not exactly address the problem you are describing. I have raise this as an issue that will need to be discussed in the WG. I think we will add this if there is more demand from developers for it. The range of metadata elements currently covered by the spec represent the intersection of all commonly appearing metadata elements in other widget user agents (again see the Widget Landscape document). >> R14. Authorship and Widget Metadata > Almost all mentioned items seem optional. Yes. They are all optional. In fact, the configuration document is optional. >> an author's name, email, and organization > s/email/E-mail address (Should it be mailbox (RFC 2822) or mailto IRI?) Fixed typo. Probably IRI, but that's defined in the spec Packaging spec. >> a unique identifier > How to check for uniqueness? What if a widget user agent encounters a widget with a non-unique identifier? I've added the following to R14 Widget Metadata: "A conforming specification MUST specify graceful error handling procedures for all metadata elements for when values are in error, or contradictory to the system, or declared erroneously by an author." >> as well as a model for how this data must be processed by a widget user agent > What's the point of this? The user will in all realistic scenarios be able to edit the widget resource manually to prevent such processing, so if the intent is to enforce some obstacles, it's futile. No, the intent is just to have clearly defined processing rules and predictable behavior. >> R16. Visual Rendering Dimensions > This is privileging visual media. This is making an architectural assumption about widgets that a presentational aspect (intrinsic dimensions) is part of their nature (nothing wrong with this, SVG and MathML do the same, but just calling for awareness), so not deferring it to styling as the only option is acceptable. Please clarify however that if styling is applied, it takes precedence. The same with other means of redefining the dimensions a posteriori. And make them optional (ideally independently in each dimension) to allow widgets without intrinsic width or height. I agree with you that there is no reason that a widget should be intrinsically visual. In an attempt to capture what you are saying, I've rewritten the requirement as follows. Please let me know if I have captured everything correctly or feel free to suggest changes: "For widgets that make use of a rendering context, a conforming specification SHOULD specify an OPTIONAL means for an author to declare the initial visual dimensions for an instantiated widget in a way that is device independent (e.g. via CSS pixels). A conforming specification MUST specify that styling by the author takes precedence over dimensional values declared in the configuration document or any dimensional values implicitly computed by the widget user agent.." >> mechanism that addresses the start file > A remnant of some old very file-centric > draft. Please change to resource. For me personally, "start file" makes sense in this context as it is the file (or, yes, "resource") that is first used when starting the application. If it helps, in the packaging spec, a start file is defined as "...the *resource* that is used when the widget is instantiated." I know we are both being nit-picky here, but changing "file" to "resource" here won't make too much of a difference. >> it may be able to address a resource on the Web over HTTP > Why not other protocols or schemes? To disable access to local resources? I believe this distinction should be defined in a more general way and probably ultimately defer to widget user agent policy. Ok good point. I've removed the word HTTP. It now says "However, the bootstrapping mechanism MAY be able to address a resource on the Internet...". >> or resources that are of media types supported by a widget user agent > If a bootstrap resource is of an unsupported media type, it's useless in this context. On the other hand, any can be supported by a given agent. That's correct. >> so long as they are compatible with the widget user agent > This term will have to be defined in the spec. But I doubt the definition will be very meaningful and not a moot paragraph. By "this term" I suppose you mean "compatible". I've changed it to: "A conforming specification MAY also allow authors to declaratively bootstrap proprietary resources within the widget resource, so long as they are able to be processed or instantiated by the widget user agent." >> may specify an automated model > Combined with the previous requirement this means that a spec just may define something that it must require the agent to do. Not that it couldn't possibly make sense, but if it does for some reason, please state it. >> an automated model for finding the start file > Again a file? Yep:) The things to remember is that addressing inside a package does not follow HTTP semantics (you are not going to get alternatives or redirected, etc.). Inside the Zip file there is just (compressed) bytes identified by a "filename field" (which is a path, eg. i/am/a.file). I want to be careful we don't get into "architecture astronautism". >> For example, the conforming specification could specify a model that searches for a default file name (index.htm, index.html, index.svg, etc) > Please don't rely on extensions. Believe me, we don't want to but I cant see another solution for this. I mean, we can't just go in an parse every XML file in the document to derive it's type based on it's namespace. That would be very inefficient. What do you recommend we do here? >> the widget user agent could try finding files > At this point I can see clearly that entirely avoiding talking about files seems unrealistic. Let's broaden the term then. I suggest replacing "(or similar logical containers)" in R3 with "(understood in this document > in a broader sense than in some popular file systems, namely as forms of generic logical containers)". Ok, I've included the text you recommended verbatim. >> A conforming specification must specify the default values for parameters > I wrote about this above already. I'd like this to be changed so that for some predefined parameters the agent must supply the values (possibly obeying some rules set forth by the spec) if they are missing. And sometimes even overriding provided ones (like visual dimensions) should be allowed. Ok, that seems fair. I've added a sentence at the end R20 in hope of capturing what you are saying: "A conforming specification SHOULD allow a widget user agent to override author defined parameters in circumstances where it might be beneficial for users or has the potential to improve performance or stability of the widget user agent" >> can be used independently of the widget resource that contains it > This jeopardizes addressability when R5 is taken into account. Only an issue if running a widget with an externally associated configuration document is an issue. Or does it implicitly say that the ability to independently use other contained resources is not required? This comment refers to "R23. Configuration Document Independence". In version 1.0, it will not be possible to run a widget with an externally defined configuration document. The intent of this requirement is that developers or third party sites can extract the configuration document and use it however they want (within licensing terms, that is:)). Admittedly, this requirement is kinda dumb because the fact that you can extract resources from the package is a side effect of the packaging format. Anyway, I'm tempted to leave this as is... but modified it so now "A conforming specification _MAY_ provide guidelines for how the configuration document can be used separately from a widget resource" (instead of SHOULD). >> 4.3 Scripting Interfaces > Possible styling issue in the spec. fixed. >> compatibility with other standards > In R25 and R26 this is surprising but very interesting. Can you mention any W3C (or equivalent) standards which you intend to leverage? No. Everything we have looked at is overly complicated. I guess the closest thing in regards to r26 is HTML5's storage mechanism. >> A conforming specification must define a set of states in the lifecycle of the instantiated widget that are able to be captured through script. > I suggest: "A conforming specification must define a set of states and transitions in the lifecycle of the instantiated widget. The transitions must have associated events which can be consumed by event handlers, such as scripts. Additionally the API must expose the current state.". That's much better. I've used your text but with some minor modifications and removed the word transition as it is too ambiguous (could be interpreted as visual transition, which I don't think is what we want here thought it would probably be valid enough). The text for the requirement is now: "A conforming specification MUST define a set of states in the lifecycle of the instantiated widget. Changes in states MUST have associated events which can be consumed by event handlers, such as scripts. Additionally the API MUST expose the current state. A conforming specification MUST NOT require the widget user agent to send events to the widget immediately, and SHOULD allow the widget user agent to dispatch the events at its convenience." Is that ok? >> if the widget resource is connected to the network > s/resource/instance fixed. >> (or any of its windows) > s/windows/presentation contexts (Also add Accessibility to motivation here (and possibly in some other places, such as R37. It's the only unused design goal.) fixed, and added accessibility to r37, r34., r20, r13, r14. I'll probably add it to more before the next publish. >> operating system services > s/system/environment Fixed. >> For example, when a news widget receives a news item about a particular company, it could tell a stock widget stock quotes widget to display any changes in that company's share price. > Now I'm really surprised. The use case is perfectly reasonable, but what about addressability? Isn't it assumed elsewhere that only instances of the same widget can be addressed with the special scheme? Hmmm... I'm concerned that you are surprised. Have I have left some conceptual gaps in the spec? Do I need to explain things a bit more clearly in the introduction? Please let me know what you think I should do. I response to your question, it is not assumed that only instances of the same widget can be addressed with the widget scheme. Having said that, cross-widget communication is a bit gray ATM and I would personally like to see it removed from version 1.0. Having said that, I'm not sure how to proceed here. >> A conforming specification SHOULD specify a means that allows authors to open URLs > How about IRIs? Changed it to IRIs. >> The declared interface may also be accessible to screen readers > At least should, I suggest. Also see the rationale. Ok, changed it to "should". >> persistently store user preferences for each instantiated widget. > Instances are ephemeral by nature. Next run of the same widget resource yields another instantiated widget. Where's the persistence? Shouldn't the word "instantated" be omitted? Ok, I see what you mean. I dropped the word instantiated. Kind regards, Marcos [1] http://www.w3.org/TR/widgets-land/#differences -- Marcos Caceres http://datadriven.com.au
Received on Thursday, 7 August 2008 07:39:05 UTC