[fsp] Add documentation for the File System Provider API.

chrome/common/extensions/docs/templates/intros/fileSystemProvider.html

Index: chrome/common/extensions/docs/templates/intros/fileSystemProvider.html
diff --git a/chrome/common/extensions/docs/templates/intros/fileSystemProvider.html b/chrome/common/extensions/docs/templates/intros/fileSystemProvider.html
new file mode 100644
index 0000000000000000000000000000000000000000..f364280c8596a8bf78cb6a14c81f858c95f30e28
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/intros/fileSystemProvider.html
@@ -0,0 +1,58 @@
+<h2 id="manifest">Manifest</h2>
+<p>You must declare the "fileSystemProvider" permission
+in the <a href="manifest">extension manifest</a>
+to use the File System Provider API.
+For example:</p>
+<pre data-filename="manifest.json">
+{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "fileSystemProvider"
+  ]</b>,
+  ...
+}
+</pre>
+
+<h2 id="overview">Overview</h2>
+<p>
+File System Provider API allows to write extensions providing support for
+virtual file systems, which are available in the file manager on Chrome OS.
+Most obvious use cases are decompressing archives, or accessing files in a cloud

[not at google - send to devlin, 2014/06/24 14:25:42]

"Most obvious use cases" -> "Canonical use cases" or even just "Uses cases
include".

[mtomasz, 2014/06/25 05:38:13]

Done.

+service other than Drive.
+</p>
+
+<h2 id="remote-file-systems">Remote file systems</h2>
+<p>
+In order to serve contents on a remote server, <code>XMLHttpRequest</code> is
+recommended. If impossible, then <code>WebSocket</code> API should be used
+instead.

[not at google - send to devlin, 2014/06/24 14:25:42]

I don't think this paragraph is necessary and might be a bit confusing, for
example some cloud providers provide access via APIs which hide the details of
whether it's XHR or WebSockets.

[mtomasz, 2014/06/25 05:38:13]

Removed. Done.

+</p>
+
+<h2 id="archives">File handlers</h2>
+<p>
+Providing extensions can act as file handlers, using the
+<a href="manifest/file_handlers">file_handlers</a> manifest entry.
+</p>
+<p>
+When the extension is executed with a file to be handled, it has to mount a
+file system and start serving contents from the input file. The most common use
+case is decompressing archives.

[not at google - send to devlin, 2014/06/24 14:25:42]

I don't understand the context of this section on "File handlers". How do they
relate? This is a bit general/vague.

[mtomasz, 2014/06/25 05:38:13]

Basically to write an extension showing contents of archives as virtual file
systems (JS replacement for FUSE), we need the input file (Entry). I clarified
the text a little. WDYT?

[not at google - send to devlin, 2014/06/25 14:03:30]

lgtm

+</p>
+
+<h2 id="archives">Life cycle</h2>
+<p>
+Provided file systems once mounted are remembered by Chrome and remounted
+automatically after reboot or restart. Hence, it can be assumed, that once a
+file system is <a href="method-mount">mounted</a> by a providing extension, it

[not at google - send to devlin, 2014/06/24 14:25:42]

"Hence, it can be assumed, that once a file system is..." -> "Hence, once a file
system is..."

[mtomasz, 2014/06/25 05:38:13]

Done.

+will stay until either the extension is unloaded, or the extension calls the
+<a href="#method-unmount"> unmount</a> method.
+</p>
+<p>
+In case of acting as a file handler, the handled file may need to be stored
+to access it after either a reboot, or suspending and resuming an event page
+of the providing extension. In such case
+<a href="fileSystem#method-retainEntry">chrome.fileSystem.retainEntry</a> and
+<a href="fileSystem#method-restoreEntry">chrome.fileSystem.restoreEntry</a>
+should be used.
+</p>