Restructured installation instructions.

The structure is now: Platform, installation method.

--
MOS_MIGRATED_REVID=128461668

1 files changed, 113 insertions, 73 deletions

diff --git a/site/docs/install.md b/site/docs/install.md
index 8ffb4a0537..206226f282 100644
--- a/site/docs/install.md
+++ b/site/docs/install.md
@@ -5,42 +5,39 @@ title: Installing Bazel
 
 # Installing Bazel
 
-## System Requirements
-
 Supported platforms:
 
-*   Ubuntu Linux (Wily 15.10 and Trusty 14.04 LTS)
-*   Mac OS X
-*   Windows (highly experimental)
+*   [Ubuntu Linux (Wily 15.10 and Trusty 14.04 LTS)](#ubuntu)
+*   [Mac OS X](#mac-os-x)
+*   [Windows (highly experimental)](windows.md)
+
+For other platforms, you can try to [compile from source](#compiling-from-source).
 
-Java:
+Required Java version:
 
 *   Java JDK 8 or later ([JDK 7](#jdk7) is still supported
     but deprecated).
 
+Extras:
 
-## Guidance
-
-#### Ubuntu
-
-  * Using our custom APT repostiory, see [Install on Ubuntu](#install-on-ubuntu)
-  * Using binary installer, see [Install with installer](#install-with-installer)
-  * Compiling Bazel from source, see [Compiling from source](#compiling-from-source)
+*   [Bash completion](#bash)
+*   [zsh completion](#zsh)
 
-#### Mac OS X
+For more information on using Bazel, see [Getting
+started](getting-started.html).
 
-  * Using Homebrew, see [Install on Mac OS X](#install-on-mac-ox-x)
-  * Using binary installer, see [Install with installer](#install-with-installer)
-  * Compiling Bazel from source, see [Compiling from source](#compiling-from-source)
 
-#### Windows
+## <a name="ubuntu"></a>Ubuntu
 
-  * Windows is not fully supported yet; for experimental instructions, see [Building Bazel on Windows](windows.html)
+Install Bazel on Ubuntu using one of the following methods:
 
+  * [Using our custom APT repostiory](#install-on-ubuntu)
+  * [Using binary installer](#install-with-installer-ubuntu)
+  * [Compiling Bazel from source](#compiling-from-source)
 
-## <a name="install-on-ubuntu"></a>Install on Ubuntu
+### <a name="install-on-ubuntu"></a> Using Bazel custom API repository (recommended)
 
-#### Install JDK 8
+#### 1. Install JDK 8
 
 If you are running **Ubuntu Wily (15.10)**, you can skip this step.
 But for **Ubuntu Trusty (14.04 LTS)** users, since OpenJDK 8 is not available on Trusty, please install Oracle JDK 8:
@@ -53,7 +50,7 @@ $ sudo apt-get install oracle-java8-installer
 
 Note: You might need to `sudo apt-get install software-properties-common` if you don't have the `add-apt-repository` command. See [here](http://manpages.ubuntu.com/manpages/wily/man1/add-apt-repository.1.html).
 
-#### 1. Add Bazel distribution URI as a package source (one time setup)
+#### 2. Add Bazel distribution URI as a package source (one time setup)
 
 ```
 $ echo "deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8" | sudo tee /etc/apt/sources.list.d/bazel.list
@@ -62,7 +59,7 @@ $ curl https://storage.googleapis.com/bazel-apt/doc/apt-key.pub.gpg | sudo apt-k
 
 If you want to use the JDK 7, please replace `jdk1.8` with `jdk1.7` and if you want to install the testing version of Bazel, replace `stable` with `testing`.
 
-#### 2. Update and install Bazel
+#### 3. Update and install Bazel
 
 `$ sudo apt-get update && sudo apt-get install bazel`
 
@@ -70,30 +67,15 @@ Once installed, you can upgrade to newer version of Bazel with:
 
 `$ sudo apt-get upgrade bazel`
 
-## <a name="install-on-mac-ox-x"></a>Install on Mac OS X
-
-#### 1. Install Homebrew on Mac OS X (one time setup)
-
-`$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
-
-#### 2. Install Bazel using Homebrew
-
-`$ brew install bazel`
-
-Once installed, you can upgrade to newer version of Bazel with:
-
-`$ brew upgrade bazel`
+### <a name="install-with-installer-ubuntu"></a>Install with Installer
 
-
-## <a name="install-with-installer"></a>Install with installer
+We provide binary installers on our
+<a href="https://github.com/bazelbuild/bazel/releases">GitHub releases page</a>
 
 The installer only contains Bazel binary, some additional libraries are required to be installed on the machine to work.
 
-### Install dependencies
-
-#### Ubuntu
 
-##### 1. Install JDK 8
+#### 1. Install JDK 8
 
 **Ubuntu Trusty (14.04 LTS).** OpenJDK 8 is not available on Trusty. To
 install Oracle JDK 8:
@@ -112,23 +94,83 @@ Note: You might need to `sudo apt-get install software-properties-common` if you
 $ sudo apt-get install openjdk-8-jdk
 ```
 
-##### 2. Install required packages
+#### 2. Install other required packages
 
 ```
 $ sudo apt-get install pkg-config zip g++ zlib1g-dev unzip
 ```
 
+#### 3. Download Bazel
 
-#### Mac OS X
+Download the [Bazel installer](https://github.com/bazelbuild/bazel/releases) for
+your operating system.
+
+#### 4. Run the installer
 
-##### 1. Install JDK 8
+Run the installer:
+
+<pre>
+$ chmod +x bazel-<em>version</em>-installer-<em>os</em>.sh
+$ ./bazel-<em>version</em>-installer-<em>os</em>.sh --user
+</pre>
+
+The `--user` flag installs Bazel to the `$HOME/bin` directory on your
+system and sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help`
+command to see additional installation options.
+
+#### 5. Set up your environment
+
+If you ran the Bazel installer with the `--user` flag as above, the Bazel
+executable is installed in your `$HOME/bin` directory. It's a good idea to add
+this directory to your default paths, as follows:
+
+```bash
+$ export PATH="$PATH:$HOME/bin"
+```
+
+You can also add this command to your `~/.bashrc` file.
+
+
+
+## <a name="mac-os-x"></a>Mac OS X
+
+Install Bazel on Mac OS X using one of the following methods:
+
+  * [Using Homebrew](#install-on-mac-os-x-homebrew)
+  * [Using binary installer](#install-with-installer-mac-os-x)
+  * [Compiling Bazel from source](#compiling-from-source)
+
+
+### <a name="install-on-mac-os-x-homebrew"></a>Using Homebrew
+
+#### 1. Install Homebrew on Mac OS X (one time setup)
+
+`$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
+
+#### 2. Install Bazel Homebrew Package
+
+`$ brew install bazel`
+
+Once installed, you can upgrade to newer version of Bazel with:
+
+`$ brew upgrade bazel`
+
+
+### <a name="install-with-installer-mac-os-x"></a>Install with installer
+
+We provide binary installers on our
+<a href="https://github.com/bazelbuild/bazel/releases">GitHub releases page</a>
+
+The installer only contains Bazel binary, some additional libraries are required to be installed on the machine to work.
+
+#### 1. Install JDK 8
 
 JDK 8 can be downloaded from
 [Oracle's JDK Page](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
 Look for "Mac OS X x64" under "Java SE Development Kit". This will download a
 DMG image with an install wizard.
 
-##### 2. Install XCode command line tools
+#### 2. Install XCode command line tools
 
 Xcode can be downloaded from the
 [Apple Developer Site](https://developer.apple.com/xcode/downloads/), which will
@@ -137,19 +179,19 @@ redirect to the App Store.
 For `objc_*` and `ios_*` rule support, you must have Xcode 6.1 or later with
 iOS SDK 8.1 installed on your system.
 
-Once XCode is installed you can trigger the license signature with the following
+Once XCode is installed you can trigger signing the license with the following
 command:
 
 ```
 $ sudo gcc --version
 ```
 
-### Download Bazel
+#### 3. Download Bazel
 
 Download the [Bazel installer](https://github.com/bazelbuild/bazel/releases) for
 your operating system.
 
-### Run the installer
+#### 4. Run the installer
 
 Run the installer:
 
@@ -162,7 +204,7 @@ The `--user` flag installs Bazel to the `$HOME/bin` directory on your
 system and sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help`
 command to see additional installation options.
 
-## Set up your environment
+#### 5. Set up your environment
 
 If you ran the Bazel installer with the `--user` flag as above, the Bazel
 executable is installed in your `$HOME/bin` directory. It's a good idea to add
@@ -174,6 +216,25 @@ $ export PATH="$PATH:$HOME/bin"
 
 You can also add this command to your `~/.bashrc` file.
 
+## <a name="compiling-from-source"></a>Compiling from source
+
+If you would like to build Bazel from source, clone the source from GitHub and
+run `./compile.sh` to build it:
+
+```
+$ git clone https://github.com/bazelbuild/bazel.git
+$ cd bazel
+$ ./compile.sh
+```
+
+This will create a bazel binary in `bazel-bin/src/bazel`. This binary is
+self-contained, so it can be copied to a directory on the PATH (e.g.,
+`/usr/local/bin`) or used in-place.
+
+Check our [continuous integration](http://ci.bazel.io) for the current status of
+the build.
+
+
 ## <a name="jdk7"></a>Using Bazel with JDK 7 (deprecated)
 
 Bazel version _0.1.0_ runs without any change with JDK 7. However, future
@@ -184,7 +245,7 @@ The installer for JDK 7 for Bazel versions after _0.1.0_ is labeled
 </pre>
 If you wish to use JDK 7, follow the same steps as for JDK 8 but with the _jdk7_ installer or using a different APT repository as described [here](#1-add-bazel-distribution-uri-as-a-package-source-one-time-setup).
 
-### Getting bash completion
+## <a name="bash"></a>Getting bash completion
 
 Bazel comes with a bash completion script. To install it:
 
@@ -195,7 +256,7 @@ Bazel comes with a bash completion script. To install it:
    you and simply insert `source /path/to/bazel-complete.bash` in your
    `~/.bashrc` file (under OS X, put it in your `~/.bash_profile` file).
 
-### Getting zsh completion
+## <a name="zsh"></a>Getting zsh completion
 
 Bazel also comes with a zsh completion script. To install it:
 
@@ -215,24 +276,3 @@ Bazel also comes with a zsh completion script. To install it:
     zstyle ':completion:*' use-cache on
     zstyle ':completion:*' cache-path ~/.zsh/cache
     ```
-
-## Compiling from source
-
-If you would like to build Bazel from source, clone the source from GitHub and
-run `./compile.sh` to build it:
-
-```
-$ git clone https://github.com/bazelbuild/bazel.git
-$ cd bazel
-$ ./compile.sh
-```
-
-This will create a bazel binary in `bazel-bin/src/bazel`. This binary is
-self-contained, so it can be copied to a directory on the PATH (e.g.,
-`/usr/local/bin`) or used in-place.
-
-Check our [continuous integration](http://ci.bazel.io) (Bazel bootstrap and
-maintenance &gt; Bazel) for the current status of the build.
-
-For more information on using Bazel, see [Getting
-started](getting-started.html).