Fix bug in binary_size script and cosmetic updates

tools/binary_size/README.txt

 ================================================================================
               __________  .__
               \______   \ |__|   ____   _____    _______   ___.__.
                |    |  _/ |  |  /    \  \__  \   \_  __ \ <   |  |
                |    |   \ |  | |   |  \  / __ \_  |  | \/  \___  |
                |______  / |__| |___|  / (____  /  |__|     / ____|
                       \/            \/       \/            \/
     _________ .__                        ___________                   .__
    /   _____/ |__| ________   ____       \__    ___/   ____     ____   |  |
    \_____  \  |  | \___   / _/ __ \        |    |     /  _ \   /  _ \  |  |
@@ skipping 33 matching lines @@
 
   1. Build your product as you normally would, e.g.:
        ninja -C out/Release -j 100 content_shell_apk
 
   2. Build the "binary_size_tool" target from ../../build/all_android.gyp, e.g.:
        ninja -C out/Release binary_size_tool
 
   3. Run the tool specifying the library and the output report directory.
      This command will run the analysis on the Content Shell native library for
      Android using the nm/addr2line binaries from the Android NDK for ARM,
-     producing an HTMl report in /tmp/report:
+     producing an HTML report in /tmp/report:
        tools/binary_size/run_binary_size_analysis.py \
          --library out/Release/lib/libcontent_shell_content_view.so \
          --destdir /tmp/report \
          --arch android-arm
 
 Of course, there are additional options that you can see by running the tool
 with "--help".
 
 This whole process takes about an hour on a modern (circa 2014) quad-core
 machine. If you have LOTS of RAM, you can use the "--jobs" argument to
@@ skipping 15 matching lines @@
 The report is completely standalone. No external resources are required, so the
 report may be saved and viewed offline with no problems.
 
 --------------------------------------------------------------------------------
 Caveats
 --------------------------------------------------------------------------------
 The tool is not perfect and has several shortcomings:
 
   * Not all space in the binary is accounted for. The cause is still under
     investigation.
+  * When dealing with inlining and such, the size cost is attributed to the
+    resource in which the code gets inlined. Depending upon your goals for
+    analysis, this may be either good or bad; fundamentally, the more trickery
+    that the compiler and/or linker do, the less simple the relationship
+    between the original source and the resultant binary.
   * The tool is partly written in Java, temporarily tying it to Android
     purely and solely because it needs Java build logic which is only defined
     in the Android part of the build system. The Java portions need to be
     rewritten in Python so we can decouple from Android, or we need to find
     an alternative (readelf, linker maps, etc) to running nm/addr2line.
   * The Java code assumes that the library file is within a Chromium release
     directory. This limits it to Chromium-based binaries only.
   * The Java code has a hack to accurately identify the source of ICU data
-    within the Chromium source tree due to missing symbols in the ICU ASM
-    output.
+    within the Chromium source tree due to missing size information in the ICU
+    ASM output in some build variants.
   * The Python script assumes that arm-based and mips-based nm/addr2line
-    binaries exist in ../../third_party. This is true only when dealing with
-    Android and again limits the tool to Chromium-based binaries.
+    binaries exist in ../../third_party/android_tools/ndk/toolchains. This is
+    true only when dealing with Android and again limits the tool to
+    Chromium-based binaries.
   * The Python script uses build system variables to construct the classpath
     for running the Java code.
   * The Javascript code in the HTML report Assumes code lives in Chromium for
     generated hyperlinks and will not hyperlink any file that starts with the
     substring "out".
 
 --------------------------------------------------------------------------------
 Feature Requests and Bug Reports
 --------------------------------------------------------------------------------
 Please file bugs and feature requests here, making sure to use the label
 "Binary-Size-Tool":
   https://code.google.com/p/chromium/issues/entry?labels=Binary-Size-Tool
 
 View all open issues here:
   https://code.google.com/p/chromium/issues/list?can=2&q=label:Binary-Size-Tool