[docs] re-word some things, document env vars

doc/00-intro.md

@@ -1,7 +1,7 @@
 # Introduction
 
 Composer is a tool for dependency management in PHP. It allows you to declare
-the dependencies of your project and will install these dependencies for you.
+the dependencies of your project and will install them for you.
 
 ## Dependency management
 
@@ -45,7 +45,7 @@ composer:
     $ curl -s http://getcomposer.org/installer | php
 
 This will just check a few PHP settings and then download `composer.phar` to
-your working directory. This is the composer binary.
+your working directory. This file is the composer binary.
 
 After that we run the command for installing all dependencies:
 

doc/01-basic-usage.md

@@ -9,10 +9,10 @@ To install composer, simply run this command on the command line:
 This will perform some checks on your environment to make sure you can
 actually run it.
 
-This will download `composer.phar` and place it in your working directory.
-`composer.phar` 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.
+Then it will download `composer.phar` and place it in your working directory.
+`composer.phar` 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.
 
 You can place this file anywhere you wish. If you put it in your `PATH`,
 you can access it globally. On unixy systems you can even make it
@@ -94,9 +94,9 @@ supplied version constraint and download it into the the `vendor` directory.
 It's a convention to put third party code into a directory named `vendor`.
 In case of monolog it will put it into `vendor/monolog/monolog`.
 
-**Tip:** If you are using git for your project, you probably want to add
-`vendor` into your `.gitignore`. You really don't want to add all of that
-code to your repository.
+> **Tip:** If you are using git for your project, you probably want to add
+> `vendor` into your `.gitignore`. You really don't want to add all of that
+> code to your repository.
 
 Another thing that the `install` command does is it adds a `composer.lock`
 file into your project root.
@@ -145,7 +145,7 @@ this file and you will get autoloading for free.
 require 'vendor/.composer/autoload.php';
 ```
 
-This makes it really easy to use third party code, because you really just
+This makes it really easy to use third party code, because you only
 have to add one line to `composer.json` and run `install`. For monolog, it
 means that we can just start using classes from it, and they will be
 autoloaded.
@@ -157,7 +157,7 @@ $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Logger::WARNING))
 $log->addWarning('Foo');
 ```
 
-You can even add your own code to the autoloader by adding an `autoload` key
+You can even add your own code to the autoloader by adding an `autoload` field
 to `composer.json`.
 
 ```json
@@ -170,14 +170,14 @@ to `composer.json`.
 
 This is a mapping from namespaces to directories. The `src` directory would be
 in your project root. An example filename would be `src/Acme/Foo.php`
-containing a `Acme\Foo` class.
+containing an `Acme\Foo` class.
 
-After adding the `autoload` key, you have to re-run `install` to re-generate
+After adding the `autoload` field, you have to re-run `install` to re-generate
 the `vendor/.composer/autoload.php` file.
 
-Including that file will also return the autoloader instance, so you can add
-retrieve it and add more namespaces. This can be useful for autoloading
-classes in a test suite, for example.
+Including that file will also return the autoloader instance, so you can store
+the return value of the include call in a variable and add more namespaces.
+This can be useful for autoloading classes in a test suite, for example.
 
 ```php
 $loader = require 'vendor/.composer/autoload.php';

doc/03-cli.md

@@ -30,10 +30,20 @@ resolution.
 
 ### Options
 
-* **--prefer-source:** There are two ways of downloading a package: `source` and `dist`. For stable versions composer will use the `dist` by default. The `source` is a version control repository. If `--prefer-source` is enabled, composer will install from `source` if there is one. This is useful if you want to make a bugfix to a project and get a local git clone of the dependency directly.
-* **--dry-run:** If you want to run through an installation without actually installing a package, you can use `--dry-run`. This will simulate the installation and show you what would happen.
-* **--no-install-recommends:** By default composer will install all packages that are referenced by `recommend`. By passing this option you can disable that.
-* **--install-suggests:** The packages referenced by `suggest` will not be installed by default. By passing this option, you can install them.
+* **--prefer-source:** There are two ways of downloading a package: `source`
+  and `dist`. For stable versions composer will use the `dist` by default.
+  The `source` is a version control repository. If `--prefer-source` is
+  enabled, composer will install from `source` if there is one. This is
+  useful if you want to make a bugfix to a project and get a local git
+  clone of the dependency directly.
+* **--dry-run:** If you want to run through an installation without actually
+  installing a package, you can use `--dry-run`. This will simulate the
+  installation and show you what would happen.
+* **--no-install-recommends:** By default composer will install all packages
+  that are referenced by `recommend`. By passing this option you can disable
+  that.
+* **--install-suggests:** The packages referenced by `suggest` will not be
+  installed by default. By passing this option, you can install them.
 
 ## update
 
