Copy edit Learn Basics section. Includes first group of new illustrations to...

Copy edit Learn Basics section. Includes first group of new illustrations to make overall site images look googly and at the same time part of a single design process.

BUG=none
R=
TEST=none
NOTRY=true
(documentation only change)

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

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

chrome/common/extensions/docs/templates/json/chrome_sidenav.json

@@ -693,7 +693,7 @@
             "href": "/native-client/overview",
             "items": [
               {
-                "title": "What Is Native Client?",
+                "title": "Technical Overview",
                 "href": "/native-client/overview"
               },
               {

native_client_sdk/doc_generated/sitemap.html

@@ -6,11 +6,11 @@
 <div class="toctree-wrapper compound">
 <ul class="small-gap">
 <li class="toctree-l1"><a class="reference internal" href="/native-client/overview.html">Technical Overview</a><ul class="small-gap">
-<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#introduction">Introduction</a></li>
 <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#why-use-native-client">Why use Native Client?</a></li>
+<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#benefits-of-native-client">Benefits of Native Client</a></li>
 <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#common-use-cases">Common use cases</a></li>
 <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#how-native-client-works">How Native Client works</a></li>
-<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#native-client-in-a-web-application">Native Client in a web application</a></li>
+<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#structure-of-a-web-application">Structure of a web application</a></li>
 <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#versioning">Versioning</a></li>
 <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#where-to-start">Where to start</a></li>
 </ul>

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

@@ -12,103 +12,102 @@ 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. It does this by running compiled C and C++
+code at near-native speeds, and exposing a CPU's full capabilities, including
+SIMD vectors and multiple-core processing with shared memory.
+
+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
+  ``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.