[NaClDocs] Some cleanup for the Running the SDK Examples page.

- More info about browser flags w.r.t. PNaCl.
- Consistently use pepper 31 instead of mostly pepper 28 with
  a sprinkle of pepper 31.
- Add some TODOs about some possible issues.
- Change indentation, seems to affect formatting.

BUG= https://code.google.com/p/nativeclient/issues/detail?id=3634
NOTRY=true

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

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@228939 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 104 insertions, 93 deletions

diff --git a/native_client_sdk/src/doc/sdk/examples.rst b/native_client_sdk/src/doc/sdk/examples.rst
index 743ae65..f849bb3 100644
--- a/native_client_sdk/src/doc/sdk/examples.rst
+++ b/native_client_sdk/src/doc/sdk/examples.rst
@@ -11,17 +11,22 @@ on this page to build and run the examples.
 Configure the Google Chrome Browser
 -----------------------------------
 
-1. Your version of Chrome must be equal to or greater than the version of
-   your SDK bundle. For example, if you're developing with the ``pepper_28``
-   bundle, you must use Google Chrome version 28 or greater. To find out what
+#. Your version of Chrome must be equal to or greater than the version of
+   your SDK bundle. For example, if you're developing with the ``pepper_31``
+   bundle, you must use Google Chrome version 31 or greater. To find out what
    version of Chrome you're using, type ``about:chrome`` or ``about:version``
    in the Chrome address bar.
 
-2. Enable the Native Client flag. Native Client is enabled by default only
-   for applications distributed through the Chrome Web Store. To run Native
-   Client applications that are not distributed through the Chrome Web Store,
-   like the SDK examples, you must specifically enable the Native Client flag
-   in Chrome:
+#. For Portable Native Client, no extra Chrome flags are needed as of
+   Chrome version 31.
+
+   For other Native Client applications, or to **debug** Portable Native
+   Client applications by translating the **pexe** to a **nexe** ahead of
+   time, enable the Native Client flag. Native Client is enabled by default
+   only for applications distributed through the Chrome Web Store. To run
+   Native Client applications that are not distributed through the Chrome
+   Web Store, like the SDK examples, you must specifically enable the Native
+   Client flag in Chrome:
 
    * Type ``about:flags`` in the Chrome address bar and scroll down to
      "Native Client".
@@ -31,7 +36,7 @@ Configure the Google Chrome Browser
      link, scroll down to the bottom of the page, and click the "Relaunch
      Now" button. All browser windows will restart when you relaunch Chrome.
 
-3. Disable the Chrome cache. Chrome caches resources aggressively; when you
+#. Disable the Chrome cache. Chrome caches resources aggressively; when you
    are building a Native Client application you should disable the cache to
    make sure that Chrome loads the latest version:
 
@@ -53,85 +58,85 @@ toolchains).
 To build all the examples, go to the examples directory in a specific SDK
 bundle and run ``make``::
 
-    $ cd pepper_28/examples
-    $ make
-    make -C api  all
-    make[1]: Entering directory `pepper_28/examples/api'
-    make -C audio  all
-    make[2]: Entering directory `pepper_28/examples/api/audio'
-      CXX  newlib/Debug/audio_x86_32.o
-      LINK newlib/Debug/audio_x86_32.nexe
-      CXX  newlib/Debug/audio_x86_64.o
-      LINK newlib/Debug/audio_x86_64.nexe
-      CXX  newlib/Debug/audio_arm.o
-      LINK newlib/Debug/audio_arm.nexe
-      CREATE_NMF newlib/Debug/audio.nmf
-    make[2]: Leaving directory `pepper_28/examples/api/audio'
-    make -C url_loader  all
-    make[2]: Entering directory `pepper_28/examples/api/url_loader'
-      CXX  newlib/Debug/url_loader_x86_32.o
-    ...
+  $ cd pepper_31/examples
+  $ make
+  make -C api  all
+  make[1]: Entering directory `pepper_31/examples/api'
+  make -C audio  all
+  make[2]: Entering directory `pepper_31/examples/api/audio'
+    CXX  newlib/Debug/audio_x86_32.o
+    LINK newlib/Debug/audio_x86_32.nexe
+    CXX  newlib/Debug/audio_x86_64.o
+    LINK newlib/Debug/audio_x86_64.nexe
+    CXX  newlib/Debug/audio_arm.o
+    LINK newlib/Debug/audio_arm.nexe
+    CREATE_NMF newlib/Debug/audio.nmf
+  make[2]: Leaving directory `pepper_31/examples/api/audio'
+  make -C url_loader  all
+  make[2]: Entering directory `pepper_31/examples/api/url_loader'
+    CXX  newlib/Debug/url_loader_x86_32.o
+  ...
 
 Calling ``make`` from inside a particular example's directory will build only
 that example::
 