@@ -115,7 +125,7 @@ should be included in the listing.
 ### Options
 
 * **--link-type:** The link types to match on, can be specified multiple
-times.
+  times.
 
 ## validate
 
@@ -137,3 +147,34 @@ command. It will replace your `composer.phar` with the latest version.
 To get more information about a certain command, just use `help`.
 
     $ php composer.phar help install
+
+## Environment variables
+
+You can set a number of environment variables that override certain settings.
+Whenever possible it is recommended to specify these settings in the `config`
+section of `composer.json` instead. It is worth noting that that the env vars
+will always take precedence over the values specified in `composer.json`.
+
+### COMPOSER
+
+By setting the `COMPOSER` env variable is is possible to set the filename of
+`composer.json` to something else.
+
+For example:
+
+    $ COMPOSER=composer-other.json php composer.phar install
+
+### COMPOSER_VENDOR_DIR
+
+By setting this option you can make composer install the dependencies into a
+directory other than `vendor`.
+
+### COMPOSER_BIN_DIR
+
+By setting this option you can change the `bin` ([articles/vendor-bins.md])
+directory to something other than `vendor/bin`.
+
+### COMPOSER_PROCESS_TIMEOUT
+
+This env var controls the time composer waits for commands (such as git
+commands) to finish executing. The default value is 60 seconds.

doc/04-schema.md

