Re: comments from Osmosoft on the File API

Greetings Paul :)


> At Osmosoft, we took some time to collectively read the File API 
> Editor's Working Draft 28 October 2009:
>   

Thank you very much for taking the time, and sending your review 
comments.  My responses below:

> Overall we welcome the formalization of access to local files,
> including binary data within a client-side Web application and
> can envisage migrating a number of features currently implemented
> using access to a file:// URI TiddlyWiki if and when it becomes
> available in browser implementations.
>
>   

This is good to know.  Do you specifically mean the urn (or url) feature 
that the specification has solicited feedback about, or anything else?

> During our review we have one overall disappointment: whilst the 
> Use Cases describe saving local files programatically, the 
> specification does not provide any write methods. 
>
> We wondered if these were to be  provided in a later version 
> or via extensions? --We now gather this is a topic of debate within 
> the WG and with the DAP WG.
>
>   

Write methods are forthcoming in a subsequent version of the File API.  
My understanding currently is that ongoing work on file writing will 
follow in the Web Apps WG, and iterate on the current File API.

> We do have some very minor comments which we hope 
> will help move the specification forward.
>
> * Status of this Document
> The Status section states this is the work of the Web Applications 
> Working Group, but we were unable to find mention of the spec from 
> the Working Group page, or in the list of chartered deliverables:
>
>     http://www.w3.org/2008/webapps/ 
>     http://www.w3.org/2008/webapps/charter/webapps-deliverables.html 
>
> What is the current expectation of the status of the published 
> document? Is it on the Recommendation track, or will it be 
> published as a Working Group Note?
>   

It is *very soon* to be published as a FPWD.

> What is the relationship between the File API document and 
> the File Upload API listed on the historical Web API WG page?
>
>     http://www.w3.org/2006/webapi/
>     http://www.w3.org/TR/file-upload/
>   

The API you have just reviewed deprecates the File Upload API that you 
cite above.
> * Acknowledgements
> Where is the original document from Robin Berjon? A link to the 
> input document may help us better understand the context of this
> specification.
>   

In fact, you have already referenced it, namely:

http://www.w3.org/TR/file-upload/

I don't think much is gained by linking to this document directly, since 
it contains some non-starters, and is likely to confuse developers, 
since the two drafts differ significantly.  A brief history of the File 
specification is:

1. The initial API proposal had synchronous read methods, which actually 
had been implemented in Firefox (but which we'll deprecate somehow over 
the course of time, since Firefox 3.6 introduces support for the File 
API in my draft).  But synchronous reads from the main thread weren't a 
palatable direction for the web, and Apple in particular raised strong 
objections.

2. An asynchronous draft followed.  But this didn't account for progress 
events.

3. The current draft introduced asynchronous file access as well as 
progress events.
> * Processing Models
> Much of the specification seems to be written in terms of 
> pseudo-code steps. Whilst this follows the style of parts
> of the HTML 5 specification, and simplifies cloning a working 
> implementation, it can make it harder to read and more difficult
> to write tests for than a series of assertions. I'd suggest
> wherever possible, replacing the processing steps with a set of
> inputs, observable changes of state and outputs, even if this
> does make the specification more verbose.
>   

Can you give me an example?  Do you think introducing more sample code 
will address this concern?  In particular, are there areas of prose that 
you think are unclear?
> * Conformance
> The terminology used for conformance currently links within the document, 
> rather than to HTML 5 specification.
>   

I don't know what you mean here.  Do you mean the practice of putting 
internal links in square bracket e.g. [HTML5]?  This seems to be common 
practice, so that all references are cited clearly in the references 
section.
> We'd also suggest adopting the HTML 5 colours for terminology, 
> internal and external references.
>
> A a frag-id for each individual assertion, along with a table listing 
> all of the assertions at the end of the document useful when building 
> test suites.
>   

Do you feel that terminology, and references, are *hard to read* or this 
an argument for consistency?  I've labored to make the specification 
referenced and hyper-linked, and am reluctant to have a template change 
without a clearly stated payoff.  Can you point me to any specifications 
that have frag-ids for individual assertions that help building test suites?
> * Normative references
> Along with the authors, it would be useful to have an indication of the
> current status of each of the documents referenced. Many seem to be
> still at working draft.
>   

Since I'm due to update that section, I can put in a "status token" if 
that helps.

-- A*

Received on Tuesday, 17 November 2009 20:52:10 UTC