Re: comments from Osmosoft on the File API

Hi Paul!

On Nov 11, 2009, at 12:30 , <paul.downey@bt.com> <paul.downey@bt.com> wrote:
> 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.

The reason for this split is largely due to the different security requirements. During the f2f we discussed producing layered specifications that would have read, then write, then navigating the file system as compatible APIs that would at the very least share a similar style and some basic objects. There were some doubts that such a thing would really work out, but we're looking into options and I have good hope.

> 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 on Rec track, it is intended to become a web standard supported across all browsers (and other web runtimes).

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

As Art said, the File (Reader) API is just the new File Upload API. The name changed to reflect the evolution of its core concern.

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

Even I would be pained to dig it up, and if I did it would be unlikely to be very useful. My name is only there because Arun is a urbane and gentlepersonly fellow — I believe that the current content is entirely his.

If you feel that you need some context outside of the current document in order to understand it then we're missing something there — reading antiquated material really should never ever be a requirement in order to make sense of a specification. If you could pinpoint the context that you may feel to be missing, we would certainly be indebted.

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

This pseudo-code approach definitely has readability limits, but it does have the big advantage of making the job of implementing the specification (and, through that, of spotting specification bugs) far easier, as I can attest having recently implemented a specification written similarly. So while I do think that we should keep looking for ways in which to improve this writing style, I would rather wish it to stay.

I believe that the issue is largely one of audience. In order to produce interoperability, specifications need to be primarily tailored to implementers. I guess that you are approaching the document more from an author's point of view. I do believe that authors should also be catered to (either within the same document, or with a separate authoring primer), but the corresponding text can only be written once we have some confidence that we've nailed down the grittier details of the implementer-orientated stuff; lest we have to make changes twice while the API is still in flux.

> * Conformance
> The terminology used for conformance currently links within the document, 
> rather than to HTML 5 specification.

I'm not sure what you mean here?

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

That's probably something that will happen (as it has in the widgets specifications) but I would expect that to come a little bit later.

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

Received on Wednesday, 18 November 2009 08:53:01 UTC