@@ -6,7 +6,7 @@ This chapter will explain all of the options available in `composer.json`.
 
 We have a [JSON schema](http://json-schema.org) that documents the format and
 can also be used to validate your `composer.json`. In fact, it is used by the
-`validate` command. You can find it at: 
+`validate` command. You can find it at:
 [`Resources/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json).
 
 ## Package root
@@ -58,9 +58,9 @@ The type of the package. It defaults to `library`.
 
 Package types are used for custom installation logic. If you have a package
 that needs some special logic, you can define a custom type. This could be a
-`symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These will all be
-specific to certain projects, and they will need to provide an installer
-capable of installing packages of that type.
+`symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These types will
+all be specific to certain projects, and they will need to provide an
+installer capable of installing packages of that type.
 
 Out of the box, composer supports two types:
 
@@ -242,14 +242,13 @@ Repositories are not resolved recursively. You can only add them to your main
 `composer.json`. Repository declarations of dependencies' `composer.json`s are
 ignored.
 
-Following repository types are supported:
+The following repository types are supported:
 
 * **composer:** A composer repository is simply a `packages.json` file served
-  via HTTP that contains a list of `composer.json` objects with additional
+  via HTTP, that contains a list of `composer.json` objects with additional
   `dist` and/or `source` information.
 * **vcs:** The version control system repository can fetch packages from git,
-  svn and hg repositories. Note the distinction between package repository and
-  version control repository.
+  svn and hg repositories.
 * **pear:** With this you can import any pear repository into your composer
   project.
 * **package:** If you depend on a project that does not have any support for
@@ -335,7 +334,8 @@ Example:
 
 ## scripts
 
-Composer allows you to hook into various parts of the installation process through the use of scripts.
+Composer allows you to hook into various parts of the installation process
+through the use of scripts.
 
 These events are supported:
 
@@ -388,6 +388,8 @@ class ScriptHandler
 {
     static public function doSomething(Event $event)
     {
+        $composer = $event->getComposer();
+
         // custom logic
     }
 }
@@ -411,6 +413,6 @@ Optional.
 A set of files that should be treated as binaries and symlinked into the `bin-
 dir` (from config).
 
-See [articles/bin.md] for more details.
+See [articles/vendor-bins.md] for more details.
 
 Optional.

doc/05-repositories.md

@@ -5,12 +5,12 @@ of repositories are available, and how they work.
 
 ## Concepts
 
-Before we look at the different types of repositories that we can have, we
-need to understand some of the basic concepts that composer is built on.
+Before we look at the different types of repositories that exist, we need to
+understand some of the basic concepts that composer is built on.
 
 ### Package
 
-Composer is a dependency manager. It installs packages. A package is
+Composer is a dependency manager. It installs packages locally. A package is
 essentially just a directory containing something. In this case it is PHP
 code, but in theory it could be anything. And it contains a package
 description which has a name and a version. The name and the version are used
@@ -20,9 +20,9 @@ In fact, internally composer sees every version as a separate package. While
 this distinction does not matter when you are using composer, it's quite
 important when you want to change it.
 
-In addition to the name and the version, there is useful data. The only really
-important piece of information is the package source, that describes where to
-get the package contents. The package data points to the contents of the
+In addition to the name and the version, there is useful data. The information
+most relevant for installation is the source definition, which describes where
+to get the package contents. The package data points to the contents of the
 package. And there are two options here: dist and source.
 
 **Dist:** The dist is a packaged version of the package data. Usually a
@@ -135,11 +135,11 @@ The following are supported:
 * **Subversion:** [subversion.apache.org](http://subversion.apache.org)
 * **Mercurial:** [mercurial.selenic.com](http://mercurial.selenic.com)
 
-To use these systems you need to have them installed. That can be
-invonvenient. And for this reason there is special support for GitHub and
-BitBucket that use the APIs provided by these sites, to fetch the packages
-without having to install the version control system. The VCS repository
-provides `dist`s for them that fetch the packages as zips.
+To get packages from these systems you need to have their respective clients
+installed. That can be invonvenient. And for this reason there is special
+support for GitHub and BitBucket that use the APIs provided by these sites, to
+fetch the packages without having to install the version control system. The
+VCS repository provides `dist`s for them that fetch the packages as zips.
 
 * **GitHub:** [github.com](https://github.com) (Git)
 * **BitBucket:** [bitbucket.org](https://bitbucket.org) (Git and Mercurial)
@@ -177,12 +177,12 @@ In this case the short name of the channel is `pear2`, so the
 ### Package
 
 If you want to use a project that does not support composer through any of the
-means above, you still can define the package yourself using a `package`
+means above, you still can define the package yourself by using a `package`
 repository.
 
 Basically, you define the same information that is included in the `composer`
 repository's `packages.json`, but only for a single package. Again, the
-minimally required fields are `name`, `version`, and either of `dist` or
+minimum required fields are `name`, `version`, and either of `dist` or
 `source`.
 
 Here is an example for the smarty template engine:
@@ -231,8 +231,7 @@ there are some use cases for hosting your own repository.
 When hosting your own package repository it is recommended to use a `composer`
 one. This is type that is native to composer and yields the best performance.
 
-There are a few different tools that can help you create a `composer`
-repository.
+There are a few tools that can help you create a `composer` repository.
 
 ### Packagist
 
@@ -251,13 +250,12 @@ github repository](https://github.com/composer/packagist).
 
 ### Satis
 
-Satis is a static `composer` repository generator. It is a bit like a ultra-
-lightweight, file-based version of packagist.
+Satis is a static `composer` repository generator. It is a bit like an ultra-
+lightweight, static file-based version of packagist.
 
-You give it a `composer.json` containing repositories, typically VCS and package
-repository definitions. It will fetch all the packages that are `require`d from
-these repositories and dump a `packages.json` that is your `composer`
-repository.
+You give it a `composer.json` containing repositories, typically VCS and
+package repository definitions. It will fetch all the packages that are
+`require`d and dump a `packages.json` that is your `composer` repository.
 
 Check [the satis GitHub repository](https://github.com/composer/satis) for more
 information.

doc/06-community.md

@@ -1,7 +1,7 @@
 # Community
 
-We have a lot of people using composer, and also many contributors to the
-project.
+There are a lot of people using composer already, quite a few are also already
+contributing.
 
 ## Contributing
 
@@ -22,7 +22,7 @@ The most important guidelines are described as follows:
 
 ## IRC / mailing list
 
-The developer mailing list is on [google groups](http://groups.google.com/group/composer-dev/) 
+The developer mailing list is on [google groups](http://groups.google.com/group/composer-dev/)
 IRC channels are available for discussion as well, on
 irc.freenode.org [#composer](irc://irc.freenode.org/composer) for users and
 [#composer-dev](irc://irc.freenode.org/composer-dev) for development.