-    $ cd pepper_28/examples/api/core
-    $ make
-      CXX  newlib/Debug/core_x86_32.o
-      LINK newlib/Debug/core_x86_32.nexe
-      CXX  newlib/Debug/core_x86_64.o
-      LINK newlib/Debug/core_x86_64.nexe
-      CXX  newlib/Debug/core_arm.o
-      LINK newlib/Debug/core_arm.nexe
-      CREATE_NMF newlib/Debug/core.nmf
+  $ cd pepper_31/examples/api/core
+  $ make
+    CXX  newlib/Debug/core_x86_32.o
+    LINK newlib/Debug/core_x86_32.nexe
+    CXX  newlib/Debug/core_x86_64.o
+    LINK newlib/Debug/core_x86_64.nexe
+    CXX  newlib/Debug/core_arm.o
+    LINK newlib/Debug/core_arm.nexe
+    CREATE_NMF newlib/Debug/core.nmf
 
 You can call ``make`` with the ``TOOLCHAIN`` and ``CONFIG`` parameters to
 override the defaults::
 
-    $ make TOOLCHAIN=pnacl CONFIG=Release
-      CXX  pnacl/Release/core_pnacl.o
-      LINK pnacl/Release/core.bc
-      FINALIZE pnacl/Release/core.pexe
-      CREATE_NMF pnacl/Release/core.nmf
+  $ make TOOLCHAIN=pnacl CONFIG=Release
+    CXX  pnacl/Release/core_pnacl.o
+    LINK pnacl/Release/core.bc
+    FINALIZE pnacl/Release/core.pexe
+    CREATE_NMF pnacl/Release/core.nmf
 
 
 You can also set ``TOOLCHAIN`` to "all" to build one or more examples with
 all available toolchains::
 
-    $ make TOOLCHAIN=all
-    make TOOLCHAIN=newlib
-    make[1]: Entering directory `pepper_31/examples/api/core'
-      CXX  newlib/Debug/core_x86_32.o
-      LINK newlib/Debug/core_x86_32.nexe
-      CXX  newlib/Debug/core_x86_64.o
-      LINK newlib/Debug/core_x86_64.nexe
-      CXX  newlib/Debug/core_arm.o
-      LINK newlib/Debug/core_arm.nexe
-      CREATE_NMF newlib/Debug/core.nmf
-    make[1]: Leaving directory `pepper_31/examples/api/core'
-    make TOOLCHAIN=glibc
-    make[1]: Entering directory `pepper_31/examples/api/core'
-      CXX  glibc/Debug/core_x86_32.o
-      LINK glibc/Debug/core_x86_32.nexe
-      CXX  glibc/Debug/core_x86_64.o
-      LINK glibc/Debug/core_x86_64.nexe
-      CREATE_NMF glibc/Debug/core.nmf
-    make[1]: Leaving directory `pepper_31/examples/api/core'
-    make TOOLCHAIN=pnacl
-    make[1]: Entering directory `pepper_31/examples/api/core'
-      CXX  pnacl/Debug/core_pnacl.o
-      LINK pnacl/Debug/core.bc
-      FINALIZE pnacl/Debug/core.pexe
-      TRANSLATE pnacl/Debug/core_x86_32.nexe
-      TRANSLATE pnacl/Debug/core_x86_64.nexe
-      TRANSLATE pnacl/Debug/core_arm.nexe
-      CREATE_NMF pnacl/Debug/core.nmf
-    make[1]: Leaving directory `pepper_31/examples/api/core'
-    make TOOLCHAIN=linux
-    make[1]: Entering directory `pepper_31/examples/api/core'
-      CXX  linux/Debug/core.o
-      LINK linux/Debug/core.so
-    make[1]: Leaving directory `pepper_31/examples/api/core'
+  $ make TOOLCHAIN=all
+  make TOOLCHAIN=newlib
+  make[1]: Entering directory `pepper_31/examples/api/core'
+    CXX  newlib/Debug/core_x86_32.o
+    LINK newlib/Debug/core_x86_32.nexe
+    CXX  newlib/Debug/core_x86_64.o
+    LINK newlib/Debug/core_x86_64.nexe
+    CXX  newlib/Debug/core_arm.o
+    LINK newlib/Debug/core_arm.nexe
+    CREATE_NMF newlib/Debug/core.nmf
+  make[1]: Leaving directory `pepper_31/examples/api/core'
+  make TOOLCHAIN=glibc
+  make[1]: Entering directory `pepper_31/examples/api/core'
+    CXX  glibc/Debug/core_x86_32.o
+    LINK glibc/Debug/core_x86_32.nexe
+    CXX  glibc/Debug/core_x86_64.o
+    LINK glibc/Debug/core_x86_64.nexe
+    CREATE_NMF glibc/Debug/core.nmf
+  make[1]: Leaving directory `pepper_31/examples/api/core'
+  make TOOLCHAIN=pnacl
+  make[1]: Entering directory `pepper_31/examples/api/core'
+    CXX  pnacl/Debug/core_pnacl.o
+    LINK pnacl/Debug/core.bc
+    FINALIZE pnacl/Debug/core.pexe
+    TRANSLATE pnacl/Debug/core_x86_32.nexe
+    TRANSLATE pnacl/Debug/core_x86_64.nexe
+    TRANSLATE pnacl/Debug/core_arm.nexe
+    CREATE_NMF pnacl/Debug/core.nmf
+  make[1]: Leaving directory `pepper_31/examples/api/core'
+  make TOOLCHAIN=linux
+  make[1]: Entering directory `pepper_31/examples/api/core'
+    CXX  linux/Debug/core.o
+    LINK linux/Debug/core.so
+  make[1]: Leaving directory `pepper_31/examples/api/core'
 
 
 After running ``make``, each example directory will contain one or more of
