NaCl documentation: update FAQ and examples

A few updates to the documentation, a developer pointed out some of the docs weren't quite clear.

TBR= sbc@chromium.org, jmedley@chromium.org
BUG=none
TEST=none

Review URL: https://codereview.chromium.org/886163005

Cr-Commit-Position: refs/heads/master@{#315345}

4 files changed, 67 insertions, 46 deletions

diff --git a/native_client_sdk/doc_generated/faq.html b/native_client_sdk/doc_generated/faq.html
index 2470798..a102882 100644
--- a/native_client_sdk/doc_generated/faq.html
+++ b/native_client_sdk/doc_generated/faq.html
@@ -419,29 +419,37 @@ generally straightforward, with large libraries often requiring no
 source change.</p>
 <p>The following kinds of code may be more challenging to port:</p>
 <ul class="small-gap">
-<li>Code that does direct TCP/IP or UDP networking. For security reasons
-these APIs are only available to packaged applications, not on the
-open web, after asking for the appropriate permissions. Native Client
-is otherwise restricted to the networking APIs available in the
-browser.</li>
-<li>Code that creates processes, including UNIX forks. Creating processes
-is not supported for security reasons. However, threads are supported.</li>
-<li>Code that needs to do local file I/O. Native Client is restricted to
-accessing URLs and to local storage in the browser (the Pepper file I/O API
-has access to the same per-application storage that JavaScript has via Local
-Storage). HTML5 File System can be used, among others. For POSIX compatabiliy
-the Native Client SDK includes a library called nacl_io which allows the
-application to interact with all these types of files via standard POSIX I/O
-functions (e.g. open/fopen/read/write/...). See <a class="reference internal" href="/native-client/devguide/coding/nacl_io.html"><em>Using NaCl I/O</em></a> for more details.</li>
+<li>Code that does direct <a class="reference external" href="pepper_stable/cpp/classpp_1_1_u_d_p_socket">TCP</a> or
+<a class="reference external" href="pepper_stable/cpp/classpp_1_1_u_d_p_socket">UDP</a> networking. For security
+reasons these APIs are only available to <a class="reference external" href="/apps/about_apps">packaged applications</a> after asking for the appropriate permissions, not on the
+open web. Native Client is otherwise restricted to the networking APIs
+available in the browser. You may want to use to <a class="reference external" href="nacl_io">nacl_io library</a>
+to use POSIX-like sockets.</li>
+<li>Code that creates processes, including UNIX <code>fork</code>, won&#8217;t function
+as-is. However, threads are supported. You can nonetheless create new
+<code>&lt;embed&gt;</code> tags in your HTML page to launch new PNaCl processes, even using
+new <code>.pexe</code> files that your existing <code>.pexe</code> saved in a local
+filesystem. This is somewhat akin to <code>execve</code>, but the process management
+has to go through <code>postMessage</code> to JavaScript in order to create the new
+<code>&lt;embed&gt;</code>.</li>
+<li>Code that needs to do local file I/O. Native Client is restricted to accessing
+URLs and to local storage in the browser (the Pepper <a class="reference internal" href="/native-client/devguide/coding/file-io.html"><em>File IO API</em></a> has access to the same per-application storage that
+JavaScript has via Local Storage). HTML5 File System can be used, among
+others. For POSIX compatabiliy the Native Client SDK includes a library called
+nacl_io which allows the application to interact with all these types of files
+via standard POSIX I/O functions (e.g. <code>open</code> / <code>fopen</code> / <code>read</code> /
+<code>write</code> / ...). See <a class="reference internal" href="/native-client/devguide/coding/nacl_io.html"><em>Using NaCl I/O</em></a> for more
+details.</li>
 </ul>
 <h2 id="troubleshooting"><span id="faq-troubleshooting"></span>Troubleshooting</h2>
 <h3 id="my-pexe-isn-t-loading-help">My <code>.pexe</code> isn&#8217;t loading, help!</h3>
 <ul class="small-gap">
 <li>You must use Google Chrome version 31 or greater for Portable Native
-Client. Please <a class="reference external" href="http://www.google.com/chrome/">upgrade now</a> if you are
-not. If you&#8217;re already using a recent version,  open <code>about:components</code> and
-&#8220;Check for update&#8221; for PNaCl. Find your version of chrome by openning
-<code>about:chrome</code>.</li>
+Client. Find your version of chrome by opening <code>about:chrome</code>, and <a class="reference external" href="http://www.google.com/chrome/">update
+Chrome</a> if you are on an older version. If
+you&#8217;re already using a recent version, open <code>about:components</code> and &#8220;Check
+for update&#8221; for PNaCl. Note that on ChromeOS PNaCl is always up to date,
+whereas on other operating systems it updates shortly after Chrome updates.</li>
 <li>A PNaCl <code>.pexe</code> must be compiled with pepper_31 SDK or higher. <a class="reference internal" href="/native-client/sdk/download.html#updating-bundles"><em>Update
 your bundles</em></a> and make sure you&#8217;re using a version of
 Chrome that matches the SDK version.</li>
diff --git a/native_client_sdk/doc_generated/sdk/examples.html b/native_client_sdk/doc_generated/sdk/examples.html
index 6abae9e..ad9d4fa 100644
--- a/native_client_sdk/doc_generated/sdk/examples.html
+++ b/native_client_sdk/doc_generated/sdk/examples.html
@@ -168,18 +168,19 @@ $ export CHROME_PATH=&lt;Path to Google Chrome&gt;
 <p>Each example can also be launched as a packaged application. A packaged
 application is a special zip file (with a .crx extension) hosted in the Chrome
 Web Store. This file contains all of the application parts: A Chrome Web Store
-manifest file (manifest.json), an icon, and all of the regular Native Client
+manifest file (<code>manifest.json</code>), an icon, and all of the regular Native Client
 application files. Refer to <a class="reference external" href="/apps/about_apps">What are Chrome Apps</a> for more
 information about creating a packaged application.</p>
-<p>Some Pepper features, such as TCP/UDP socket access, are only allowed in
-packaged applications. The examples that use these features must be run as
-packaged applications, by using the following command:</p>
+<p>Some Pepper features, such as <a class="reference external" href="pepper_stable/cpp/classpp_1_1_u_d_p_socket">TCP</a> or <a class="reference external" href="pepper_stable/cpp/classpp_1_1_u_d_p_socket">UDP</a> socket access, are only allowed
+in <a class="reference external" href="/apps/about_apps">packaged applications</a>. The examples that use these
+features must be run as <a class="reference external" href="/apps/about_apps">packaged applications</a>, by using
+the following command:</p>
 <pre class="prettyprint">
 $ make run_package
 </pre>
 <p>You can use <code>TOOLCHAIN</code> and <code>CONFIG</code> parameters as described above to run
 with a different toolchain or configuration.</p>
-<h2 id="debugging-the-sdk-examples"><span id="id4"></span>Debugging the SDK examples</h2>
+<h2 id="debugging-the-sdk-examples"><span id="id5"></span>Debugging the SDK examples</h2>
 <p>The NaCl SDK uses <a class="reference external" href="https://www.gnu.org/software/gdb/">GDB</a> to debug Native
 Client code. The SDK includes a prebuilt version of GDB that is compatible with
 NaCl code. To use it, run the <code>make debug</code> command from an example directory:</p>
diff --git a/native_client_sdk/src/doc/faq.rst b/native_client_sdk/src/doc/faq.rst
index df3d0df..f77cf76 100644
--- a/native_client_sdk/src/doc/faq.rst
+++ b/native_client_sdk/src/doc/faq.rst
@@ -493,21 +493,29 @@ source change.
 
 The following kinds of code may be more challenging to port:
 
-* Code that does direct TCP/IP or UDP networking. For security reasons
-  these APIs are only available to packaged applications, not on the
-  open web, after asking for the appropriate permissions. Native Client
-  is otherwise restricted to the networking APIs available in the
-  browser.
-* Code that creates processes, including UNIX forks. Creating processes
-  is not supported for security reasons. However, threads are supported.
-* Code that needs to do local file I/O. Native Client is restricted to
-  accessing URLs and to local storage in the browser (the Pepper file I/O API
-  has access to the same per-application storage that JavaScript has via Local
-  Storage). HTML5 File System can be used, among others. For POSIX compatabiliy
-  the Native Client SDK includes a library called nacl_io which allows the
-  application to interact with all these types of files via standard POSIX I/O
-  functions (e.g. open/fopen/read/write/...). See :doc:`Using NaCl I/O
-  <devguide/coding/nacl_io>` for more details.
+* Code that does direct `TCP <pepper_stable/cpp/classpp_1_1_u_d_p_socket>`_ or
+  `UDP <pepper_stable/cpp/classpp_1_1_u_d_p_socket>`_ networking. For security
+  reasons these APIs are only available to `packaged applications
+  </apps/about_apps>`_ after asking for the appropriate permissions, not on the
+  open web. Native Client is otherwise restricted to the networking APIs
+  available in the browser. You may want to use to `nacl_io library <nacl_io>`_
+  to use POSIX-like sockets.
+* Code that creates processes, including UNIX ``fork``, won't function
+  as-is. However, threads are supported. You can nonetheless create new
+  ``<embed>`` tags in your HTML page to launch new PNaCl processes, even using
+  new ``.pexe`` files that your existing ``.pexe`` saved in a local
+  filesystem. This is somewhat akin to ``execve``, but the process management
+  has to go through ``postMessage`` to JavaScript in order to create the new
+  ``<embed>``.
+* Code that needs to do local file I/O. Native Client is restricted to accessing
+  URLs and to local storage in the browser (the Pepper :doc:`File IO API
+  <devguide/coding/file-io>` has access to the same per-application storage that
+  JavaScript has via Local Storage). HTML5 File System can be used, among
+  others. For POSIX compatabiliy the Native Client SDK includes a library called
+  nacl_io which allows the application to interact with all these types of files
+  via standard POSIX I/O functions (e.g. ``open`` / ``fopen`` / ``read`` /
+  ``write`` / ...). See :doc:`Using NaCl I/O <devguide/coding/nacl_io>` for more
+  details.
 
 .. _faq_troubleshooting:
 
@@ -518,10 +526,11 @@ My ``.pexe`` isn't loading, help!
 ---------------------------------
 
 * You must use Google Chrome version 31 or greater for Portable Native
-  Client. Please `upgrade now <http://www.google.com/chrome/>`_ if you are
-  not. If you're already using a recent version,  open ``about:components`` and
-  "Check for update" for PNaCl. Find your version of chrome by openning 
-  ``about:chrome``.
+  Client. Find your version of chrome by opening ``about:chrome``, and `update
+  Chrome <http://www.google.com/chrome/>`_ if you are on an older version. If
+  you're already using a recent version, open ``about:components`` and "Check
+  for update" for PNaCl. Note that on ChromeOS PNaCl is always up to date,
+  whereas on other operating systems it updates shortly after Chrome updates.
 * A PNaCl ``.pexe`` must be compiled with pepper_31 SDK or higher. :ref:`Update
   your bundles <updating-bundles>` and make sure you're using a version of
   Chrome that matches the SDK version. 
diff --git a/native_client_sdk/src/doc/sdk/examples.rst b/native_client_sdk/src/doc/sdk/examples.rst
index 1b12b12..9a4c5d5 100644
--- a/native_client_sdk/src/doc/sdk/examples.rst
+++ b/native_client_sdk/src/doc/sdk/examples.rst
@@ -208,13 +208,16 @@ Run the SDK examples as packaged apps
 Each example can also be launched as a packaged application. A packaged
 application is a special zip file (with a .crx extension) hosted in the Chrome
 Web Store. This file contains all of the application parts: A Chrome Web Store
-manifest file (manifest.json), an icon, and all of the regular Native Client
+manifest file (``manifest.json``), an icon, and all of the regular Native Client
 application files. Refer to `What are Chrome Apps </apps/about_apps>`_ for more
 information about creating a packaged application.
 
-Some Pepper features, such as TCP/UDP socket access, are only allowed in
-packaged applications. The examples that use these features must be run as
-packaged applications, by using the following command::
+Some Pepper features, such as `TCP
+<pepper_stable/cpp/classpp_1_1_u_d_p_socket>`_ or `UDP
+<pepper_stable/cpp/classpp_1_1_u_d_p_socket>`_ socket access, are only allowed
+in `packaged applications </apps/about_apps>`_. The examples that use these
+features must be run as `packaged applications </apps/about_apps>`_, by using
+the following command::
 
   $ make run_package