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*