@@ -159,8 +164,8 @@ Run the SDK examples
 
 To run the SDK examples, you can use the ``make run`` command::
 
-    $ cd pepper_28/examples/api/core
-    $ make run
+  $ cd pepper_31/examples/api/core
+  $ make run
 
 This will launch a local HTTP server which will serve the data for the
 example. It then launches Chrome with the address of this server, usually
@@ -171,30 +176,31 @@ This command will try to find an executable named ``google-chrome`` in your
 ``PATH`` environment variable. If it can't, you'll get an error message like
 this::
 
-    pepper_31/tools/common.mk:415: No valid Chrome found at CHROME_PATH=
-    pepper_31/tools/common.mk:415: *** Set CHROME_PATH via an environment variable, or command-line..  Stop.
+  pepper_31/tools/common.mk:415: No valid Chrome found at CHROME_PATH=
+  pepper_31/tools/common.mk:415: *** Set CHROME_PATH via an environment variable, or command-line..  Stop.
 
 Set the CHROME_PATH environment variable to the location of your Chrome
-executable **TODO(binji):** use default Chrome paths here, especially
-important for Mac:
+executable.
 
-    On Windows::
+On Windows::
 
-      > set CHROME_PATH=<Path to chrome.exe>
+  > set CHROME_PATH=<Path to chrome.exe>
 
-    On Linux::
+On Linux::
 
-      $ export CHROME_PATH=<Path to google-chrome>
+  $ export CHROME_PATH=<Path to google-chrome>
 
-    On Mac::
+On Mac::
 
-      $ export CHROME_PATH=<Path to chrome>
+  $ export CHROME_PATH=<Path to chrome>
 
+.. **TODO(binji):** use default Chrome paths here, especially
+.. important for Mac:
 
 You can run via a different toolchain or configuration by using the
 ``TOOLCHAIN`` and ``CONFIG`` parameters to make::
 
-    $ make run TOOLCHAIN=pnacl CONFIG=Debug
+  $ make run TOOLCHAIN=pnacl CONFIG=Debug
 
 
 Run the SDK examples as packaged apps
@@ -210,11 +216,16 @@ Some Pepper features, such as TCP/UDP socket access, are only allowed in
 packaged apps. The examples that use these features must be run as packaged
 apps, by using the ``make run_package`` command::
 
-    $ make run_package
+  $ make run_package
 
 You can use ``TOOLCHAIN`` and ``CONFIG`` parameters as above to run with a
 different toolchain or configuration.
 
+.. **TODO(jvoung)**: That doesn't seem to work in pepper_canary.
+.. It just picks newlib.
+.. https://code.google.com/p/chromium/issues/detail?id=307724
+
+
 .. _debugging_the_sdk_examples:
 
 Debugging the SDK examples
@@ -224,7 +235,7 @@ The NaCl SDK uses `GDB <https://www.gnu.org/software/gdb/>`_ to debug Native
 Client code. The SDK includes a prebuilt version of GDB that is compatible with
 NaCl code. To use it, run the ``make debug`` command from an example directory::
 
-    $ make debug
+  $ make debug
 
 This will launch Chrome with the ``--enable-nacl-debug`` flag set. This flag
 will cause Chrome to pause when a NaCl module is first loaded, waiting for a
@@ -232,13 +243,13 @@ connection from gdb. The ``make debug`` command also simultaneously launches
 GDB and loads the symbols for that NEXE. To connect GDB to Chrome, in the GDB
 console, type::
 
-    (gdb) target remote :4014
+  (gdb) target remote :4014
 
 This tells GDB to connect to a TCP port on localhost:4014--the port that
 Chrome is listening on. GDB will respond::
 
-    Remote debugging using :4014
-    0x000000000fa00080 in ?? ()
+  Remote debugging using :4014
+  0x000000000fa00080 in ?? ()
 
 At this point, you can use the standard GDB commands to debug your NaCl module.
 The most common commands you will use to debug are ``continue``, ``step``,