NaCl documentation: update FAQ and examples

native_client_sdk/src/doc/faq.rst

 ##########################
 Frequently Asked Questions
 ##########################
 
 .. contents::
   :local:
   :backlinks: none
   :depth: 2
 
 This document answers some frequently asked questions about Native
@@ skipping 475 matching lines @@
 In most cases you won't have to rewrite much, if any, code. The Native
 Client-specific tools, such as ``pnacl-clang++`` or ``x86_64-nacl-g++``,
 take care of most of the necessary changes. You may need to make some
 changes to your operating system calls and interactions with external
 devices to work with the web. Porting existing Linux libraries is
 generally straightforward, with large libraries often requiring no
 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

[binji, 2015/02/09 18:13:42]

I believe these are just called Chrome Apps now. It seems that this is still
used in many places, though, so I suppose it's OK to leave it for now

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

[binji, 2015/02/09 18:13:42]

This sentence is clumsy. Split it into two sentences?

+  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:
 
 Troubleshooting
 ===============
 
 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. 
 * Your application can verify that Portable Native Client is supported
   in JavaScript with ``navigator.mimeTypes['application/x-pnacl'] !==
   undefined``. This is preferred over checking the Chrome version.
 
 My ``.nexe`` files never finish loading. What gives?
 ----------------------------------------------------
 
@@ skipping 44 matching lines @@
 .. _Rust: http://www.rust-lang.org/
 .. _Go: https://golang.org
 .. _native-client-discuss: https://groups.google.com/group/native-client-discuss
 .. _deprecated in Chrome: http://blog.chromium.org/2013/09/saying-goodbye-to-our-old-friend-npapi.html
 .. _OpenGL ES 2.0: https://www.khronos.org/opengles/
 .. _GLES2 file: https://code.google.com/p/chromium/codesearch#chromium/src/ppapi/lib/gl/gles2/gles2.c
 .. _Google Chrome privacy policy: https://www.google.com/chrome/intl/en/privacy.html
 .. _Google Chrome Terms of Service: https://www.google.com/chrome/intl/en/eula_text.html
 .. _naclports: https://code.google.com/p/naclports
 .. _CORS: http://en.wikipedia.org/wiki/Cross-origin_resource_sharing