Make some small tweaks to the build instructions.

docs/mac_build_instructions.md

Index: docs/mac_build_instructions.md
diff --git a/docs/mac_build_instructions.md b/docs/mac_build_instructions.md
index 450271080c5878c6d2221c5861fd44935f8db0ec..b2f15086528f9e99fad064c64a15894c366f6bfc 100644
--- a/docs/mac_build_instructions.md
+++ b/docs/mac_build_instructions.md
@@ -8,68 +8,84 @@ Google employee? See [go/building-chrome](https://goto.google.com/building-chrom
 
 *   A 64-bit Mac running 10.9+.
 *   [Xcode](https://developer.apple.com/xcode) 7.3+.
-*   The OSX 10.10 SDK. Run
-    ```
-    ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs
+*   The OS X 10.10 SDK. Run
+
+    ```shell  
+    $ ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs
     ```
-    to check whether you have it.  Building with the 10.11 SDK works too, but
+ 
+    to check whether you have it.  Building with a newer SDK works too, but
     the releases currently use the 10.10 SDK.
-*   Git v
-*   Python 2.7.x.
 
 ## Install `depot_tools`
 
-Clone the depot_tools repository:
+Clone the `depot_tools` repository:
 
-    $ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
+```shell
+$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
+```
 
-Add depot_tools to the end of your PATH (you will probably want to put this
-in your ~/.bashrc or ~/.zshrc). Assuming you cloned depot_tools
-to /path/to/depot_tools:
+Add `depot_tools` to the end of your PATH (you will probably want to put this
+in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to
+`/path/to/depot_tools`:
 
-    $ export PATH=$PATH:/path/to/depot_tools
+```shell
+$ export PATH="$PATH:/path/to/depot_tools"
+```
 
 ## Get the code
 
-Create a chromium directory for the checkout and change to it (you can call
-this whatever you like and put it wherever you like, as
-long as the full path has no spaces):
-    
-    $ mkdir chromium
-    $ cd chromium
+Create a `chromium` directory for the checkout and change to it (you can call
+this whatever you like and put it wherever you like, as long as the full path
+has no spaces):
 
-Run the `fetch` tool from depot_tools to check out the code and its
+```shell
+$ mkdir chromium && cd chromium
+```
+
+Run the `fetch` tool from `depot_tools` to check out the code and its
 dependencies.
 
-    $ fetch chromium
+```shell
+$ fetch chromium
+```
 
 If you don't want the full repo history, you can save a lot of time by
-adding the `--no-history` flag to fetch. Expect the command to take
-30 minutes on even a fast connection, and many hours on slower ones.
+adding the `--no-history` flag to `fetch`.
 
-When fetch completes, it will have created a directory called `src`.
-The remaining instructions assume you are now in that directory:
+Expect the command to take 30 minutes on even a fast connection, and many
+hours on slower ones.
 
-    $ cd src
+When `fetch` completes, it will have created a hidden `.gclient` file and a
+directory called `src` in the working directory. The remaining instructions
+assume you are now in that directory:
 
-*Optional*: You can also [install API keys](https://www.chromium.org/developers/how-tos/api-keys)
-if you want to talk to some of the Google services, but this is not necessary
-for most development and testing purposes.
+```shell
+$ cd src
+```
+
+*Optional*: You can also [install API
+keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
+build to talk to some Google services, but this is not necessary for most
+development and testing purposes.
 
 ## Building
 
-Chromium uses [Ninja](https://ninja-build.org) as its main build tool, and
-a tool called [GN](../tools/gn/docs/quick_start.md) to generate
-the .ninja files to do the build. To create a build directory:
+Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
+with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
+files. You can create any number of *build directories* with different
+configurations. To create a build directory:
 
-    $ gn gen out/Default
+```shell
+$ gn gen out/Default
+```
 
-* You only have to do run this command once, it will self-update the build
-  files as needed after that.
-* You can replace `out/Default` with another directory name, but we recommend
-  it should still be a subdirectory of `out`.
-* To specify build parameters for GN builds, including release settings,
-  see [GN build configuration](https://www.chromium.org/developers/gn-build-configuration). 
+* You only have to do run this once for each new build directory, Ninja will

[Dirk Pranke, 2016/11/30 23:40:20]

Nit: s/do //, here and in the other pages.

[Sidney San Martín, 2016/12/01 00:22:23]

Done.

+  update the build files as needed.
+* You can replace `Default` with another name, but
+  it should be a subdirectory of `out`.
+* For other build arguments, including release settings, see [GN build
+  configuration](https://www.chromium.org/developers/gn-build-configuration).
   The default will be a debug component build matching the current host
   operating system and CPU.
 * For more info on GN, run `gn help` on the command line or read the
@@ -83,21 +99,28 @@ lot faster in Release builds.
 
 Put
 
-    is_debug = false
+```
+is_debug = false
+```
 
-in your args.gn to do a release build.
+in your `args.gn` to do a release build.
 
 Put
 
-    is_component_build = true
+```
+is_component_build = true
+```
 
-in your args.gn to build many small dylibs instead of a single large executable.
-This makes incremental builds much faster, at the cost of producing a binary
-that opens less quickly.  Component builds work in both debug and release.
+in your `args.gn` to build many small dylibs instead of a single large
+executable. This makes incremental builds much faster, at the cost of producing
+a binary that opens less quickly. Component builds work in both debug and
+release.
 
 Put
 
-    symbol_level = 0
+```
+symbol_level = 0
+```
 
 in your args.gn to disable debug symbols altogether.  This makes both full
 rebuilds and linking faster (at the cost of not getting symbolized backtraces
@@ -109,14 +132,18 @@ You might also want to [install ccache](ccache_mac.md) to speed up the build.
 
 Once it is built, you can simply run the browser:
 
-    $ out/Default/chrome
+```shell
+$ out/Default/chrome
+```
 
 ## Running test targets
 
 You can run the tests in the same way. You can also limit which tests are
 run using the `--gtest_filter` arg, e.g.:
 
-    $ ninja -C out/Default unit_tests --gtest_filter="PushClientTest.*"
+```
+$ ninja -C out/Default unit_tests --gtest_filter="PushClientTest.*"
+```
 
 You can find out more about GoogleTest at its
 [GitHub page](https://github.com/google/googletest).
@@ -126,102 +153,114 @@ You can find out more about GoogleTest at its
 Good debugging tips can be found
 [here](http://dev.chromium.org/developers/how-tos/debugging-on-os-x). If you
 would like to debug in a graphical environment, rather than using `lldb` at the
-command line, that is possible without building in Xcode. See
-[Debugging in Xcode](http://www.chromium.org/developers/how-tos/debugging-on-os-x/building-with-ninja-debugging-with-xcode)
-for information on how.
+command line, that is possible without building in Xcode (see
+[Debugging in Xcode](http://www.chromium.org/developers/how-tos/debugging-on-os-x/building-with-ninja-debugging-with-xcode)).
 
 ## Update your checkout
 
 To update an existing checkout, you can run
 
-    $ git rebase-update
-    $ gclient sync
+```shell
+$ git rebase-update
+$ gclient sync
+```
 
 The first command updates the primary Chromium source repository and rebases
-any of your local branches on top of tip-of-tree (aka the Git branch `origin/master`).
-If you don't want to use this script, you can also just use `git pull` or 
-other common Git commands to update the repo.
+any of your local branches on top of tip-of-tree (aka the Git branch
+`origin/master`). If you don't want to use this script, you can also just use
+`git pull` or other common Git commands to update the repo.
 
-The second command syncs the subrepositories to the appropriate versions and
-re-runs the hooks as needed.
+The second command syncs dependencies to the appropriate versions and re-runs
+hooks as needed.
 
 ## Tips, tricks, and troubleshooting
 
 ### Using Xcode-Ninja Hybrid
 
-While using Xcode is unsupported, gn supports a hybrid approach of using ninja
+While using Xcode is unsupported, GN supports a hybrid approach of using Ninja
 for building, but Xcode for editing and driving compilation.  Xcode is still
 slow, but it runs fairly well even **with indexing enabled**.  Most people
-build in the Terminal and write code with a text editor though.
+build in the Terminal and write code with a text editor, though.
 
-With hybrid builds, compilation is still handled by ninja, and can be run by the
-command line (e.g. ninja -C out/gn chrome) or by choosing the chrome target
-in the hybrid workspace and choosing build.
+With hybrid builds, compilation is still handled by Ninja, and can be run from
+the command line (e.g. `ninja -C out/gn chrome`) or by choosing the `chrome`
+target in the hybrid workspace and choosing Build.
 
-To use Xcode-Ninja Hybrid pass --ide=xcode to `gn gen`
+To use Xcode-Ninja Hybrid pass `--ide=xcode` to `gn gen`:
 
 ```shell
-gn gen out/gn --ide=xcode
+$ gn gen out/gn --ide=xcode
 ```
 
 Open it:
 
 ```shell
-open out/gn/ninja/all.xcworkspace
+$ open out/gn/ninja/all.xcworkspace
 ```
 
 You may run into a problem where http://YES is opened as a new tab every time
 you launch Chrome. To fix this, open the scheme editor for the Run scheme,
 choose the Options tab, and uncheck "Allow debugging when using document
 Versions Browser". When this option is checked, Xcode adds
-`--NSDocumentRevisionsDebugMode YES` to the launch arguments, and the `YES` gets
-interpreted as a URL to open.
+`--NSDocumentRevisionsDebugMode YES` to the launch arguments, and the `YES`
+gets interpreted as a URL to open.
 
 If you have problems building, join us in `#chromium` on `irc.freenode.net` and
-ask there. As mentioned above, be sure that the
-[waterfall](http://build.chromium.org/buildbot/waterfall/) is green and the tree
-is open before checking out. This will increase your chances of success.
+ask there. Be sure that the
+[waterfall](http://build.chromium.org/buildbot/waterfall/) is green and the
+tree is open before checking out. This will increase your chances of success.
 
 ### Improving performance of `git status`
 
 `git status` is used frequently to determine the status of your checkout.  Due
-to the number of files in Chromium's checkout, `git status` performance can be
-quite variable.  Increasing the system's vnode cache appears to help.  By
+to the large number of files in Chromium's checkout, `git status` performance
+can be quite variable.  Increasing the system's vnode cache appears to help. By
 default, this command:
 
-    sysctl -a | egrep kern\..*vnodes
+```shell
+$ sysctl -a | egrep kern\..*vnodes
+```
 
 Outputs `kern.maxvnodes: 263168` (263168 is 257 * 1024).  To increase this
 setting:
 
-    sudo sysctl kern.maxvnodes=$((512*1024))
+```shell
+$ sudo sysctl kern.maxvnodes=$((512*1024))
+```
 
 Higher values may be appropriate if you routinely move between different
 Chromium checkouts.  This setting will reset on reboot, the startup setting can
 be set in `/etc/sysctl.conf`:
 
-    echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf
+```shell
+$ echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf
+```
 
 Or edit the file directly.
 
-If your `git --version` reports 2.6 or higher, the following may also improve
+If `git --version` reports 2.6 or higher, the following may also improve
 performance of `git status`:
 
-    git update-index --untracked-cache
+```shell
+$ git update-index --untracked-cache
+```
 
 ### Xcode license agreement
 
 If you're getting the error
 
-```
-Agreeing to the Xcode/iOS license requires admin privileges, please re-run as root via sudo.
-```
+> Agreeing to the Xcode/iOS license requires admin privileges, please re-run as
+> root via sudo.
 
 the Xcode license hasn't been accepted yet which (contrary to the message) any
 user can do by running:
 
-    xcodebuild -license
+```shell
+$ xcodebuild -license
+```
 
 Only accepting for all users of the machine requires root:
 
-    sudo xcodebuild -license
+```shell
+$ sudo xcodebuild -license
+```