[NaCl SDK Docs] Only generate one top-level <section> element.

native_client_sdk/doc_generated/devguide/coding/file-io.html

 {{+bindTo:partials.standard_nacl_article}}
 
 <section id="file-i-o">
 <span id="devguide-coding-fileio"></span><h1 id="file-i-o"><span id="devguide-coding-fileio"></span>File I/O</h1>
 <div class="contents local" id="contents" style="display: none">
 <ul class="small-gap">
 <li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
 <li><a class="reference internal" href="#reference-information" id="id3">Reference information</a></li>
 <li><p class="first"><a class="reference internal" href="#local-file-i-o" id="id4">Local file I/O</a></p>
 <ul class="small-gap">
@@ skipping 17 matching lines @@
 <li><a class="reference internal" href="#handling-messages-from-javascript" id="id16">Handling messages from JavaScript</a></li>
 <li><a class="reference internal" href="#saving-a-file" id="id17">Saving a file</a></li>
 <li><a class="reference internal" href="#loading-a-file" id="id18">Loading a file</a></li>
 <li><a class="reference internal" href="#id1" id="id19">Deleting a file</a></li>
 <li><a class="reference internal" href="#listing-files-in-a-directory" id="id20">Listing files in a directory</a></li>
 <li><a class="reference internal" href="#making-a-new-directory" id="id21">Making a new directory</a></li>
 </ul>
 </li>
 </ul>
 
-</div><section id="introduction">
-<h2 id="introduction">Introduction</h2>
+</div><h2 id="introduction">Introduction</h2>
 <p>This chapter describes how to use the <a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_file_i_o">FileIO API</a> to read and write
 files using a local secure data store.</p>
 <p>You might use the File IO API with the URL Loading APIs to create an overall
 data download and caching solution for your NaCl applications. For example:</p>
 <ol class="arabic simple">
 <li>Use the File IO APIs to check the local disk to see if a file exists that
 your program needs.</li>
 <li>If the file exists locally, load it into memory using the File IO API. If
 the file doesn&#8217;t exist locally, use the URL Loading API to retrieve the
 file from the server.</li>
 <li>Use the File IO API to write the file to disk.</li>
 <li>Load the file into memory using the File IO API when needed by your
 application.</li>
 </ol>
 <p>The example discussed in this chapter is included in the SDK in the directory
 <code>examples/api/file_io</code>.</p>
-</section><section id="reference-information">
 <h2 id="reference-information">Reference information</h2>
 <p>For reference information related to FileIO, see the following documentation:</p>
 <ul class="small-gap">
 <li><a class="reference external" href="/native-client/pepper_stable/cpp/file__io_8h">file_io.h</a> - API to create a
 FileIO object</li>
 <li><a class="reference external" href="/native-client/pepper_stable/cpp/file__ref_8h">file_ref.h</a> - API to create
 a file reference or &#8220;weak pointer&#8221; to a file in a file system</li>
 <li><a class="reference external" href="/native-client/pepper_stable/cpp/file__system_8h">file_system.h</a> - API to
 create a file system associated with a file</li>
 </ul>
-</section><section id="local-file-i-o">
 <h2 id="local-file-i-o">Local file I/O</h2>
 <p>Chrome provides an obfuscated, restricted area on disk to which a web app can
 safely <a class="reference external" href="https://developers.google.com/chrome/whitepapers/storage#persistent">read and write files</a>. The
 Pepper FileIO, FileRef, and FileSystem APIs (collectively called the File IO
 APIs) allow you to access this sandboxed local disk so you can read and write
 files and manage caching yourself. The data is persistent between launches of
 Chrome, and is not removed unless your application deletes it or the user
 manually deletes it. There is no limit to the amount of local data you can
 use, other than the actual space available on the local drive.</p>
-<section id="enabling-local-file-i-o">
-<span id="enabling-file-access"></span><span id="quota-management"></span><h3 id="enabling-local-file-i-o"><span id="enabling-file-access"></span><span id="quota-management"></span>Enabling local file I/O</h3>
+<h3 id="enabling-local-file-i-o"><span id="enabling-file-access"></span><span id="quota-management"></span>Enabling local file I/O</h3>
 <p>The easiest way to enable the writing of persistent local data is to include
 the <a class="reference external" href="/extensions/declare_permissions#unlimitedStorage">unlimitedStorage permission</a> in your Chrome Web Store
 manifest file. With this permission you can use the Pepper FileIO API without
 the need to request disk space at run time. When the user installs the app
 Chrome displays a message announcing that the app writes to the local disk.</p>
 <p>If you do not use the <code>unlimitedStorage</code> permission you must include
 JavaScript code that calls the <a class="reference external" href="http://updates.html5rocks.com/2011/11/Quota-Management-API-Fast-Facts">HTML5 Quota Management API</a> to
 explicitly request local disk space before using the FileIO API. In this case
 Chrome will prompt the user to accept a requestQuota call every time one is
 made.</p>
