Copy edit Learn Basics section.

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

Index: native_client_sdk/src/doc/nacl-and-pnacl.rst
diff --git a/native_client_sdk/src/doc/nacl-and-pnacl.rst b/native_client_sdk/src/doc/nacl-and-pnacl.rst
index 7eb07fb46a4f3e5ee6699e8bcb142462177935b6..07e12a070a3bffaad8dbead30a1f652a1ba6d2bd 100644
--- a/native_client_sdk/src/doc/nacl-and-pnacl.rst
+++ b/native_client_sdk/src/doc/nacl-and-pnacl.rst
@@ -12,103 +12,101 @@ This document describes the differences between **Native Client** and
   :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.
-
-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
+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.

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

Mention SIMD too? Or maybe rephrase to explain that we expose a CPU's full
capabilities, which includes SIMD and multicore+share memory?

[jpmedley, 2014/09/22 17:19:50]

Done.

+
+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 convenient, making it ill-suited for the
+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.
-
-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.
-
-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.
+#. compiling the source code to a bitcode executable (pexe), and
+#. translating the bitcode to a host-specific executable as soon as the module
+   loads in the browser but before any code execution.
+
+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, you'll generate a single pexe, rather than multiple platform-
+specific nexes. Since the pexe uses an abstract, architecture- and OS-
+independent format, it does not suffer from the portability problem described
+above. Although, PNaCl can be more efficient on some operating systems than on
+others. PNaCl boasts the same level of security as NaCl. 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.
 
 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.
-
-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.
-
-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.
+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.
+
+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.
 
 .. _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:
-
-* 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
+Use NaCl if any of the following apply to your application:
+
+* 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

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

There's a space before the period .

[jpmedley, 2014/09/22 17:19:50]

Done.

+  ``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's LLVM
+  toolchain, like taking the address of a label for computed ``goto``, or nested
   functions.