Created PNaCl translation documenation and updated old NaCl documents.

mojo/nacl/nonsfi/README.md

Index: mojo/nacl/nonsfi/README.md
diff --git a/mojo/nacl/nonsfi/README.md b/mojo/nacl/nonsfi/README.md
index 3ecae5a094d5eda32c073bbd018b20d427fa3a04..3fcd4136d1dcb3db0658205ed181369da69d37b9 100644
--- a/mojo/nacl/nonsfi/README.md
+++ b/mojo/nacl/nonsfi/README.md
@@ -11,6 +11,9 @@ The Non-SFI NaCl and accompanying tests should be built by default for Linux.
 The boolean indicating if they are built is "mojo_use_nacl_nonsfi", defined
 inside the BUILD files.
 
+Building Non-SFI NaCl
+---------------------
+
 Build Mojo (all following commands assume you are in the root of the mojo
 repository):
 
@@ -19,9 +22,44 @@ $  ./mojo/tools/mojob.py gn
 $  ./mojo/tools/mojob.py build
 ```
 
-Doing this build step will automatically create a pexe of unit tests, at
-`./out/Debug/newlib_pnacl/monacl_test.pexe`.  To translate a pexe into a
-non-SFI nexe:
+Doing this build step will automatically create the necessary content handlers
+and pexes.
+
+Translating and Running Pexes
+-----------------------------
+
+When portable executable files (pexes) are generated by mojo, they are created
+as `.pexe.mojo` files. These pexes are generated by building a gn target with
+the `mojo_native_application` template with a PNaCl toolchain.
+
+The "pexe" part of the name comes from the fact that they are portable, and the
+"mojo" part of the name comes from the fact that they have the line `#!mojo
+mojo:content_handler_nonsfi_pexe` prepended to them, so the appropriate pexe
+content handler can be found by the Mojo Shell.
+
+To run the `FOOBAR.pexe.mojo` pexe (aka, to translate and execute it), run the
+following:
+
+```
+$ ./out/Debug/mojo_shell --enable-multiprocess ./out/Debug/FOOBAR.pexe.mojo
+```
+
+or, alternatively, for a version compatible with Android:
+
+```
+$  ./mojo/devtools/common/mojo_run --enable-multiprocess mojo:FOOBAR.pexe
+[--android]
+```
+
+For more information on the process of translating and handling nexes and pexes,
+refer to the `services/nacl` directory.
+
+Manually Translating Pexes and Running Nexes
+--------------------------------------------
+
+A raw pexe of unit tests will be built, at
+`./out/Debug/newlib_pnacl/monacl_test.pexe`.  To manually translate this pexe
+into a non-SFI nexe:
 
 ```
 $ ./native_client/toolchain/linux_x86/pnacl_newlib/bin/pnacl-translate \
@@ -29,9 +67,9 @@ $ ./native_client/toolchain/linux_x86/pnacl_newlib/bin/pnacl-translate \
 ```
 
 Now, you should have the fully translated nexe (called
-"FOOBAR.nexe").  You can run the nexe through the monacl shell
+`FOOBAR.nexe`).  You can run the nexe through the monacl shell
 (a minimal, "nexe-only" shell, which loads the nexe ELF file -- see
- monacl_shell_nonsfi.cc):
+ `monacl_shell_nonsfi.cc`):
 
 ```
 $ ./out/Debug/clang_x86/monacl_shell_nonsfi FOOBAR.nexe
@@ -43,19 +81,13 @@ is not the only way. Usually, applications are launched through the
 this content (i.e., how does the mojo_shell know it is dealing with a nonsfi
 nexe?).
 
-The BUILD.gn files in Mojo automatically make this pexe, translate it to a
-nexe, and prepend a line ("#!mojo mojo:content_handler_nonsfi_nexe") to the
-front of the file, at which point it is also runnable through the mojo_shell.
+The BUILD.gn files in Mojo automatically make the "monacl_test" pexe, translate
+it to a nexe, and prepend a line (`#!mojo mojo:content_handler_nonsfi_nexe`) to
+the front of the file, at which point it is also runnable through the
+mojo_shell.
 These files, which start with this "#!" line, are ".mojo" files. The nexes can
 be run like this:
 
 ```
 $  ./out/Debug/mojo_shell --enable-multiprocess out/Debug/FOOBAR.mojo
 ```
-
-TODO
-====
-
-* Use subzero (a NaCl project to improve translation speed) for pexe
-translation.
-* Enable caching of translated pexes.