-</section><section id="testing-local-file-i-o">
 <h3 id="testing-local-file-i-o">Testing local file I/O</h3>
 <p>You should be aware that using the <code>unlimitedStorage</code> manifest permission
 constrains the way you can test your app. Three of the four techniques
 described in <a class="reference internal" href="/native-client/devguide/devcycle/running.html"><em>Running Native Client Applications</em></a>
 read the Chrome Web Store manifest file and enable the <code>unlimitedStorage</code>
 permission when it appears, but the first technique (local server) does not.
 If you want to test the file IO portion of your app with a simple local server,
 you need to include JavaScript code that calls the HTML5 Quota Management API.
 When you deliver your application you can replace this code with the
 <code>unlimitedStorage</code> manifest permission.</p>
-</section></section><section id="the-file-io-example">
 <h2 id="the-file-io-example">The <code>file_io</code> example</h2>
 <p>The Native Client SDK includes an example, <code>file_io</code>, that demonstrates how
 to read and write a local disk file. Since you will probably run the example
 from a local server without a Chrome Web Store manifest file, the example&#8217;s
 index file uses JavaScript to perform the Quota Management setup as described
 above. The example has these primary files:</p>
 <ul class="small-gap">
 <li><code>index.html</code> - The HTML code that launches the Native Client module and
 displays the user interface.</li>
 <li><code>example.js</code> - JavaScript code that requests quota (as described above). It
 also listens for user interaction with the user interface, and forwards the
 requests to the Native Client module.</li>
 <li><code>file_io.cc</code> - The code that sets up and provides an entry point to the
 Native Client module.</li>
 </ul>
 <p>The remainder of this section covers the code in the <code>file_io.cc</code> file for
 reading and writing files.</p>
-<section id="file-i-o-overview">
 <h3 id="file-i-o-overview">File I/O overview</h3>
 <p>Like many Pepper APIs, the File IO API includes a set of methods that execute
 asynchronously and that invoke callback functions in your Native Client module.
 Unlike most other examples, the <code>file_io</code> example also demonstrates how to
 make Pepper calls synchronously on a worker thread.</p>
 <p>It is illegal to make blocking calls to Pepper on the module&#8217;s main thread.
 This restriction is lifted when running on a worker thread&#8212;this is called
 &#8220;calling Pepper off the main thread&#8221;. This often simplifies the logic of your
 code; multiple asynchronous Pepper functions can be called from one function on
 your worker thread, so you can use the stack and standard control flow
 structures normally.</p>
 <p>The high-level flow for the <code>file_io</code> example is described below.  Note that
 methods in the namespace <code>pp</code> are part of the Pepper C++ API.</p>
-</section><section id="creating-and-writing-a-file">
 <h3 id="creating-and-writing-a-file">Creating and writing a file</h3>
 <p>Following are the high-level steps involved in creating and writing to a
 file:</p>
 <ol class="arabic simple">
 <li><code>pp::FileIO::Open</code> is called with the <code>PP_FILEOPEN_FLAG_CREATE</code> flag to
 create a file.  Because the callback function is <code>pp::BlockUntilComplete</code>,
 this thread is blocked until <code>Open</code> succeeds or fails.</li>
 <li><code>pp::FileIO::Write</code> is called to write the contents. Again, the thread is
 blocked until the call to <code>Write</code> completes. If there is more data to
 write, <code>Write</code> is called again.</li>
 <li>When there is no more data to write, call <code>pp::FileIO::Flush</code>.</li>
 </ol>
-</section><section id="opening-and-reading-a-file">
 <h3 id="opening-and-reading-a-file">Opening and reading a file</h3>
 <p>Following are the high-level steps involved in opening and reading a file:</p>
 <ol class="arabic simple">
 <li><code>pp::FileIO::Open</code> is called to open the file. Because the callback
 function is <code>pp::BlockUntilComplete</code>, this thread is blocked until Open
 succeeds or fails.</li>
 <li><code>pp::FileIO::Query</code> is called to query information about the file, such as
 its file size. The thread is blocked until <code>Query</code> completes.</li>
 <li><code>pp::FileIO::Read</code> is called to read the contents. The thread is blocked
 until <code>Read</code> completes. If there is more data to read, <code>Read</code> is called
 again.</li>
 </ol>
