Swap READMEs to markdown

Suggested by vapier@ in I7daf1cbe93f8809e469698d7772a6c68baf9e194

This ignores README.chromium, since I'm unsure if that's a special name
that some tool somewhere relies on.

I skimmed over all of these in gitiles (as you can probably tell by the
35 patch sets :) ) and fixed the issues that jumped out at me. I'm sure
that some remain somewhere, but I think I got the majority of them.

An attempt has been made to make all files roughly follow the rules
here:
https://github.com/google/styleguide/blob/gh-pages/docguide/style.md

Note that not all of them have super meaningful introductions with
ToCs/etc, but the rest should be relatively consistent with that guide.

BUG=None
TEST=Manual inspection

Change-Id: I158048d972d49966e3b8ff1e07e5429928edb339
Reviewed-on: https://chromium-review.googlesource.com/1504893
Commit-Ready: George Burgess <gbiv@chromium.org>
Tested-by: George Burgess <gbiv@chromium.org>
Reviewed-by: George Burgess <gbiv@chromium.org>

13 files changed, 902 insertions, 813 deletions

diff --git a/binary_search_tool/README.bisect b/binary_search_tool/README.bisect
deleted file mode 100644
index 49e0c085..00000000
--- a/binary_search_tool/README.bisect
+++ /dev/null
@@ -1,217 +0,0 @@
-
-bisect.py is a wrapper around the general purpose
-binary_search_state.py. It provides a user friendly interface for
-bisecting various compilation errors.  The 2 currently provided
-methods of bisecting are ChromeOS package and object bisection. Each
-method defines a default set of options to pass to
-binary_search_state.py and allow the user to override these defaults
-(see the "Overriding" section).
-
-** NOTE **
-All commands, examples, scripts, etc. are to be run from your chroot unless
-stated otherwise.
-
-Bisection Methods:
-
-1) ChromeOS Package:
-  This method will bisect across all packages in a ChromeOS repository and find
-  the offending packages (according to your test script). This method takes the
-  following arguments:
-
-    board: The board to bisect on. For example: daisy, falco, etc.
-    remote: The IP address of the physical machine you're using to test with.
-
-  By default the ChromeOS package method will do a simple interactive test that
-  pings the machine and prompts the user if the machine is good.
-
-  a) Setup:
-    The ChromeOS package method requires that you have three build trees:
-
-      /build/${board}.bad  - The build tree for your "bad" build
-      /build/${board}.good - The build tree for your "good" build
-      /build/${board}.work - A full copy of /build/${board}.bad
-
-  b) Cleanup:
-    bisect.py does most cleanup for you, the only
-    thing required by the user is to cleanup all built images and the
-    three build trees made in /build/
-
-  c) Default Arguments:
-    --get_initial_items='cros_pkg/get_initial_items.sh'
-    --switch_to_good='cros_pkg/switch_to_good.sh'
-    --switch_to_bad='cros_pkg/switch_to_bad.sh'
-    --test_setup_script='cros_pkg/test_setup.sh'
-    --test_script='cros_pkg/interactive_test.sh'
-    --incremental
-    --prune
-    --file_args
-
-  d) Additional Documentation:
-    See ./cros_pkg/README.cros_pkg_triage for full documentation of ChromeOS
-    package bisection.
-
-  e) Examples:
-    i)  Basic interactive test package bisection, on daisy board:
-        ./bisect.py package daisy 172.17.211.184
-
-    ii) Basic boot test package bisection, on daisy board:
-        ./bisect.py package daisy 172.17.211.184 -t cros_pkg/boot_test.sh
-
-2) ChromeOS Object:
-  This method will bisect across all objects in a ChromeOS package and find
-  the offending objects (according to your test script). This method takes the
-  following arguments:
-
-    board: The board to bisect on. For example: daisy, falco, etc.
-    remote: The IP address of the physical machine you're using to test with.
-    package: The package to bisect with. For example: chromeos-chrome
-    dir: (Optional) the directory for your good/bad build trees. Defaults to
-         $BISECT_DIR or /tmp/sysroot_bisect. This value will set $BISECT_DIR
-         for all bisecting scripts.
-
-  By default the ChromeOS object method will do a simple interactive test that
-  pings the machine and prompts the user if the machine is good.
-
-  a) Setup:
-    The ChromeOS package method requires that you populate your good and bad set
-    of objects. sysroot_wrapper will automatically detect the BISECT_STAGE
-    variable and use this to populate emerged objects. Here is an example:
-
-      # Defaults to /tmp/sysroot_bisect
-      export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
-
-      export BISECT_STAGE="POPULATE_GOOD"
-      ./switch_to_good_compiler.sh
-      emerge-${board} -C ${package_to_bisect}
-      emerge-${board} ${package_to_bisect}
-
-      export BISECT_STAGE="POPULATE_BAD"
-      ./switch_to_bad_compiler.sh
-      emerge-${board} -C {package_to_bisect}
-      emerge-${board} ${package_to_bisect}
-
-  b) Cleanup:
-    The user must clean up all built images and the populated object files.
-
-  c) Default Arguments:
-    --get_initial_items='sysroot_wrapper/get_initial_items.sh'
-    --switch_to_good='sysroot_wrapper/switch_to_good.sh'
-    --switch_to_bad='sysroot_wrapper/switch_to_bad.sh'
-    --test_setup_script='sysroot_wrapper/test_setup.sh'
-    --test_script='sysroot_wrapper/interactive_test.sh'
-    --noincremental
-    --prune
-    --file_args
-
-  d) Additional Documentation:
-    See ./sysroot_wrapper/README for full documentation of ChromeOS object file
-    bisecting.
-
-  e) Examples:
-    i)  Basic interactive test object bisection, on daisy board for
-        cryptohome package:
-        ./bisect.py object daisy 172.17.211.184 cryptohome
-
-    ii) Basic boot test package bisection, on daisy board for cryptohome
-        package:
-        ./bisect.py object daisy 172.17.211.184 cryptohome \
-        --test_script=sysroot_wrapper/boot_test.sh
-
-3) Android object:
-  NOTE: Because this isn't a ChromeOS bisection tool, the concept of a
-        chroot doesn't exist. Just run this tool from a normal shell.
-
-  This method will bisect across all objects in the Android source tree and
-  find the offending objects (according to your test script). This method takes
-  the following arguments:
-
-    android_src: The location of your android source tree
-    num_jobs: (Optional) The number of jobs to pass to make. This is dependent
-              on how many cores your machine has. A good number is probably
-	      somewhere around 5 to 10.
-    device_id: (Optional) The serial code for the device you are testing on.
-               This is used to determine which device should be used in case
-	       multiple devices are plugged into your computer. You can get
-	       serial code for your device by running "adb devices".
-    dir: (Optional) the directory for your good/bad build trees. Defaults to
-         $BISECT_DIR or ~/ANDROID_BISECT/. This value will set $BISECT_DIR
-         for all bisecting scripts.
-
-  By default the Android object method will do a simple interactive test that
-  pings the machine and prompts the user if the machine is good.
-
-  a) Setup:
-    The Android object method requires that you populate your good and bad set
-    of objects. The Android compiler wrapper will automatically detect the
-    BISECT_STAGE variable and use this to populate emerged objects. Here is an
-    example:
-
-      # Defaults to ~/ANDROID_BISECT/
-      export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
-
-      export BISECT_STAGE="POPULATE_GOOD"
-      # Install the "good" compiler
-      ./switch_to_good_compiler.sh
-      make clean
-      make -j <your_preferred_number_of_jobs>
-
-      export BISECT_STAGE="POPULATE_BAD"
-      # Install the "bad" compiler
-      ./switch_to_bad_compiler.sh
-      make clean
-      make -j <your_preferred_number_of_jobs>
-
-  b) Cleanup:
-    The user must clean up all built images and the populated object files.
-
-  c) Default Arguments:
-    --get_initial_items='android/get_initial_items.sh'
-    --switch_to_good='android/switch_to_good.sh'
-    --switch_to_bad='android/switch_to_bad.sh'
-    --test_setup_script='android/test_setup.sh'
-    --test_script='android/interactive_test.sh'
-    --incremental
-    --prune
-    --file_args
-
-  d) Additional Documentation:
-    See ./android/README.android for full documentation of Android object file
-    bisecting.
-
-  e) Examples:
-    i)  Basic interactive test android bisection, where the android source is
-        at ~/android_src:
-        ./bisect.py android ~/android_src
-
-    ii) Basic boot test android bisection, where the android source is at
-        ~/android_src, and 10 jobs will be used to build android:
-        ./bisect.py android ~/android_src --num_jobs=10 \
-        --test_script=sysroot_wrapper/boot_test.sh
-
-Resuming:
-  bisect.py and binary_search_state.py offer the
-  ability to resume a bisection in case it was interrupted by a
-  SIGINT, power failure, etc. Every time the tool completes a
-  bisection iteration its state is saved to disk (usually to the file
-  "./bisect_driver.py.state"). If passed the --resume option, the tool
-  it will automatically detect the state file and resume from the last
-  completed iteration.
-
-Overriding:
-  You can run ./bisect.py --help or ./binary_search_state.py
-  --help for a full list of arguments that can be overriden. Here are
-  a couple of examples:
-
-  Example 1 (do boot test instead of interactive test):
-  ./bisect.py package daisy 172.17.211.182 --test_script=cros_pkg/boot_test.sh
-
-  Example 2 (do package bisector system test instead of interactive test, this
-             is used to test the bisecting tool itself -- see comments in
-             hash_test.sh for more details):
-  ./bisect.py package daisy 172.17.211.182 \
-    --test_script=common/hash_test.sh --test_setup_script=""
-
-  Example 3 (enable verbose mode, disable pruning, and disable verification):
-  ./bisect.py package daisy 172.17.211.182 \
-  --verbose --prune=False --verify=False
-
diff --git a/binary_search_tool/README.bisect.md b/binary_search_tool/README.bisect.md
new file mode 100644
index 00000000..74715ca0
--- /dev/null
+++ b/binary_search_tool/README.bisect.md
@@ -0,0 +1,248 @@
+# `bisect.py`
+
+`bisect.py` is a wrapper around the general purpose
+`binary_search_state.py`. It provides a user friendly interface for
+bisecting various compilation errors.  The 2 currently provided
+methods of bisecting are ChromeOS package and object bisection. Each
+method defines a default set of options to pass to
+`binary_search_state.py` and allow the user to override these defaults
+(see the "Overriding" section).
+
+Please note that all commands, examples, scripts, etc. are to be run from your
+chroot unless stated otherwise.
+
+## Bisection Methods
+
+### ChromeOS Package
+
+This method will bisect across all packages in a ChromeOS repository and find
+the offending packages (according to your test script). This method takes the
+following arguments:
+
+* board: The board to bisect on. For example: daisy, falco, etc.
+* remote: The IP address of the physical machine you're using to test with.
+
+By default the ChromeOS package method will do a simple interactive test that
+pings the machine and prompts the user if the machine is good.
+
+1.  Setup: The ChromeOS package method requires that you have three build trees:
+
+    ```
+    /build/${board}.bad  - The build tree for your "bad" build
+    /build/${board}.good - The build tree for your "good" build
+    /build/${board}.work - A full copy of /build/${board}.bad
+    ```
+
+1.  Cleanup: bisect.py does most cleanup for you, the only thing required by the
+    user is to cleanup all built images and the three build trees made in
+    `/build/`
+
+1.  Default Arguments:
+
+    ```
+    --get_initial_items='cros_pkg/get_initial_items.sh'
+    --switch_to_good='cros_pkg/switch_to_good.sh'
+    --switch_to_bad='cros_pkg/switch_to_bad.sh'
+    --test_setup_script='cros_pkg/test_setup.sh'
+    --test_script='cros_pkg/interactive_test.sh'
+    --incremental
+    --prune
+    --file_args
+    ```
+
+1.  Additional Documentation: See `./cros_pkg/README.cros_pkg_triage` for full
+    documentation of ChromeOS package bisection.
+
+1.  Examples:
+
+    1.  Basic interactive test package bisection, on daisy board:
+
+        ```
+        ./bisect.py package daisy 172.17.211.184
+        ```
+
+    2.  Basic boot test package bisection, on daisy board:
+
+        ```
+        ./bisect.py package daisy 172.17.211.184 -t cros_pkg/boot_test.sh
+        ```
+
+### ChromeOS Object
+
+This method will bisect across all objects in a ChromeOS package and find
+the offending objects (according to your test script). This method takes the
+following arguments:
+
+* board: The board to bisect on. For example: daisy, falco, etc.
+* remote: The IP address of the physical machine you're using to test with.
+* package: The package to bisect with. For example: chromeos-chrome
+* dir: (Optional) the directory for your good/bad build trees. Defaults to
+       $BISECT_DIR or /tmp/sysroot_bisect. This value will set $BISECT_DIR
+       for all bisecting scripts.
+
+By default the ChromeOS object method will do a simple interactive test that
+pings the machine and prompts the user if the machine is good.
+
+1.  Setup: The ChromeOS package method requires that you populate your good and
+    bad set of objects. `sysroot_wrapper` will automatically detect the
+    `BISECT_STAGE` variable and use this to populate emerged objects. Here is an
+    example:
+
+    ```
+    # Defaults to /tmp/sysroot_bisect
+    export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
+
+    export BISECT_STAGE="POPULATE_GOOD"
+    ./switch_to_good_compiler.sh
+    emerge-${board} -C ${package_to_bisect}
+    emerge-${board} ${package_to_bisect}
+
+    export BISECT_STAGE="POPULATE_BAD"
+    ./switch_to_bad_compiler.sh
+    emerge-${board} -C {package_to_bisect}
+    emerge-${board} ${package_to_bisect}
+    ```
+
+1.  Cleanup: The user must clean up all built images and the populated object
+    files.
+
+1.  Default Arguments:
+
+    ```
+    --get_initial_items='sysroot_wrapper/get_initial_items.sh'
+    --switch_to_good='sysroot_wrapper/switch_to_good.sh'
+    --switch_to_bad='sysroot_wrapper/switch_to_bad.sh'
+    --test_setup_script='sysroot_wrapper/test_setup.sh'
+    --test_script='sysroot_wrapper/interactive_test.sh'
+    --noincremental
+    --prune
+    --file_args
+    ```
+
+1.  Additional Documentation: See `./sysroot_wrapper/README` for full
+    documentation of ChromeOS object file bisecting.
+
+1.  Examples:
+
+    1.  Basic interactive test object bisection, on daisy board for cryptohome
+        package: `./bisect.py object daisy 172.17.211.184 cryptohome`
+
+    2.  Basic boot test package bisection, on daisy board for cryptohome
+        package: `./bisect.py object daisy 172.17.211.184 cryptohome
+        --test_script=sysroot_wrapper/boot_test.sh`
+
+### Android object
+
+NOTE: Because this isn't a ChromeOS bisection tool, the concept of a
+      chroot doesn't exist. Just run this tool from a normal shell.
+
+This method will bisect across all objects in the Android source tree and
+find the offending objects (according to your test script). This method takes
+the following arguments:
+
+*   `android_src`: The location of your android source tree
+
+*   `num_jobs`: (Optional) The number of jobs to pass to make. This is dependent
+    on how many cores your machine has. A good number is probably somewhere
+    around 5 to 10.
+
+*   `device_id`: (Optional) The serial code for the device you are testing on.
+    This is used to determine which device should be used in case multiple
+    devices are plugged into your computer. You can get serial code for your
+    device by running "adb devices".
+
+*   `dir`: (Optional) the directory for your good/bad build trees. Defaults to
+    `$BISECT_DIR` or `~/ANDROID_BISECT/`. This value will set `$BISECT_DIR` for
+    all bisecting scripts.
+
+  By default the Android object method will do a simple interactive test that
+  pings the machine and prompts the user if the machine is good.
+
+1.  Setup: The Android object method requires that you populate your good and
+    bad set of objects. The Android compiler wrapper will automatically detect
+    the `BISECT_STAGE` variable and use this to populate emerged objects. Here
+    is an example:
+
+    ```
+    # Defaults to ~/ANDROID_BISECT/
+    export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
+
+    export BISECT_STAGE="POPULATE_GOOD"
+    # Install the "good" compiler
+    ./switch_to_good_compiler.sh
+    make clean
+    make -j <your_preferred_number_of_jobs>
+
+    export BISECT_STAGE="POPULATE_BAD"
+    # Install the "bad" compiler
+    ./switch_to_bad_compiler.sh
+    make clean
+    make -j <your_preferred_number_of_jobs>
+    ```
+
+1.  Cleanup: The user must clean up all built images and the populated object
+    files.
+
+1.  Default Arguments:
+
+    ```
+    --get_initial_items='android/get_initial_items.sh'
+    --switch_to_good='android/switch_to_good.sh'
+    --switch_to_bad='android/switch_to_bad.sh'
+    --test_setup_script='android/test_setup.sh'
+    --test_script='android/interactive_test.sh'
+    --incremental
+    --prune
+    --file_args
+    ```
+
+1.  Additional Documentation: See `./android/README.android` for full
+    documentation of Android object file bisecting.
+
+1.  Examples:
+
+    1.  Basic interactive test android bisection, where the android source is at
+        ~/android_src: `./bisect.py android ~/android_src`
+
+    2. Basic boot test android bisection, where the android source is at
+       `~/android_src`, and 10 jobs will be used to build android: `./bisect.py
+       android ~/android_src --num_jobs=10
+       --test_script=sysroot_wrapper/boot_test.sh`
+
+### Resuming
+
+`bisect.py` and `binary_search_state.py` offer the
+ability to resume a bisection in case it was interrupted by a
+SIGINT, power failure, etc. Every time the tool completes a
+bisection iteration its state is saved to disk (usually to the file
+`./bisect_driver.py.state`). If passed the --resume option, the tool
+it will automatically detect the state file and resume from the last
+completed iteration.
+
+### Overriding
+
+You can run `./bisect.py --help` or `./binary_search_state.py
+--help` for a full list of arguments that can be overriden. Here are
+a couple of examples:
+
+Example 1 (do boot test instead of interactive test):
+
+```
+./bisect.py package daisy 172.17.211.182 --test_script=cros_pkg/boot_test.sh
+```
+
+Example 2 (do package bisector system test instead of interactive test, this
+           is used to test the bisecting tool itself -- see comments in
+           hash_test.sh for more details):
+
+```
+./bisect.py package daisy 172.17.211.182 \
+    --test_script=common/hash_test.sh --test_setup_script=""
+```
+
+Example 3 (enable verbose mode, disable pruning, and disable verification):
+
+```
+./bisect.py package daisy 172.17.211.182
+      --verbose --prune=False --verify=False
+```
diff --git a/binary_search_tool/README.pass_bisect b/binary_search_tool/README.pass_bisect
deleted file mode 100644
index 3d419b26..00000000
--- a/binary_search_tool/README.pass_bisect
+++ /dev/null
@@ -1,77 +0,0 @@
-This document describes a feature for the bisection tool, which provides
-pass and transformation level bisection for a bad object file.
-
-Before reading this document, please refer to README.bisect for general usage
-of the bisection tool.
-
-The benefit of using pass level bisection is:
-When building a bad object file, it can tell you which pass and transformation
-in the compiler caused the error.
-
-Notice: This tool will only work for LLVM/clang, since it is using options
-        `-opt-bisect-limit` and `print-debug-counter` that only exist in LLVM.
-
-ARGUMENTS
-
-    All the required arguments in object-file-level bisection tool are still
-    to be provided. In addition, you will need to add the following arguments:
-
-    1)--pass_bisect: enables pass level bisection
-    2)--ir_diff: enables output of IR differences
-
-    Please refer to `--help` or the examples below for details about how to use
-    them. 
-
-HOW TO USE: ChromeOS
-
-TODO - Future work: Currently this only works for Android.
-
-HOW TO USE: Android
-
-    1) Prerequisite
-
-        A general setup is still needed for Android, which means that you need
-        to populate good and bad set of objects with two versions of compilers.
-
-        See the documentation in README.bisect for more detailed instructions.
-
-    2) Pass/Transformation Bisection
-
-        If you do not wish to override the other arguments, this command should
-        be sufficient to do pass/transformation level bisection:
-
-        ./bisect.py android PATH_TO_ANDROID_HOME_DIR
-                    --pass_bisect=’android/generate_cmd.sh’
-                    --prune=False
-                    --ir_diff
-                    --verbose
-
-        Where:
-            --pass_bisect:
-                Enables pass/transformation level bisection and with default
-                script to generate the command as ‘android/generate_cmd.sh’.
-            --prune:
-                For now, prune must be set to False to return only the first
-                bad item.
-            --ir_diff:
-                Optional argument to print out IR differences.
-            --verbose:
-                To show IR diff, verbose needs to be on.
-
-        Other default arguments:
-            --get_initial_items='android/get_initial_items.sh'
-            --switch_to_good='android/switch_to_good.sh'
-            --switch_to_bad='android/switch_to_bad.sh'
-            --test_setup_script='android/test_setup.sh'
-            --test_script='android/interactive_test.sh'
-            --incremental
-            --prune
-            --file_args
-
-        You can always override them if needed. See README.bisect for more
-        details.
-
-    3) Other features:
-
-        Features such as resuming, number of jobs, and device id remain the
-        same as before. See README.bisect for more details.
diff --git a/binary_search_tool/README.pass_bisect.md b/binary_search_tool/README.pass_bisect.md
new file mode 100644
index 00000000..d03a563b
--- /dev/null
+++ b/binary_search_tool/README.pass_bisect.md
@@ -0,0 +1,83 @@
+# Pass bisection
+
+This document describes a feature for the bisection tool, which provides
+pass and transformation level bisection for a bad object file.
+
+Before reading this document, please refer to README.bisect for general usage
+of the bisection tool.
+
+The benefit of using pass level bisection is:
+When building a bad object file, it can tell you which pass and transformation
+in the compiler caused the error.
+
+*Notice:* This tool will only work for LLVM/clang, since it is using options
+`-opt-bisect-limit` and `print-debug-counter` that only exist in LLVM.
+
+## Arguments
+
+All the required arguments in object-file-level bisection tool are still
+to be provided. In addition, you will need to add the following arguments:
+
+1. `--pass_bisect`: enables pass level bisection
+2. `--ir_diff`: enables output of IR differences
+
+Please refer to `--help` or the examples below for details about how to use
+them.
+
+## HOW TO USE: ChromeOS
+
+*TODO* - Future work: Currently this only works for Android.
+
+## HOW TO USE: Android
+
+1.  Prerequisites: A general setup is still needed for Android, which means that
+    you need to populate good and bad set of objects with two versions of
+    compilers.
+
+    See the documentation in `README.bisect.md` for more detailed instructions.
+
+1.  Pass/Transformation Bisection: If you do not wish to override the other
+    arguments, this command should be sufficient to do pass/transformation level
+    bisection:
+
+    ```
+    ./bisect.py android PATH_TO_ANDROID_HOME_DIR
+                --pass_bisect=’android/generate_cmd.sh’
+                --prune=False
+                --ir_diff
+                --verbose
+    ```
+
+    Where:
+
+    ```
+    --pass_bisect:
+        Enables pass/transformation level bisection and with default
+        script to generate the command as ‘android/generate_cmd.sh’.
+    --prune:
+        For now, prune must be set to False to return only the first
+        bad item.
+    --ir_diff:
+        Optional argument to print out IR differences.
+    --verbose:
+        To show IR diff, verbose needs to be on.
+    ```
+
+    Other default arguments:
+
+    ```
+    --get_initial_items='android/get_initial_items.sh'
+    --switch_to_good='android/switch_to_good.sh'
+    --switch_to_bad='android/switch_to_bad.sh'
+    --test_setup_script='android/test_setup.sh'
+    --test_script='android/interactive_test.sh'
+    --incremental
+    --prune
+    --file_args
+    ```
+
+    You can always override them if needed. See README.bisect for more
+    details.
+
+1.  Other features: Features such as resuming, number of jobs, and device id
+    remain the same as before. See README.bisect for more details.
diff --git a/binary_search_tool/README.testing b/binary_search_tool/README.testing.md
index 6c81ab96..139dc087 100644
--- a/binary_search_tool/README.testing
+++ b/binary_search_tool/README.testing.md
@@ -1,3 +1,5 @@
+# Testing the binary search tool
+
 This file explains how to set up and run the various kinds of bisection tests.
 
 The bisection tool comes with several sets of tests which you should
