rewriting some documentation sections

doc/00-intro.md

@@ -47,7 +47,7 @@ any version beginning with `1.2`.
 ## System Requirements
 
 Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile
-flags are also required, but the installer will warn you about any
+flags are also required, but when using the installer you will be warned about any
 incompatibilities.
 
 To install packages from sources instead of simple zip archives, you will need
@@ -58,12 +58,17 @@ Linux and OSX.
 
 ## Installation - *nix
 
+These instructions should cover most Linux and Unix variants (including OSX).
+
 ### Downloading the Composer Executable
 
+There are in short, two ways to install Composer on *nix. Locally as part of your
+project, or globally as a system wide executable.
+
 #### Locally
 
-To actually get Composer, we need to do two things. The first one is installing
-Composer (again, this means downloading it into your project):
+Installing Composer locally is a matter of just running the installer in your
+project directory:
 
 ```sh
 curl -sS https://getcomposer.org/installer | php
@@ -76,8 +81,8 @@ curl -sS https://getcomposer.org/installer | php
 php -r "readfile('https://getcomposer.org/installer');" | php
 ```
 
-This will just check a few PHP settings and then download `composer.phar` to
-your working directory. This file is the Composer binary. It is a PHAR (PHP
+The installer will just check a few PHP settings and then download `composer.phar`
+to your working directory. This file is the Composer binary. It is a PHAR (PHP
 archive), which is an archive format for PHP which can be run on the command
 line, amongst other things.
 
@@ -106,17 +111,6 @@ mv composer.phar /usr/local/bin/composer
 
 Then, just run `composer` in order to run Composer instead of `php composer.phar`.
 
-#### Globally (on OSX via homebrew)
-
-Composer is part of the homebrew-php project.
-
-```sh
-brew update
-brew tap homebrew/dupes
-brew tap homebrew/php
-brew install composer
-```
-
 ## Installation - Windows
 
 ### Using the Installer

doc/01-basic-usage.md

@@ -1,29 +1,8 @@
 # Basic usage
 
-## Installation
+## Installing
 
-To install Composer, you just need to download the `composer.phar` executable.
-
-```sh
-curl -sS https://getcomposer.org/installer | php
-```
-
-For the details, see the [Introduction](00-intro.md) chapter.
-
-To check if Composer is working, just run the PHAR through `php`:
-
-```sh
-php composer.phar
-```
-
-This should give you a list of available commands.
-
-> **Note:** You can also perform the checks only without downloading Composer
-> by using the `--check` option. For more information, just use `--help`.
->
-> ```sh
-> curl -sS https://getcomposer.org/installer | php -- --help
-> ```
+If you have not yet installed Composer, refer to to the [Intro](00-intro.md) chapter.
 
 ## `composer.json`: Project Setup
 

doc/03-cli.md

@@ -482,6 +482,10 @@ performance.
   a bit of time to run so it is currently not done by default.
 * **--no-dev:** Disables autoload-dev rules.
 
+## clear-cache
+
+Deletes all content from Composer's cache directories.
+
 ## licenses
 
 Lists the name, version and license of every package installed. Use