-</section><section id="deleting-a-file">
 <h3 id="deleting-a-file">Deleting a file</h3>
 <p>Deleting a file is straightforward: call <code>pp::FileRef::Delete</code>. The thread is
 blocked until <code>Delete</code> completes.</p>
-</section><section id="making-a-directory">
 <h3 id="making-a-directory">Making a directory</h3>
 <p>Making a directory is also straightforward: call <code>pp::File::MakeDirectory</code>.
 The thread is blocked until <code>MakeDirectory</code> completes.</p>
-</section><section id="listing-the-contents-of-a-directory">
 <h3 id="listing-the-contents-of-a-directory">Listing the contents of a directory</h3>
 <p>Following are the high-level steps involved in listing a directory:</p>
 <ol class="arabic simple">
 <li><code>pp::FileRef::ReadDirectoryEntries</code> is called, and given a directory entry
 to list. A callback is given as well; many of the other functions use
 <code>pp::BlockUntilComplete</code>, but <code>ReadDirectoryEntries</code> returns results in
 its callback, so it must be specified.</li>
 <li>When the call to <code>ReadDirectoryEntries</code> completes, it calls
 <code>ListCallback</code> which packages up the results into a string message, and
 sends it to JavaScript.</li>
 </ol>
-</section></section><section id="file-io-deep-dive">
 <h2 id="file-io-deep-dive"><code>file_io</code> deep dive</h2>
 <p>The <code>file_io</code> example displays a user interface with a couple of fields and
 several buttons. Following is a screenshot of the <code>file_io</code> example:</p>
 <img alt="/native-client/images/fileioexample.png" src="/native-client/images/fileioexample.png" />
 <p>Each radio button is a file operation you can perform, with some reasonable
 default values for filenames. Try typing a message in the large input box and
 clicking <code>Save</code>, then switching to the <code>Load File</code> operation, and
 clicking <code>Load</code>.</p>
 <p>Let&#8217;s take a look at what is going on under the hood.</p>
-<section id="opening-a-file-system-and-preparing-for-file-i-o">
 <h3 id="opening-a-file-system-and-preparing-for-file-i-o">Opening a file system and preparing for file I/O</h3>
 <p><code>pp::Instance::Init</code> is called when an instance of a module is created. In
 this example, <code>Init</code> starts a new thread (via the <code>pp::SimpleThread</code>
 class), and tells it to open the filesystem:</p>
 <pre class="prettyprint">
 virtual bool Init(uint32_t /*argc*/,
                   const char * /*argn*/ [],
                   const char * /*argv*/ []) {
   file_thread_.Start();
   // Open the file system on the file_thread_. Since this is the first
@@ skipping 20 matching lines @@
   int32_t rv = file_system_.Open(1024 * 1024, pp::BlockUntilComplete());
   if (rv == PP_OK) {
     file_system_ready_ = true;
     // Notify the user interface that we're ready
     PostMessage(&quot;READY|&quot;);
   } else {
     ShowErrorMessage(&quot;Failed to open file system&quot;, rv);
   }
 }
 </pre>
-</section><section id="handling-messages-from-javascript">
 <h3 id="handling-messages-from-javascript">Handling messages from JavaScript</h3>
 <p>When you click the <code>Save</code> button, JavaScript posts a message to the NaCl
 module with the file operation to perform sent as a string (See <a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Messaging
 System</em></a> for more details on message passing). The string is
 parsed by <code>HandleMessage</code>, and new work is added to the file thread:</p>
 <pre class="prettyprint">
 virtual void HandleMessage(const pp::Var&amp; var_message) {
   if (!var_message.is_string())
     return;
 
@@ skipping 13 matching lines @@
 
   // Dispatch the instruction
   if (instruction == kLoadPrefix) {
     file_thread_.message_loop().PostWork(
         callback_factory_.NewCallback(&amp;FileIoInstance::Load, file_name));
   } else if (instruction == kSavePrefix) {
     ...
   }
 }
 </pre>
-</section><section id="saving-a-file">
 <h3 id="saving-a-file">Saving a file</h3>
 <p><code>FileIoInstance::Save</code> is called when the <code>Save</code> button is pressed. First,
 it checks to see that the FileSystem has been successfully opened:</p>
 <pre class="prettyprint">
 if (!file_system_ready_) {
   ShowErrorMessage(&quot;File system is not open&quot;, PP_ERROR_FAILED);
   return;
 }
 </pre>
 <p>It then creates a <code>pp::FileRef</code> resource with the name of the file. A
@@ skipping 43 matching lines @@
 } while (bytes_written &lt; static_cast&lt;int64_t&gt;(file_contents.length()));
 </pre>
 <p>Finally, the file is flushed to push all changes to disk:</p>
 <pre class="prettyprint">
 int32_t flush_result = file.Flush(pp::BlockUntilComplete());
 if (flush_result != PP_OK) {
   ShowErrorMessage(&quot;File fail to flush&quot;, flush_result);
   return;
 }
 </pre>
