Copy edit Learn Basics section.

native_client_sdk/src/doc/nacl-and-pnacl.rst

 .. _nacl-and-pnacl:
 
 ##############
 NaCl and PNaCl
 ##############
 
 This document describes the differences between **Native Client** and
 **Portable Native Client**, and provides recommendations for when to use each.
 
 .. contents::
   :local:
   :backlinks: none
   :depth: 2
 
+.. _native-client-nacl:
+
 Native Client (NaCl)
 ====================
 
 Native Client enables the execution of native code securely inside web
 applications through the use of advanced `Software Fault Isolation (SFI)
-techniques <http://research.google.com/pubs/pub35649.html>`_.  Since its launch in
-2011, Native Client has provided developers with the ability to harness a
-client machine's computational power to a much fuller extent than traditional
-web technologies, by running compiled C and C++ code at near-native speeds and
-taking advantage of multiple cores with shared memory.
+techniques <http://research.google.com/pubs/pub35649.html>`_. Native Client
+allows you to harness a client machine's computational power to a fuller extent
+than traditional web technologies by running compiled C and C++ code at
+near-native speeds and taking advantage of multiple cores with shared memory.
 
-While Native Client provides operating system independence, it requires
-developers to generate architecture-specific executable 
-(**nexe**) modules for each hardware platform. This is not only inconvenient
-for developers, but architecture-specific machine code is not portable and thus
-not well-suited for the open web. The traditional method of application
-distribution on the web is through a self-contained bundle of HTML, CSS,
-JavaScript, and other resources (images, etc.) that can be hosted on a server
-and run inside a web browser.  With this type of distribution, a website
-created today should still work years later, on all platforms.
-Architecture-specific executables are clearly not a good fit for distribution
-on the web. As a consequence, Native Client has been restricted to
-applications and browser extensions that are installed through the
+While Native Client provides operating system independence, it requires you to
+generate architecture-specific executables (**nexe**) for each hardware
+platform. This is neither portable nor conveient, making it ill-suited for the

[JF, 2014/09/19 18:16:17]

s/conveient/convenient/

[jpmedley, 2014/09/19 20:40:33]

Done.

+open web.
+
+The traditional method of application distribution on the web is through self-
+contained bundles of HTML, CSS, JavaScript, and other resources (images, etc.)
+that can be hosted on a server and run inside a web browser. With this type of
+distribution, a website created today should still work years later, on all
+platforms. Architecture-specific executables are clearly not a good fit for
+distribution on the web. Consequently, Native Client has been until recently
+restricted to applications and browser extensions that are installed through the
 Chrome Web Store.
 
+.. _portable-native-client-pnacl:
+
 Portable Native Client (PNaCl)
 ==============================
 
 PNaCl solves the portability problem by splitting the compilation process
 into two parts:
 
-#. compiling the source code to a portable bitcode format, and
-#. translating the bitcode to a host-specific executable just before execution.
+#. compiling the source code to a bitcode executable (pexe), and

[JF, 2014/09/19 18:16:17]

We usually use **nexe** and **pexe**, though I think we haven't been convenient?

[jpmedley, 2014/09/19 20:40:33]

To what end? I don't think it's really needed and it makes pages a little
noisier than they need to be.

[JF, 2014/09/22 16:53:05]

