- Closes #1811 for Toolbox

- Updating with comments

Signed-off-by: Mary Anthony <mary@docker.com>

docs/install.md

@@ -12,50 +12,67 @@ weight=4
 
 # Install Docker Compose
 
-To install Compose, you'll need to install Docker first. You'll then install
+You can run Compose on OS X and 64-bit Linux.  It is currently not supported on
-Compose with a `curl` command. 
+the Windows operating system. To install Compose, you'll need to install Docker
+first. 
 
-## Install Docker
+Depending on how your system is configured, you may require `sudo` access to
+install Compose. If your system requires `sudo`, you will receive "Permission
+denied" errors when installing Compose. If this is the case for you, preface the
+install commands with `sudo` to install.
 
-First, install Docker version 1.7.1 or greater:
+To install Compose, do the following:
 
-- [Instructions for Mac OS X](http://docs.docker.com/installation/mac/)
+1. Install Docker Engine version 1.7.1 or greater:
-- [Instructions for Ubuntu](http://docs.docker.com/installation/ubuntulinux/)
-- [Instructions for other systems](http://docs.docker.com/installation/)
 
-## Install Compose
+     * <a href="https://docs.docker.com/installation/mac/" target="_blank">Mac OS X installation</a> (installs both Engine and Compose)
      
-To install Compose, run the following commands:
+     * <a href="https://docs.docker.com/installation/ubuntulinux/" target="_blank">Ubuntu installation</a>
      
-    curl -L https://github.com/docker/compose/releases/download/1.3.3/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
+     * <a href="https://docs.docker.com/installation/" target="_blank">other system installations</a>
-    chmod +x /usr/local/bin/docker-compose
  
-> Note: If you get a "Permission denied" error, your `/usr/local/bin` directory probably isn't writable and you'll need to install Compose as the superuser. Run `sudo -i`, then the two commands above, then `exit`.
+2. Mac OS X users are done installing. Others should continue to the next step.
    
-Optionally, you can also install [command completion](completion.md) for the
+3. Go to the <a href="https://github.com/docker/compose/releases" target="_blank">repository release page</a>.
-bash and zsh shell.
 
-> **Note:** Some older Mac OS X CPU architectures are incompatible with the binary. If you receive an "Illegal instruction: 4" error after installing, you should install using the `pip` command instead.
+4. Enter the `curl` command in your termial.
 
-Compose is available for OS X and 64-bit Linux. If you're on another platform,
+     The command has the following format:
-Compose can also be installed as a Python package:
 
-    $ sudo pip install -U docker-compose
+        curl -L https://github.com/docker/compose/releases/download/VERSION_NUM/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
    
-No further steps are required; Compose should now be successfully installed.
+     If you have problems installing with `curl`, you can use `pip` instead: `pip install -U docker-compose`
-You can test the installation by running `docker-compose --version`.
       
-### Upgrading
+4. Apply executable permissions to the binary:
 
-If you're coming from Compose 1.2 or earlier, you'll need to remove or migrate your existing containers after upgrading Compose. This is because, as of version 1.3, Compose uses Docker labels to keep track of containers, and so they need to be recreated with labels added.
+        $ chmod +x /usr/local/bin/docker-compose
 
-If Compose detects containers that were created without labels, it will refuse to run so that you don't end up with two sets of them. If you want to keep using your existing containers (for example, because they have data volumes you want to preserve) you can migrate them with the following command:
+5.  Optionally, install [command completion](completion.md) for the
+`bash` and `zsh` shell.
 
-    docker-compose migrate-to-labels
+6. Test the installation.
 
-Alternatively, if you're not worried about keeping them, you can remove them - Compose will just create new ones.
+        $ docker-compose --version
+        docker-compose version: 1.4.0
 
-    docker rm -f myapp_web_1 myapp_db_1 ...
+## Upgrading
+
+If you're upgrading from Compose 1.2 or earlier, you'll need to remove or migrate
+your existing containers after upgrading Compose. This is because, as of version
+1.3, Compose uses Docker labels to keep track of containers, and so they need to
+be recreated with labels added.
+
+If Compose detects containers that were created without labels, it will refuse
+to run so that you don't end up with two sets of them. If you want to keep using
+your existing containers (for example, because they have data volumes you want
+to preserve) you can migrate them with the following command:
+
+    $ docker-compose migrate-to-labels
+
+Alternatively, if you're not worried about keeping them, you can remove them &endash;
+Compose will just create new ones.
+
+    $ docker rm -f -v myapp_web_1 myapp_db_1 ...
 
 
 ## Uninstallation
@@ -69,10 +86,13 @@ To uninstall Docker Compose if you installed using `pip`:
 
     $ pip uninstall docker-compose
     
-> Note: If you get a "Permission denied" error using either of the above methods, you probably do not have the proper permissions to remove `docker-compose`.  To force the removal, prepend `sudo` to either of the above commands and run again.
+>**Note**: If you get a "Permission denied" error using either of the above
+>methods, you probably do not have the proper permissions to remove
+>`docker-compose`.  To force the removal, prepend `sudo` to either of the above
+>commands and run again.
 
 
-## Compose documentation
+## Where to go next
 
 - [User guide](/)
 - [Get started with Django](django.md)