-</section><section id="loading-a-file">
 <h3 id="loading-a-file">Loading a file</h3>
 <p><code>FileIoInstance::Load</code> is called when the <code>Load</code> button is pressed. Like
 the <code>Save</code> function, <code>Load</code> first checks to see if the FileSystem has been
 successfully opened, and creates a new <code>FileRef</code>:</p>
 <pre class="prettyprint">
 if (!file_system_ready_) {
   ShowErrorMessage(&quot;File system is not open&quot;, PP_ERROR_FAILED);
   return;
 }
 pp::FileRef ref(file_system_, file_name.c_str());
@@ skipping 49 matching lines @@
 }
 </pre>
 <p>Finally, the contents of the file are sent back to JavaScript, to be displayed
 on the page. This example uses &#8220;<code>DISP|</code>&#8221; as a prefix command for display
 information:</p>
 <pre class="prettyprint">
 std::string string_data(data.begin(), data.end());
 PostMessage(&quot;DISP|&quot; + string_data);
 ShowStatusMessage(&quot;Load success&quot;);
 </pre>
-</section><section id="id1">
 <h3 id="id1">Deleting a file</h3>
 <p><code>FileIoInstance::Delete</code> is called when the <code>Delete</code> button is pressed.
 First, it checks whether the FileSystem has been opened, and creates a new
 <code>FileRef</code>:</p>
 <pre class="prettyprint">
 if (!file_system_ready_) {
   ShowErrorMessage(&quot;File system is not open&quot;, PP_ERROR_FAILED);
   return;
 }
 pp::FileRef ref(file_system_, file_name.c_str());
 </pre>
 <p>Unlike <code>Save</code> and <code>Load</code>, <code>Delete</code> is called on the <code>FileRef</code> resource,
 not a <code>FileIO</code> resource. Note that the result is checked for
 <code>PP_ERROR_FILENOTFOUND</code> to give a better error message when trying to delete
 a non-existent file:</p>
 <pre class="prettyprint">
 int32_t result = ref.Delete(pp::BlockUntilComplete());
 if (result == PP_ERROR_FILENOTFOUND) {
   ShowStatusMessage(&quot;File/Directory not found&quot;);
   return;
 } else if (result != PP_OK) {
   ShowErrorMessage(&quot;Deletion failed&quot;, result);
   return;
 }
 </pre>
-</section><section id="listing-files-in-a-directory">
 <h3 id="listing-files-in-a-directory">Listing files in a directory</h3>
 <p><code>FileIoInstance::List</code> is called when the <code>List Directory</code> button is
 pressed. Like all other operations, it checks whether the FileSystem has been
 opened and creates a new <code>FileRef</code>:</p>
 <pre class="prettyprint">
 if (!file_system_ready_) {
   ShowErrorMessage(&quot;File system is not open&quot;, PP_ERROR_FAILED);
   return;
 }
 
@@ skipping 29 matching lines @@
   for (size_t i = 0; i &lt; entries.size(); ++i) {
     pp::Var name = entries[i].file_ref().GetName();
     if (name.is_string()) {
       ss &lt;&lt; &quot;|&quot; &lt;&lt; name.AsString();
     }
   }
   PostMessage(ss.str());
   ShowStatusMessage(&quot;List success&quot;);
 }
 </pre>
-</section><section id="making-a-new-directory">
 <h3 id="making-a-new-directory">Making a new directory</h3>
 <p><code>FileIoInstance::MakeDir</code> is called when the <code>Make Directory</code> button is
 pressed. Like all other operations, it checks whether the FileSystem has been
 opened and creates a new <code>FileRef</code>:</p>
 <pre class="prettyprint">
 if (!file_system_ready_) {
   ShowErrorMessage(&quot;File system is not open&quot;, PP_ERROR_FAILED);
   return;
 }
 pp::FileRef ref(file_system_, dir_name.c_str());
 </pre>
 <p>Then the <code>pp::FileRef::MakeDirectory</code> function is called.</p>
 <pre class="prettyprint">
 int32_t result = ref.MakeDirectory(
     PP_MAKEDIRECTORYFLAG_NONE, pp::BlockUntilComplete());
 if (result != PP_OK) {
   ShowErrorMessage(&quot;Make directory failed&quot;, result);
   return;
 }
 ShowStatusMessage(&quot;Make directory success&quot;);
 </pre>
-</section></section></section>
+</section>
 
 {{/partials.standard_nacl_article}}