@@ -5,33 +7,34 @@ run after updating any of the bisection tool scripts OR after updating
 the Android compiler wrapper (to make sure the wrapper will still work
 correctly with bisection).
 
-Before you start.
-----------------
+## Before you start.
 
 Before you can run the tests, your PYTHONPATH environment variable
 must be correct.  This means that it must include both the
-toolchain-utils directory and the binary_search_tool directory.  The
+toolchain-utils directory and the `binary_search_tool` directory.  The
 easiest way to set it is:
 
+```
 $ cd toolchain-utils
 $ export PYTHONPATH=`pwd`:${PYTHONPATH}
 $ cd binary_search_tool
 $ export PYTHONPATH=`pwd`:${PYTHONPATH}
+```
 
 
-Running the unittests.
-----------------------
+## Running the unittests.
 
 To run the basic unit tests:
 
+```
 $ cd toolchain-utils/binary_search_tool/test
 $ ./binary_search_tool_tester.py
+```
 
-Running the bisection tests, testing the compiler wrapper.
-----------------------------------------------------------
+# Running the bisection tests, testing the compiler wrapper.
 
 If you want to run the bisection tests, and test the compiler wrapper
-(to make sure the POPULATE_GOOD and POPULATE_BAD stages are still
+(to make sure the `POPULATE_GOOD` and `POPULATE_BAD` stages are still
 working properly) you can do the following.
 
 If you are testing with the ANDROID COMPILER WRAPPER, you need to to some
@@ -39,42 +42,53 @@ preliminary setup:
 
 Set up the compiler wrapper to replace GCC:
 
-    $ cd <android-root/prebuilts/clang/host/linux-x86/clang-368880/bin
-    $ cp clang gcc
-    $ whereis gcc
-    gcc: /usr/bin/gcc /usr/lib/gcc /usr/bin/X11/gcc /usr/share/man/man1/gcc.1.gz
-    $ cd /usr/bin
-    $ ls -l gcc
-    lrwxrwxrwx 1 root root 7 Feb  3 17:00 gcc -> gcc-4.8*
-    $ sudo mv gcc gcc.real
-    $ sudo ln -s <android-root>/prebuilts/clang/host/linux-x86/clang-3688880/bin/gcc gcc
+```
+$ cd <android-root/prebuilts/clang/host/linux-x86/clang-368880/bin
+$ cp clang gcc
+$ whereis gcc
+gcc: /usr/bin/gcc /usr/lib/gcc /usr/bin/X11/gcc /usr/share/man/man1/gcc.1.gz
+$ cd /usr/bin
+$ ls -l gcc
+lrwxrwxrwx 1 root root 7 Feb  3 17:00 gcc -> gcc-4.8*
+$ sudo mv gcc gcc.real
+$ sudo ln -s \
+    <android-root>/prebuilts/clang/host/linux-x86/clang-3688880/bin/gcc gcc
+```
 
 Move to the correct directory, then run the test script:
 
-    $ cd toolchain-utils/binary_search_tool
-    $ ./run_bisect_test.py
-
+```
+$ cd toolchain-utils/binary_search_tool
+$ ./run_bisect_test.py
+```
 
 If you are testing with the CHROMEOS COMPILER WRAPPER, you MUST run the
 tests from INSIDE your CHROOT (but you don't need to do any special setup):
 
-    $ cd <path-to-chromeos-root>
-    $ cros_sdk
-    $ cd ~/trunk/src/third_party/toolchain-utils
+```
+$ cd <path-to-chromeos-root>
+$ cros_sdk
+$ cd ~/trunk/src/third_party/toolchain-utils
+```
 
-    Set up your PYTHONPATH:
+Set up your `PYTHONPATH`:
 
-    $ export PYTHONPATH=`pwd`:${PYTHONPATH}
-    $ cd binary_search_tool
-    $ export PYTHONPATH=`pwd`:${PYTHONPATH}
+```
+$ export PYTHONPATH=`pwd`:${PYTHONPATH}
+$ cd binary_search_tool
+$ export PYTHONPATH=`pwd`:${PYTHONPATH}
+```
 
-    Run the test script:
+Run the test script:
 
-    $ ./run_bisect_test.py
+```
+$ ./run_bisect_test.py
+```
 
 
-Running the bisection tests, without testing the compiler wrapper.
-------------------------------------------------------------------
+## Running the bisection tests, without testing the compiler wrapper.
 
+```
 $ cd toolchain-utils/binary_search_tool
 $ ./full_bisect_test/run-test-nowrapper.sh
+```
diff --git a/binary_search_tool/android/README.android b/binary_search_tool/android/README.android
deleted file mode 100644
index 6e79d48a..00000000
--- a/binary_search_tool/android/README.android
+++ /dev/null
@@ -1,191 +0,0 @@
-
-binary_search_state.py is a general binary search triage tool that
-performs a binary search on a set of things to try to identify which
-thing or thing(s) in the set is 'bad'.  binary_search_state.py assumes
-that the user has two sets, one where everything is known to be good,
-and one which contains at least one bad item.  binary_search_state.py
-then copies items from the good and bad sets into a working set and
-tests the result (good or bad).  binary_search_state.py requires that
-a set of scripts be supplied to it for any particular job.  For more
-information on binary_search_state.py, see
-
-https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage
-
-This particular set of scripts is designed to work with
-binary_search_state.py in order to find the bad object or set of
-bad objects in an Android build. Furthermore, it can also help find
-the bad compiler pass and transformation when building that bad object.
-
-
-QUICKSTART:
-
-After setting up your 2 build trees (see Prerequisites section), do the
-following:
-
- - Decide which test script to use (boot_test.sh or
-   interactive_test.sh)
- - Get the serial number for the Android device you will use for testing.
- - Run the following:
-
-   $ cd <android_src>
-   $ source build/envsetup.sh
-   $ lunch <android_device_lunch_combo>
-   $ cd <path_to_toolchain_utils>/binary_search_tool/
-   $ NUM_JOBS=10 ANDROID_SERIAL=<device_serial> \
-         ./android/setup.sh <android_src>
-
-   If you chose the boot test, then:
-   TEST_SCRIPT=android/boot_test.sh
-
-   If you chose the interactive test, then:
-   TEST_SCRIPT=android/interactive_test.sh
-
-   Finally, run the binary search tool:
-
-   $ python ./binary_search_state.py \
-       --get_initial_items=android/get_initial_items.sh \
-       --switch_to_good=android/switch_to_good.sh \
-       --switch_to_bad=android/switch_to_bad.sh \
-       --test_setup_script=android/test_setup.sh \
-       --test_script=$TEST_SCRIPT \
-       --file_args \
-       --prune
-
-   Once you have completely finished doing the binary search/triage,
-   run the cleanup script:
-
-   $ android/cleanup.sh
-
-
-
-FILES AND SCRIPTS:
-
-  Check the header comments for each script for more in depth documentation.
-
-  boot_test.sh - One of two possible test scripts used to determine
-                 if the Android image built from the objects is good
-                 or bad. This script tests to see if the image
-                 booted, and requires no user intervention.
-
-  cleanup.sh - This is called after the binary search tool completes. This
-               script will clean up the common.sh file generated by setup.sh
-
-  get_initial_items.sh - This script is used to determine all Android objects
-                         that will be bisected.
-
-  test_setup.sh - This script will build and flash your image to the
-                  Android device. If the flash fails, this script will
-                  help the user troubleshoot by trying to flash again or
-                  by asking the user to manually flash it.
-
-  interactive_test.sh - One of two possible scripts used to determine
-                        if the Android image built from the objects
-                        is good or bad.  This script requires user
-                        interaction to determine if the image is
-                        good or bad.
-
-  setup.sh - This is the first script the user should call, after
-             taking care of the prerequisites.  It sets up the
-             environment appropriately for running the Android
-             object binary search triage, and it generates the
-             necessary common script (see below).
-
-  switch_to_bad.sh - This script is used to link objects from the
-                     'bad' build tree into the work area.
-
-  switch_to_good.sh - This script is used to link objects from the
-                      'good' build tree into the work area.
-
-  generate_cmd.sh - This script will generate another temporary script, which
-                    contains the command line options to build the bad object
-                    file again with pass/transformation level limit.
-
-
-GENERATED SCRIPTS:
-
-  common.sh  - contains basic environment variable definitions for
-               this binary search triage session.
-
-ASSUMPTIONS:
-
-- There are two different Android builds, for the same board/lunch combo with
-  the same set of generated object files.  One build creates a good working
-  Android image and the other does not.
-
-- The toolchain bug you are tracking down is not related to the linker. If the
-  linker is broken or generates bad code, this tool is unlikely to help you.
-
-
-PREREQUISITES FOR USING THESE SCRIPTS:
-
-  Step 1: Decide where to store each build tree
-    By default, each build tree is stored in "~/ANDROID_BISECT". However you
-    can override this by exporting BISECT_DIR set to whatever directory you
-    please. Keep in mind these build trees take dozens of gigabytes each.
-
-  Step 2: Setup your android build environment
-    1. `cd <android_src>`
-    2. `source build/envsetup.sh`
-    3. `lunch <android_device_lunch_combo>`
-
-  Step 3: Populate the good build tree
-    1. `make clean`
-    2. `export BISECT_STAGE=POPULATE_GOOD`
-    3. Install your "good" toolchain in Android, this will most likely be
-       the toolchain that comes preinstalled with the Android source.
-    4. Build all of Android: `make -j10`. The "-j" parameter depends on how
-       many cores your machine has. See Android documentation for more details.
-
-  Step 4: Populate the bad build tree
-    1. `make clean`
-    2. `export BISECT_STAGE=POPULATE_BAD`
-    3. Install your "bad" toolchain in Android.
-    4. Build all of Android again.
-
-  Step 5: Run the android setup script
-    1. `cd <path_to_toolchain_utils>/binary_search_tool/`
-    2. `NUM_JOBS=<jobs> ANDROID_SERIAL=<android_serial_num> \
-        android/setup.sh <android_src>`
-
-   WARNING: It's important that you leave the full "out/" directory in your
-            Android source alone after Step 4. The binary search tool will
-            use this directory as a skeleton to build each test image while
-            triaging.
-
-USING THESE SCRIPTS FOR BINARY TRIAGE OF OBJECTS:
-
-To use these scripts, you must first run setup.sh, passing it the path to your
-Android source directory. setup.sh will do the following:
-
-   - Verify that your build trees are set up correctly (with good, bad).
-   - Verify that each build tree has the same contents.
-   - Verify that the android build environment (lunch, etc.) are setup in your
-     current shell.
-   - Create the common.sh file that the other scripts passed to the
-     binary triage tool will need.
-
-
-This set of scripts comes with two alternate test scripts.  One test
-script, boot_test.sh, just checks to make sure that the image
-booted (wait for device to boot to home screen) and assumes that is enough.
-The other test script, interactive_test.sh, is interactive and asks YOU
-to tell it whether the image on the android device is ok or not (it
-prompts you and waits for a response).
-
-
-Once you have run setup.sh (and decided which test script you
-want to use) run the binary triage tool using these scripts to
-isolate/identify the bad object:
-
-./binary_search_state.py \
- --get_initial_items=android/get_initial_items.sh \
- --switch_to_good=android/switch_to_good.sh \
- --switch_to_bad=android/switch_to_bad.sh \
- --test_setup_script=android/test_setup.sh \
- --test_script=android/boot_test.sh \  # could use interactive_test.sh instead
- --prune
-
-
-After you have finished running the tool and have identified the bad
-object(s), you will want to run the cleanup script (android/cleanup.sh).
-
diff --git a/binary_search_tool/android/README.android.md b/binary_search_tool/android/README.android.md
new file mode 100644
index 00000000..9445dcbb
--- /dev/null
+++ b/binary_search_tool/android/README.android.md
@@ -0,0 +1,209 @@
+# Android's binary search tool
+
+`binary_search_state.py` is a general binary search triage tool that
+performs a binary search on a set of things to try to identify which
+thing or thing(s) in the set is 'bad'.  `binary_search_state.py` assumes
+that the user has two sets, one where everything is known to be good,
+and one which contains at least one bad item.  `binary_search_state.py`
+then copies items from the good and bad sets into a working set and
+tests the result (good or bad).  `binary_search_state.py` requires that
+a set of scripts be supplied to it for any particular job.  For more
+information on `binary_search_state.py`, see
+
+https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage
+
+This particular set of scripts is designed to work with
+`binary_search_state.py` in order to find the bad object or set of
+bad objects in an Android build. Furthermore, it can also help find
+the bad compiler pass and transformation when building that bad object.
+
+
+## QUICKSTART
+
+After setting up your 2 build trees (see Prerequisites section), do the
+following:
+
+-   Decide which test script to use (`boot_test.sh` or
+    `interactive_test.sh`)
+-   Get the serial number for the Android device you will use for testing.
+-   Run the following:
+
+    ```
+    $ cd <android_src>
+    $ source build/envsetup.sh
+    $ lunch <android_device_lunch_combo>
+    $ cd <path_to_toolchain_utils>/binary_search_tool/
+    $ NUM_JOBS=10 ANDROID_SERIAL=<device_serial> \
+          ./android/setup.sh <android_src>
+    ```
+
+    If you chose the boot test, then:
+
+    ```
+    TEST_SCRIPT=android/boot_test.sh
+    ```
+
+    If you chose the interactive test, then:
+
+    ```
+    TEST_SCRIPT=android/interactive_test.sh
+    ```
+
+    Finally, run the binary search tool:
+
+    ```
+    $ python ./binary_search_state.py \
+        --get_initial_items=android/get_initial_items.sh \
+        --switch_to_good=android/switch_to_good.sh \
+        --switch_to_bad=android/switch_to_bad.sh \
+        --test_setup_script=android/test_setup.sh \
+        --test_script=$TEST_SCRIPT \
+        --file_args \
+        --prune
+    ```
+
+    Once you have completely finished doing the binary search/triage,
+    run the cleanup script:
+
+    ```
+    $ android/cleanup.sh
+    ```
+
+
+## FILES AND SCRIPTS
+
+Check the header comments for each script for more in depth documentation.
+
+`boot_test.sh` - One of two possible test scripts used to determine
+                 if the Android image built from the objects is good
+                 or bad. This script tests to see if the image
+                 booted, and requires no user intervention.
+
+`cleanup.sh` - This is called after the binary search tool completes. This
+               script will clean up the common.sh file generated by setup.sh
+
+`get_initial_items.sh` - This script is used to determine all Android objects
+                         that will be bisected.
+
+`test_setup.sh` - This script will build and flash your image to the
+                  Android device. If the flash fails, this script will
+                  help the user troubleshoot by trying to flash again or
+                  by asking the user to manually flash it.
+
+`interactive_test.sh` - One of two possible scripts used to determine
+                        if the Android image built from the objects
+                        is good or bad.  This script requires user
+                        interaction to determine if the image is
+                        good or bad.
+
+`setup.sh` - This is the first script the user should call, after
+             taking care of the prerequisites.  It sets up the
+             environment appropriately for running the Android
+             object binary search triage, and it generates the
+             necessary common script (see below).
+
+`switch_to_bad.sh` - This script is used to link objects from the
+                     'bad' build tree into the work area.
+
+`switch_to_good.sh` - This script is used to link objects from the
+                      'good' build tree into the work area.
+
+`generate_cmd.sh` - This script will generate another temporary script, which
+                    contains the command line options to build the bad object
+                    file again with pass/transformation level limit.
+
+
+## GENERATED SCRIPTS
+
+`common.sh` - contains basic environment variable definitions for
+              this binary search triage session.
+
+## ASSUMPTIONS
+
+-   There are two different Android builds, for the same board/lunch combo with
+    the same set of generated object files.  One build creates a good working
+    Android image and the other does not.
+
+-   The toolchain bug you are tracking down is not related to the linker. If the
+    linker is broken or generates bad code, this tool is unlikely to help you.
+
+
+PREREQUISITES FOR USING THESE SCRIPTS:
+
+1.  Decide where to store each build tree
+    By default, each build tree is stored in `~/ANDROID_BISECT`. However you
+    can override this by exporting `BISECT_DIR` set to whatever directory you
+    please. Keep in mind these build trees take dozens of gigabytes each.
+
+2.  Setup your android build environment
+
+    ```
+    cd <android_src>
+    source build/envsetup.sh
+    lunch <android_device_lunch_combo>
+    ```
+
+3.  Populate the good build tree
+
+    1.  `make clean`
+    2.  `export BISECT_STAGE=POPULATE_GOOD`
+    3.  Install your "good" toolchain in Android, this will most likely be
+        the toolchain that comes preinstalled with the Android source.
+    4.  Build all of Android: `make -j10`. The "-j" parameter depends on how
+        many cores your machine has. See Android documentation for more details.
+
+4.  Populate the bad build tree
+
+    1.  `make clean`
+    2.  `export BISECT_STAGE=POPULATE_BAD`
+    3.  Install your "bad" toolchain in Android.
+    4.  Build all of Android again.
+
+5.  Run the android setup script
+
+    1.  `cd <path_to_toolchain_utils>/binary_search_tool/`
+    2.  `NUM_JOBS=<jobs> ANDROID_SERIAL=<android_serial_num>
+        android/setup.sh <android_src>`
+
+WARNING: It's important that you leave the full `out/` directory in your
+         Android source alone after Step 4. The binary search tool will
+         use this directory as a skeleton to build each test image while
+         triaging.
+
+## USING THESE SCRIPTS FOR BINARY TRIAGE OF OBJECTS
+
+To use these scripts, you must first run setup.sh, passing it the path to your
+Android source directory. setup.sh will do the following:
+
+-   Verify that your build trees are set up correctly (with good, bad).
+-   Verify that each build tree has the same contents.
+-   Verify that the android build environment (lunch, etc.) are setup in your
+    current shell.
+-   Create the common.sh file that the other scripts passed to the
+    binary triage tool will need.
+
+
+This set of scripts comes with two alternate test scripts.  One test
+script, `boot_test.sh`, just checks to make sure that the image
+booted (wait for device to boot to home screen) and assumes that is enough.
+The other test script, `interactive_test.sh`, is interactive and asks YOU
+to tell it whether the image on the android device is ok or not (it
+prompts you and waits for a response).
+
+
+Once you have run `setup.sh` (and decided which test script you
+want to use) run the binary triage tool using these scripts to
+isolate/identify the bad object:
+
+```
+./binary_search_state.py \
+   --get_initial_items=android/get_initial_items.sh \
+   --switch_to_good=android/switch_to_good.sh \
+   --switch_to_bad=android/switch_to_bad.sh \
+   --test_setup_script=android/test_setup.sh \
+   --test_script=android/boot_test.sh \  # could use interactive_test.sh instead
+   --prune
+```
+
+After you have finished running the tool and have identified the bad
+object(s), you will want to run the cleanup script (android/cleanup.sh).
diff --git a/binary_search_tool/cros_pkg/README.cros_pkg_triage b/binary_search_tool/cros_pkg/README.cros_pkg_triage
deleted file mode 100644
index 5e285008..00000000
--- a/binary_search_tool/cros_pkg/README.cros_pkg_triage
+++ /dev/null
@@ -1,185 +0,0 @@
-
-binary_search_state.py is a general binary search triage tool that
-performs a binary search on a set of things to try to identify which
-thing or thing(s) in the set is 'bad'.  binary_search_state.py assumes
-that the user has two sets, one where everything is known to be good,
-ane one which contains at least one bad item.  binary_search_state.py
-then copies items from the good and bad sets into a working set and
-tests the result (good or bad).  binary_search_state.py requires that
-a set of scripts be supplied to it for any particular job.  For more
-information on binary_search_state.py, see
-
-https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage
-
-This particular set of scripts is designed to work wtih
-binary_search_state.py in order to find the bad package or set of
-packages in a ChromeOS build.
-
-
-QUICKSTART:
-
-After setting up your 3 build trees (see Prerequisites section), do the
-following:
-
- - Decide which test script to use (boot_test.sh or
-   interactive_test.sh)
- - Get the IP name or address of the chromebook you will use for testing.
- - Do the following inside your chroot:
-
-   $ cd ~/trunk/src/third_party/toolchain_utils/binary_search_tool
-   $ ./cros_pkg/setup.sh <board-to-test> <IP-name-or-address-of-chromebook>
-
-   If you chose the boot test, then:
-
-   $ python ./binary_search_state.py \
-       --get_initial_items=cros_pkg/get_initial_items.sh \
-       --switch_to_good=cros_pkg/switch_to_good.sh \
-       --switch_to_bad=cros_pkg/switch_to_bad.sh \
-       --test_setup_script=cros_pkg/test_setup.sh \
-       --test_script=cros_pkg/boot_test.sh \
-       --file_args \
-       --prune
-
-   Otherwise, if you chose the interactive test, then:
-
-   $ python ./binary_search_state.py \
-       --get_initial_items=cros_pkg/get_initial_items.sh \
-       --switch_to_good=cros_pkg/switch_to_good.sh \
-       --switch_to_bad=cros_pkg/switch_to_bad.sh \
-       --test_setup_script=cros_pkg/test_setup.sh \
-       --test_script=cros_pkg/interactive_test.sh \
-       --file_args \
-       --prune
-
-   Once you have completely finished doing the binary search/triage,
-   run the genereated cleanup script, to restore your chroot to the state
-   it was in before you ran the setup.sh script:
-
-   $ cros_pkg/${BOARD}_cleanup.sh
-
-
-
-FILES AND SCRIPTS:
-
-  boot_test.sh - One of two possible test scripts used to determine
-                 if the ChromeOS image built from the packages is good
-                 or bad.  This script tests to see if the image
-                 booted, and requires no user intervention.
-
-  create_cleanup_script.py - This is called by setup.sh, to
-                             generate ${BOARD}_cleanup.sh,
-                             which is supposed to be run by the user
-                             after the binary search triage process is
-                             finished, to undo the changes made by
-                             setup.sh and return everything
-                             to its original state.
-
-  get_initial_items.sh - This script is used to determine the current
-                         set of ChromeOS packages.
-
-  test_setup.sh - This script will build and flash your image to the
-                  remote machine. If the flash fails, this script will
-                  help the user troubleshoot by flashing through usb or
-                  by retrying the flash over ethernet.
-
-  interactive_test.sh - One of two possible scripts used to determine
-                        if the ChromeOS image built from the packages
-                        is good or bad.  This script requires user
-                        interaction to determine if the image is
-                        good or bad.
-
-  setup.sh - This is the first script the user should call, after
-             taking care of the prerequisites.  It sets up the
-             environment appropriately for running the ChromeOS
-             package binary search triage, and it generates two
-             necessary scripts (see below).
-
-  switch_to_bad.sh - This script is used to copy packages from the
-                     'bad' build tree into the work area.
-
-  switch_to_good.sh - This script is used to copy packages from the
-                      good' build tree into the work area.
-
-
-GENERATED SCRIPTS:
-
-  common.sh  - contains basic environment variable definitions for
-               this binary search triage session.
-
-  ${BOARD}_cleanup.sh - script to undo all the changes made by
-                        running setup.sh, and returning
-                        everything to its original state. The user
-                        should manually run this script once the
-                        binary search triage process is over.
-
-ASSUMPTIONS:
-
-- There are two different ChromeOS builds, for the same board, with the
-  same set of ChromeOS packages.  One build creates a good working ChromeOS
-  image and the other does not.
-
-- You have saved the complete build trees for both the good and bad builds.
-
-
-PREREQUISITES FOR USING THESE SCRIPTS (inside the chroot):
-
-- The "good" build tree, for the board, is in /build/${board}.good
-  (e.g. /build/lumpy.good or /build/daisy.good).
-
-- The "bad" build tree is in /build/${board}.bad
-  (e.g. /build/lumpy.bad or /build/daisy.bad).
-
-- You made a complete copy of the "bad" build tree , and put it in
-  /build/${board}.work (e.g. /build/lumpy.work or /build/daisy.work.
-  The easiest way to do this is to use something similar to the
-  following set of commands (this example assumes the board is
-  'lumpy'):
-
-   $ cd /build
-   $ sudo tar -cvf lumpy.bad.tar lumpy.bad
-   $ sudo mv lumpy.bad lumpy.work
-   $ sudo tar -xvf lumpy.bad.tar
-
-
-USING THESE SCRIPTS FOR BINARY TRIAGE OF PACKAGES:
-
-To use these scripts, you must first run setup.sh, passing it two
-arguments (in order): the board for which you are building the image;
-and the name or ip address of the chromebook you want to use for
-testing your chromeos images.  setup.sh will do the following:
-
-   - Verify that your build trees are set up correctly (with good, bad
-     and work).
-   - Create a soft link for /build/${board} pointing to the work build
-     tree.
-   - Create the common.sh file that the other scripts passed to the
-     binary triage tool will need.
-   - Create a cleanup script, ${board}_cleanup.sh, for you to
-     run after you are done with the binary triages, to undo all of these
-     various changes that setup.sh did.
-
-
-This set of scripts comes with two alternate test scripts.  One test
-script, boot_test.sh, just checks to make sure that the image
-booted (i.e. responds to ping) and assumes that is enough.  The other
-test script, interactive_test.sh, is interactive and asks YOU
-to tell it whether the image on the chromebook is ok or not (it
-prompts you and waits for a response).
-
-
-Once you have run setup.sh (and decided which test script you
-want to use) run the binary triage tool using these scripts to
-isolate/identify the bad package:
-
-~/trunk/src/third_party/toolchain_utils/binary_search_tool/binary_search_state.py \
- --get_initial_items=cros_pkg/get_initial_items.sh \
- --switch_to_good=cros_pkg/switch_to_good.sh \
- --switch_to_bad=cros_pkg/switch_to_bad.sh \
- --test_setup_script=cros_pkg/test_setup.sh \
- --test_script=cros_pkg/boots_test.sh \  # could use interactive_test.sh instead
- --prune
-
-
-After you have finished running the tool and have identified the bad
-package(s), you will want to run the cleanup script that setup.sh
-generated (cros_pkg/${BOARD}_cleanup.sh).
diff --git a/binary_search_tool/cros_pkg/README.cros_pkg_triage.md b/binary_search_tool/cros_pkg/README.cros_pkg_triage.md
new file mode 100644
index 00000000..17121dd7
--- /dev/null
+++ b/binary_search_tool/cros_pkg/README.cros_pkg_triage.md
@@ -0,0 +1,193 @@
+# CrOS's binary search tool
+
+`binary_search_state.py` is a general binary search triage tool that
+performs a binary search on a set of things to try to identify which
+thing or thing(s) in the set is 'bad'.  `binary_search_state.py` assumes
+that the user has two sets, one where everything is known to be good,
+ane one which contains at least one bad item.  `binary_search_state.py`
+then copies items from the good and bad sets into a working set and
+tests the result (good or bad).  `binary_search_state.py` requires that
+a set of scripts be supplied to it for any particular job.  For more
+information on `binary_search_state.py`, see
+
+https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage
+
+This particular set of scripts is designed to work wtih
+`binary_search_state.py` in order to find the bad package or set of
+packages in a ChromeOS build.
+
+
+## QUICKSTART
+
+After setting up your 3 build trees (see Prerequisites section), do the
+following:
+
+-   Decide which test script to use (`boot_test.sh` or
+    `interactive_test.sh`)
+-   Get the IP name or address of the chromebook you will use for testing.
+-   Do the following inside your chroot:
+
+    ```
+    $ cd ~/trunk/src/third_party/toolchain_utils/binary_search_tool
+    $ ./cros_pkg/setup.sh <board-to-test> <IP-name-or-address-of-chromebook>
+    ```
+
+    If you chose the boot test, then:
+
+    ```
+    $ python ./binary_search_state.py \
+        --get_initial_items=cros_pkg/get_initial_items.sh \
+        --switch_to_good=cros_pkg/switch_to_good.sh \
+        --switch_to_bad=cros_pkg/switch_to_bad.sh \
+        --test_setup_script=cros_pkg/test_setup.sh \
+        --test_script=cros_pkg/boot_test.sh \
+        --file_args \
+        --prune
+    ```
+
+    Otherwise, if you chose the interactive test, then:
+
+    ```
+    $ python ./binary_search_state.py \
+        --get_initial_items=cros_pkg/get_initial_items.sh \
+        --switch_to_good=cros_pkg/switch_to_good.sh \
+        --switch_to_bad=cros_pkg/switch_to_bad.sh \
+        --test_setup_script=cros_pkg/test_setup.sh \
+        --test_script=cros_pkg/interactive_test.sh \
+        --file_args \
+        --prune
+    ```
+
+    Once you have completely finished doing the binary search/triage,
+    run the genereated cleanup script, to restore your chroot to the state
+    it was in before you ran the `setup.sh` script:
+
+    ```
+    $ cros_pkg/${BOARD}_cleanup.sh
+    ```
+
+
+## FILES AND SCRIPTS
+
+`boot_test.sh` - One of two possible test scripts used to determine
+                 if the ChromeOS image built from the packages is good
+                 or bad.  This script tests to see if the image
+                 booted, and requires no user intervention.
+
+`create_cleanup_script.py` - This is called by setup.sh, to
+                             generate ${BOARD}_cleanup.sh,
+                             which is supposed to be run by the user
+                             after the binary search triage process is
+                             finished, to undo the changes made by
+                             setup.sh and return everything
+                             to its original state.
+
+`get_initial_items.sh` - This script is used to determine the current
+                         set of ChromeOS packages.
+
+`test_setup.sh` - This script will build and flash your image to the
+                  remote machine. If the flash fails, this script will
+                  help the user troubleshoot by flashing through usb or
+                  by retrying the flash over ethernet.
+
+`interactive_test.sh` - One of two possible scripts used to determine
+                        if the ChromeOS image built from the packages
+                        is good or bad.  This script requires user
+                        interaction to determine if the image is
+                        good or bad.
+
+`setup.sh` - This is the first script the user should call, after
+             taking care of the prerequisites.  It sets up the
+             environment appropriately for running the ChromeOS
+             package binary search triage, and it generates two
+             necessary scripts (see below).
+
+`switch_to_bad.sh` - This script is used to copy packages from the
+                     'bad' build tree into the work area.
+
+`switch_to_good.sh` - This script is used to copy packages from the
+                      'good' build tree into the work area.
+
+
+## GENERATED SCRIPTS
+
+`common.sh`  - contains basic environment variable definitions for
+               this binary search triage session.
+
+`${BOARD}_cleanup.sh` - script to undo all the changes made by
+                        running setup.sh, and returning
+                        everything to its original state. The user
+                        should manually run this script once the
+                        binary search triage process is over.
+
+## ASSUMPTIONS
+
+-   There are two different ChromeOS builds, for the same board, with the
+    same set of ChromeOS packages.  One build creates a good working ChromeOS
+    image and the other does not.
+
+-   You have saved the complete build trees for both the good and bad builds.
+
+
+## PREREQUISITES FOR USING THESE SCRIPTS (inside the chroot)
+
+-   The "good" build tree, for the board, is in /build/${board}.good
+    (e.g. /build/lumpy.good or /build/daisy.good).
+
+-   The "bad" build tree is in /build/${board}.bad
+    (e.g. /build/lumpy.bad or /build/daisy.bad).
+
+-   You made a complete copy of the "bad" build tree , and put it in
+    /build/${board}.work (e.g. /build/lumpy.work or /build/daisy.work.
+    The easiest way to do this is to use something similar to the
+    following set of commands (this example assumes the board is
+    'lumpy'):
+
+    ```
+    $ cd /build
+    $ sudo tar -cvf lumpy.bad.tar lumpy.bad
+    $ sudo mv lumpy.bad lumpy.work
+    $ sudo tar -xvf lumpy.bad.tar
+    ```
+
+
+## USING THESE SCRIPTS FOR BINARY TRIAGE OF PACKAGES
+
+To use these scripts, you must first run setup.sh, passing it two
+arguments (in order): the board for which you are building the image;
+and the name or ip address of the chromebook you want to use for
+testing your chromeos images.  setup.sh will do the following:
+
+-   Verify that your build trees are set up correctly (with good, bad and work).
+-   Create a soft link for /build/${board} pointing to the work build tree.
+-   Create the common.sh file that the other scripts passed to the binary triage
+    tool will need.
+-   Create a cleanup script, ${board}_cleanup.sh, for you to run after you are
+    done with the binary triages, to undo all of these various changes that
+    setup.sh did.
+
+This set of scripts comes with two alternate test scripts.  One test
+script, `boot_test.sh`, just checks to make sure that the image
+booted (i.e. responds to ping) and assumes that is enough.  The other
+test script, `interactive_test.sh`, is interactive and asks YOU
+to tell it whether the image on the chromebook is ok or not (it
+prompts you and waits for a response).
+
+
+Once you have run `setup.sh` (and decided which test script you
+want to use) run the binary triage tool using these scripts to
+isolate/identify the bad package:
+
+```
+~/trunk/src/third_party/toolchain_utils/binary_search_tool/binary_search_state.py \
+    --get_initial_items=cros_pkg/get_initial_items.sh \
+    --switch_to_good=cros_pkg/switch_to_good.sh \
+    --switch_to_bad=cros_pkg/switch_to_bad.sh \
+    --test_setup_script=cros_pkg/test_setup.sh \
+    --test_script=cros_pkg/boots_test.sh \  # could use interactive_test.sh instead
+    --prune
+```
+
+After you have finished running the tool and have identified the bad
+package(s), you will want to run the cleanup script that `setup.sh`
+generated (`cros_pkg/${BOARD}_cleanup.sh`).
diff --git a/binary_search_tool/ndk/README b/binary_search_tool/ndk/README
deleted file mode 100644
index 324d1391..00000000
--- a/binary_search_tool/ndk/README
+++ /dev/null
@@ -1,84 +0,0 @@
-
-This is an example bisection for an NDK build system. This example specifically
-bisects the sample NDK Teapot app. All steps (setup and otherwise) for bisection
-can be found in DO_BISECTION.sh. This shell script is meant to show the process
-required to bisect a compiler problem in an arbitrary NDK app build system.
-
-There are three necessary setup steps to run this example:
-
-  1. Install the NDK (known to work with r12b)
-    a. See here for NDK: https://developer.android.com/ndk/index.html
-    b. Go here for older NDK downloads: https://github.com/android-ndk/ndk/wiki
-
-  2. Install the compiler wrapper provided with this repo. See
-     compiler_wrapper.py for more details.
-    a. Essentially you must go into the NDK source (or where you build system
-       stores its toolchain), rename your compilers to <compiler>.real, and
-       create a symlink pointing to compiler_wrapper.py named <compiler>
-       (where your compiler used to be).
-    b. If you're using the toolchains that come with the NDK they live at:
-         <ndk_path>/toolchains/<arch>/prebuilt/<host>/bin
-       example:
-         <ndk_path>/toolchains/llvm/prebuilt/linux-x86_64/bin/clang
-
-  3. Plug in an Arm7 compatible Android device with usb debugging enabled.
-    a. This bisection example was tested with a Nexus 5X
-    b. It should be relatively simple to change the example to work with other
-       types of devices. Just change the scripts, and change PATCH1 to use a
-       different build flavor (like x86). See below for more details.
-
-This example contains two patches:
-
-  PATCH1 - This is the necessary changes to the build system to make the
-  bisection easier. More specifically, it adds an arm7 build flavor to gradle.
-  By default, this project will build objects for all possible architectures and
-  package them into one big apk. These object files meant for another
-  architecture just sit there and don't actually execute. By adding a build
-  flavor for arm7, our compiler wrapper won't try to bisect object files meant
-  for another device.
-
-  PATCH2 - This patch is what inserts the "compiler error". This is a simple
-  nullptr error in one of the source files, but it is meant to mimic bad code
-  generation. The result of the error is the app simply crashes immediately
-  after starting.
-
-Using another device architecture:
-
-  If we want to bisect for an x86-64 device we first need to provide a arch
-  specific build flavor in our app/build.gradle file:
-
-      create("x86-64") {
-        ndk.abiFilters.add("x86_64")
-      }
-
-  We want to add this under the same "productFlavors" section that our arm7
-  build flavor is in (see PATCH1). Now we should have the "installx86-64Debug"
-  task in our build system. We can use this to build and install an x86-64
-  version of our app.
-
-  Now we want to change our test_setup.sh script to run our new gradle task:
-    ./gradlew installx86-64Debug
-
-  Keep in mind, these specific build flavors are not required. If your build
-  system makes these device specific builds difficult to implement, the
-  bisection tool will function perfectly fine without them. However, the
-  downside of not having targetting a single architecture is the bisection will
-  take longer (as it will need to search across more object files).
-
-Additional Documentation:
-  These are internal Google documents, if you are a developer external to
-  Google please ask whoever gave you this sample for access or copies to the
-  documentation. If you cannot gain access, the various READMEs paired with the
-  bisector should help you.
-
-  * Ahmad's original presentation:
-    https://goto.google.com/zxdfyi
-
-  * Bisection tool update design doc:
-    https://goto.google.com/zcwei
-
-  * Bisection tool webpage:
-    https://goto.google.com/ruwpyi
-
-  * Compiler wrapper webpage:
-    https://goto.google.com/xossn
diff --git a/binary_search_tool/ndk/README.md b/binary_search_tool/ndk/README.md
new file mode 100644
index 00000000..e41311a1
--- /dev/null
+++ b/binary_search_tool/ndk/README.md
@@ -0,0 +1,89 @@
+# NDK Bisection tool
+
+This is an example bisection for an NDK build system. This example specifically
+bisects the sample NDK Teapot app. All steps (setup and otherwise) for bisection
+can be found in `DO_BISECTION.sh`. This shell script is meant to show the
+process required to bisect a compiler problem in an arbitrary NDK app build
+system.
+
+There are three necessary setup steps to run this example:
+
+1.  Install the NDK (known to work with r12b)
+
+    1. See here for NDK: https://developer.android.com/ndk/index.html
+    2. Go here for older NDK downloads: https://github.com/android-ndk/ndk/wiki
+
+1.  Install the compiler wrapper provided with this repo. See
+    compiler_wrapper.py for more details.
+
+    1.  Essentially you must go into the NDK source (or where you build system
+        stores its toolchain), rename your compilers to <compiler>.real, and
+        create a symlink pointing to compiler_wrapper.py named <compiler>
+        (where your compiler used to be).
+
+    2.  If you're using the toolchains that come with the NDK they live at:
+        `<ndk_path>/toolchains/<arch>/prebuilt/<host>/bin`
+        example:
+        `<ndk_path>/toolchains/llvm/prebuilt/linux-x86_64/bin/clang`
+
+1.  Plug in an Arm7 compatible Android device with usb debugging enabled.
+
+    1. This bisection example was tested with a Nexus 5X
+
+    2. It should be relatively simple to change the example to work with other
+       types of devices. Just change the scripts, and change PATCH1 to use a
+       different build flavor (like x86). See below for more details.
+
+This example contains two patches:
+
+`PATCH1` - This is the necessary changes to the build system to make the
+bisection easier. More specifically, it adds an arm7 build flavor to gradle.
+By default, this project will build objects for all possible architectures and
+package them into one big apk. These object files meant for another
+architecture just sit there and don't actually execute. By adding a build
+flavor for arm7, our compiler wrapper won't try to bisect object files meant
+for another device.
+
+`PATCH2` - This patch is what inserts the "compiler error". This is a simple
+nullptr error in one of the source files, but it is meant to mimic bad code
+generation. The result of the error is the app simply crashes immediately
+after starting.
+
+## Using another device architecture
+
+If we want to bisect for an x86-64 device we first need to provide a arch
+specific build flavor in our app/build.gradle file:
+
+```
+create("x86-64") {
+  ndk.abiFilters.add("x86_64")
+}
+```
+
+We want to add this under the same "productFlavors" section that our arm7
+build flavor is in (see PATCH1). Now we should have the "installx86-64Debug"
+task in our build system. We can use this to build and install an x86-64
+version of our app.
+
+Now we want to change our `test_setup.sh` script to run our new gradle task:
+```
+./gradlew installx86-64Debug
+```
+
+Keep in mind, these specific build flavors are not required. If your build
+system makes these device specific builds difficult to implement, the
+bisection tool will function perfectly fine without them. However, the
+downside of not having targetting a single architecture is the bisection will
+take longer (as it will need to search across more object files).
+
+## Additional Documentation
+
+These are internal Google documents, if you are a developer external to
+Google please ask whoever gave you this sample for access or copies to the
+documentation. If you cannot gain access, the various READMEs paired with the
+bisector should help you.
+
+* Ahmad's original presentation: https://goto.google.com/zxdfyi
+* Bisection tool update design doc: https://goto.google.com/zcwei
+* Bisection tool webpage: https://goto.google.com/ruwpyi
+* Compiler wrapper webpage: https://goto.google.com/xossn
diff --git a/binary_search_tool/sysroot_wrapper/README b/binary_search_tool/sysroot_wrapper/README
deleted file mode 100644
index 599d700d..00000000
--- a/binary_search_tool/sysroot_wrapper/README
+++ /dev/null
@@ -1,28 +0,0 @@
-This is a set of scripts to use when triaging compiler problem by using
-the bisecting functionality included in the sysroot_wrapper.hardened.
-The only script that you need to create for your triaging problem is the
-test_script.sh (The ones in this directory are here only as an example).
-
-Before running the binary searcher tool you will need to run the setup script:
-
-./sysroot_wrapper/setup.sh ${board} ${remote_ip} ${package}
-
-This setup script will ensure your $BISECT_DIR is properly populated and
-generate a common variable script for the convenience of the scripts in
-./sysroot_wrapper
-
-To run the binary searcher tool with these scripts, execute it like this:
-
-./binary_search_state.py --get_initial_items=./sysroot_wrapper/get_initial_items.sh --switch_to_good=./sysroot_wrapper/switch_to_good.sh --switch_to_bad=./sysroot_wrapper/switch_to_bad.sh --test_script=./sysroot_wrapper/test_script.sh --noincremental --file_args 2>&1 | tee /tmp/binary_search.log
-
-Finally once done you will want to run the cleanup script:
-
-./sysroot_wrapper/cleanup.sh
-
-For more information on how to use the sysroot_wrapper to do object file
-triaging see:
-
-https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/bisecting-compiler-problems
-
-
-
diff --git a/binary_search_tool/sysroot_wrapper/README.md b/binary_search_tool/sysroot_wrapper/README.md
new file mode 100644
index 00000000..89904a0b
--- /dev/null
+++ b/binary_search_tool/sysroot_wrapper/README.md
@@ -0,0 +1,35 @@
+# Sysroot wrapper
+
+This is a set of scripts to use when triaging compiler problem by using
+the bisecting functionality included in the `sysroot_wrapper.hardened`.
+The only script that you need to create for your triaging problem is the
+`test_script.sh` (The ones in this directory are here only as an example).
+
+Before running the binary searcher tool you will need to run the setup script:
+
+```
+./sysroot_wrapper/setup.sh ${board} ${remote_ip} ${package}
+```
+
+This setup script will ensure your `$BISECT_DIR` is properly populated and
+generate a common variable script for the convenience of the scripts in
+`./sysroot_wrapper`
+
+To run the binary searcher tool with these scripts, execute it like this:
+
+```
+./binary_search_state.py \
+  --get_initial_items=./sysroot_wrapper/get_initial_items.sh \
+  --switch_to_good=./sysroot_wrapper/switch_to_good.sh \
+  --switch_to_bad=./sysroot_wrapper/switch_to_bad.sh \
+  --test_script=./sysroot_wrapper/test_script.sh \
+  --noincremental \
+  --file_args \
+  2>&1 | tee /tmp/binary_search.log
+```
+
+Finally once done you will want to run the cleanup script:
+`./sysroot_wrapper/cleanup.sh`
+
+For more information on how to use the `sysroot_wrapper` to do object file
+triaging see: https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/bisecting-compiler-problems