It just makes them bold. I'm not necessarily advocating either way, just for
consistency (the section above has **nexe** and this one doesn't have **pexe**).

+#. translating the bitcode to a host-specific executable as soon as the module
+   loads in the browser but before any code execution.
 
-PNaCl enables developers to distribute **portable executables** (**pexe**)
-modules that the hosting environment (in other words, the Chrome browser) can 
-translate to native code before executing. This portability aligns Native Client
-with existing open web technologies such as JavaScript. A developer can 
-distribute a **pexe** as part of an application (along with HTML, CSS, and
-JavaScript), and the user's machine is simply able to run it.
+This portability aligns Native Client with existing open web technologies such
+as JavaScript. You can distribute a pexe as part of an application (along with
+HTML, CSS, and JavaScript), and the user's machine is simply able to run it.
 
-With PNaCl, a developer generates a single **pexe** from source code,
-rather than multiple platform-specific nexes. The **pexe** provides both
-architecture- and OS-independence. Since the **pexe** uses an abstract,
-architecture-independent format, it does not suffer from the portability
-problem described above. Future versions of hosting environments should
-have no problem executing the **pexe**, even on new architectures.
-Moreover, if an existing architecture is subsequently enhanced, the
-**pexe** doesn't even have to be recompiled. In some cases the
-client-side translation will automatically be able to take advantage of
-the new capabilities. A **pexe** module can be part of any web
-application. It does not have to be distributed through the Chrome Web
-Store. In short, PNaCl combines the portability of existing web technologies 
-with the performance and security benefits of Native Client.
+With PNaCl, you'll generate a single pexe, rather than multiple platform-
+specific nexes. Since the pexe uses an abstract, architecture- and os-

[JF, 2014/09/19 18:16:17]

Capitalize OS.

[jpmedley, 2014/09/19 20:40:33]

Done.

+independent format, it does not suffer from the portability problem described
+above. Future versions of hosting environments should have no problem executing
+the pexe, even on new architectures. Moreover, if an existing architecture is
+enhanced, the pexe doesn't need to be recompiled. In some cases the client-side
+translation will automatically take advantage of new capabilities. A pexe can be
+part of any web application. It does not have to be distributed through the
+Chrome Web Store. In short, PNaCl combines the portability of existing web
+technologies with the performance and security benefits of Native Client.

[JF, 2014/09/19 18:16:17]

Interesting points we may want to make:
 * NaCl is currently an implementation detail of PNaCl: we still benefit from
the security that NaCl has.
 * PNaCl can be more efficient on certain operating systems, and can have novel
sandboxing approaches.

[jpmedley, 2014/09/19 20:40:32]

Done.

 
 PNaCl is a new technology, and as such it still has a few limitations
 as compared to NaCl. These limitations are described below.
 
+.. _when-to-use-pnacl:
+
 When to use PNaCl
 =================
 
 PNaCl is the preferred toolchain for Native Client, and the only way to deploy
-Native Client modules on the open web. Unless your project is subject to one
-of the narrow limitations described below
-(see :ref:`When to use NaCl<when-to-use-nacl>`), you should use PNaCl.
+Native Client modules without the Google Web Store. Unless your project is
+subject to one of the narrow limitations described under ":ref:`When to use
+NaCl<when-to-use-nacl>`", you should use PNaCl.
 
-Beginning with version 31, the Chrome browser supports translation of
-**pexe** modules and their use in web applications, without requiring
-any installation (either of a browser plugin or of the applications
-themselves). Native Client and PNaCl are open-source technologies, and
-our hope is that they will be added to other hosting platforms in the
-future.
+Since version 31, Chrome supports translation of pexe 
+modules and their use in web applications without requiring installation either
+of a browser plug-in or of the applications themselves. Native Client and PNaCl
+are open-source technologies, and our hope is that they will be added to other
+hosting platforms in the future.
 
-If controlled distribution through the Chrome Web Store is an important part
-of your product plan, the benefits of PNaCl are less critical for you. But
-you can still use the PNaCl toolchain and distribute your application
-through the Chrome Web Store, and thereby take advantage of the
-conveniences of PNaCl, such as not having to explicitly compile your application
-for all supported architectures.
+If controlled distribution through the Chrome Web Store is an important part of
+your product plan, the benefits of PNaCl are less critical for you. But you can
+still use the PNaCl toolchain and distribute your application through the Chrome
+Web Store, and thereby take advantage of the conveniences of PNaCl, such as not
+having to explicitly compile your application for all supported architectures.
 
 .. _when-to-use-nacl:
 
 When to use NaCl
 ================
 
-The limitations below apply to the current release of PNaCl. If any of
-these limitations are critical for your application, you should use
-non-portable NaCl:
+Use NaCl if any of the following apply to your application:
 
-* PNaCl does not support architecture-specific
-  instructions in an application (i.e., inline assembly), but tries to
-  offer high-performance portable equivalents. One such example is
-  PNaCl's :ref:`Portable SIMD Vectors <portable_simd_vectors>`.
-* PNaCl only supports static linking with the ``newlib``
-  C standard library (the Native Client SDK provides a PNaCl port of
-  ``newlib``). Dynamic linking and ``glibc`` are not yet supported.
-  Work is under way to enable dynamic linking in future versions of PNaCl.
-* PNaCl does not support some GNU extensions
-  like taking the address of a label for computed ``goto``, or nested
-  functions.
+* Your application requires architecture-specific instructions such as, for
+  example, inline assembly. PNaCl tries to offer high-performance portable
+  equivalents. One such example is PNaCl's :ref:`Portable SIMD Vectors 
+  <portable_simd_vectors>`.
+* Your application uses dynamic linking. PNaCl only supports static linking
+  with a PNaCl port of the ``newlib`` C standard library . Dynamic linking and
+  ``glibc`` are not yet supported in PNaCl. Work is under way to enable dynamic
+  linking in future versions of PNaCl.
+* Your application uses certain GNU extensions not supported by PNaCl, like

[JF, 2014/09/19 18:16:17]

"not supported by PNaCl's LLVM toolchain".

[jpmedley, 2014/09/19 20:40:33]

Done.

+  taking the address of a label for computed ``goto``, or nested functions.