added some links and some restructuring

doc/01-basic-usage.md

@@ -18,8 +18,8 @@ other metadata as well.
 ### The `require` Key
 
 The first (and often only) thing you specify in `composer.json` is the
-`require` key. You're simply telling Composer which packages your project
-depends on.
+[`require`](04-schema.md#require) key. You're simply telling Composer which 
+packages your project depends on.
 
 ```json
 {
@@ -29,8 +29,9 @@ depends on.
 }
 ```
 
-As you can see, `require` takes an object that maps **package names**
-(e.g. `monolog/monolog`) to **version constraints** (e.g. `1.0.*`).
+As you can see, [`require`](04-schema.md#require) takes an object that maps 
+**package names** (e.g. `monolog/monolog`) to **version constraints** (e.g. 
+`1.0.*`).
 
 ### Package Names
 
@@ -49,7 +50,7 @@ smaller decoupled parts.
 
 In the previous example we were requiring version
 [`1.0.*`](http://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*) of
-monolog. This means any version in the `1.0` development branch. It is the
+Monolog. This means any version in the `1.0` development branch. It is the
 equivalent of saying versions that match `>=1.0 <1.1`.
 
 Version constraints can be specified in several ways, read 
@@ -66,7 +67,7 @@ all packages instead of doing per dependency you can also use the
 ## Installing Dependencies
 
 To install the defined dependencies for your project, just run the
-`install` command.
+[`install`](03-cli.md#install) command.
 
 ```sh
 php composer.phar install
@@ -75,13 +76,14 @@ php composer.phar install
 This will find the latest version of `monolog/monolog` that matches the
 supplied version constraint and download it into 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`.
+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` in your `.gitignore`. You really don't want to add all of that
 > code to your repository.
 
-You will notice the `install` command also created a `composer.lock` file.
+You will notice the [`install`](03-cli.md#install) command also created a 
+`composer.lock` file.
 
 ## `composer.lock` - The Lock File
 
@@ -92,9 +94,9 @@ to those specific versions.
 **Commit your application's `composer.lock` (along with `composer.json`)
 into version control.**
 
-This is important because the `install` command checks if a lock file is
-present, and if it is, it downloads the versions specified there (regardless
-of what `composer.json` says).
+This is important because the [`install`](03-cli.md#install) command checks 
+if a lock file is present, and if it is, it downloads the versions specified 
+there (regardless of what `composer.json` says).
 
 This means that anyone who sets up the project will download the exact same
 version of the dependencies. Your CI server, production machines, other
@@ -106,12 +108,13 @@ if your dependencies released many new versions since then.
 
 If no `composer.lock` file exists, Composer will read the dependencies and
 versions from `composer.json` and  create the lock file after executing the
-`update` or the `install` command.
+[`update`](03-cli.md#update) or the [`install`](03-cli.md#install) command.
 
 This means that if any of the dependencies get a new version, you won't get the
-updates automatically. To update to the new version, use the `update` command.
-This will fetch the latest matching versions (according to your `composer.json`
-file) and also update the lock file with the new version.
+updates automatically. To update to the new version, use the 
+[`update`](03-cli.md#update) command. This will fetch the latest matching 
+versions (according to your `composer.json` file) and also update the lock file 
+with the new version.
 
 ```sh
 php composer.phar update
@@ -125,7 +128,7 @@ If you only want to install or update one dependency, you can whitelist them:
 php composer.phar update monolog/monolog [...]
 ```
 
-> **Note:** For libraries it is not necessarily recommended to commit the lock
+> **Note:** For libraries it is not necessary to commit the lock
 > file, see also: [Libraries - Lock file](02-libraries.md#lock-file).
 
 ## Packagist
@@ -135,12 +138,12 @@ repository is basically a package source: a place where you can get packages
 from. Packagist aims to be the central repository that everybody uses. This
 means that you can automatically `require` any package that is available there.
 
-If you go to the [packagist website](https://packagist.org/) (packagist.org),
+If you go to the [Packagist website](https://packagist.org/) (packagist.org),
 you can browse and search for packages.
 
-Any open source project using Composer should publish their packages on
-packagist. A library doesn't need to be on packagist to be used by Composer, but
-it makes life quite a bit simpler.
+Any open source project using Composer is recommended to publish their packages 
+on Packagist. A library doesn't need to be on Packagist to be used by Composer, 
+but it enables discovery and adoption by other developers more quickly.
 
 ## Autoloading
 
@@ -153,18 +156,17 @@ require 'vendor/autoload.php';
 ```
 
 This makes it really easy to use third party code. For example: If your project
-depends on monolog, you can just start using classes from it, and they will be
+depends on Monolog, you can just start using classes from it, and they will be
 autoloaded.
 
 ```php
 $log = new Monolog\Logger('name');
 $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
-
 $log->addWarning('Foo');
 ```
 
-You can even add your own code to the autoloader by adding an `autoload` field
-to `composer.json`.
+You can even add your own code to the autoloader by adding an 
+[`autoload`](04-schema.md#autoload) field to `composer.json`.
 
 ```json
 {
@@ -181,8 +183,9 @@ You define a mapping from namespaces to directories. The `src` directory would
 be in your project root, on the same level as `vendor` directory is. An example
 filename would be `src/Foo.php` containing an `Acme\Foo` class.
 
-After adding the `autoload` field, you have to re-run `dump-autoload` to
-re-generate the `vendor/autoload.php` file.
+After adding the [`autoload`](04-schema.md#autoload) field, you have to re-run 
+[`dump-autoload`](03-cli.md#dump-autoload) to re-generate the 
+`vendor/autoload.php` file.
 
 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.
@@ -193,9 +196,9 @@ $loader = require 'vendor/autoload.php';
 $loader->add('Acme\\Test\\', __DIR__);
 ```
 
-In addition to PSR-4 autoloading, classmap is also supported. This allows
-classes to be autoloaded even if they do not conform to PSR-4. See the [autoload
-reference](04-schema.md#autoload) for more details.
+In addition to PSR-4 autoloading, Composer also supports PSR-0, classmap and 
+files autoloading. See the [`autoload`](04-schema.md#autoload) reference for 
+more information.
 
 > **Note:** Composer provides its own autoloader. If you don't want to use that
 > one, you can just include `vendor/composer/autoload_*.php` files, which return

doc/02-libraries.md

@@ -1,16 +1,17 @@
 # Libraries
 
-This chapter will tell you how to make your library installable through Composer.
+This chapter will tell you how to make your library installable through
+Composer.
 
 ## Every project is a package
 
 As soon as you have a `composer.json` in a directory, that directory is a
-package. When you add a `require` to a project, you are making a package that
-depends on other packages. The only difference between your project and
-libraries is that your project is a package without a name.
+package. When you add a [`require`](04-schema.md#require) to a project, you are
+making a package that depends on other packages. The only difference between
+your project and libraries is that your project is a package without a name.
 
 In order to make that package installable you need to give it a name. You do
-this by adding a `name` to `composer.json`:
+this by adding the [`name`](04-schema.md#name) property in `composer.json`:
 
 ```json
 {
@@ -21,12 +22,12 @@ this by adding a `name` to `composer.json`:
 }
 ```
 
-In this case the project name is `acme/hello-world`, where `acme` is the
-vendor name. Supplying a vendor name is mandatory.
+In this case the project name is `acme/hello-world`, where `acme` is the vendor
+name. Supplying a vendor name is mandatory.
 
 > **Note:** If you don't know what to use as a vendor name, your GitHub
-username is usually a good bet. While package names are case insensitive, the
-convention is all lowercase and dashes for word separation.
+> username is usually a good bet. While package names are case insensitive, the
+> convention is all lowercase and dashes for word separation.
 
 ## Platform packages
 
@@ -50,15 +51,14 @@ includes PHP itself, PHP extensions and some system libraries.
   PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
   `openssl`, `pcre`, `uuid`, `xsl`.
 
-You can use `composer show --platform` to get a list of your locally available
-platform packages.
+You can use [`show --platform`](03-cli.md#show) to get a list of your locally
+available platform packages.
 
 ## Specifying the version
 
-You need to specify the package's version some way. When you publish your
-package on Packagist, it is able to infer the version from the VCS (git, svn,
-hg) information, so in that case you do not have to specify it, and it is
-recommended not to. See [tags](#tags) and [branches](#branches) to see how
+When you publish your package on Packagist, it is able to infer the version
+from the VCS (git, svn, hg) information. This means you don't have to
+explicitly declare it. Read [tags](#tags) and [branches](#branches) to see how
 version numbers are extracted from these.
 
 If you are creating packages by hand and really have to specify it explicitly,
@@ -76,9 +76,9 @@ you can just add a `version` field:
 ### Tags
 
 For every tag that looks like a version, a package version of that tag will be
-created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix
-of `-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffixes
-can also be followed by a number.
+created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix of
+`-patch` (`-p`), `-alpha` (`-a`), `-beta` (`-b`) or `-RC`. The suffix can also
+be followed by a number.
 
 Here are a few examples of valid tag names:
 
@@ -89,19 +89,20 @@ Here are a few examples of valid tag names:
 - v2.0.0-alpha
 - v2.0.4-p1
 
-> **Note:** Even if your tag is prefixed with `v`, a [version constraint](01-basic-usage.md#package-versions)
-> in a `require` statement has to be specified without prefix
-> (e.g. tag `v1.0.0` will result in version `1.0.0`). 
+> **Note:** Even if your tag is prefixed with `v`, a
+> [version constraint](01-basic-usage.md#package-versions) in a `require`
+> statement has to be specified without prefix (e.g. tag `v1.0.0` will result
+> in version `1.0.0`).
 
 ### Branches
 
 For every branch, a package development version will be created. If the branch
 name looks like a version, the version will be `{branchname}-dev`. For example,
-the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for technical
-reasons, to make sure it is recognized as a branch). The `2.0.x` branch would also
-be valid and be turned into `2.0.x-dev` as well. If the branch does not look
-like a version, it will be `dev-{branchname}`. `master` results in a
-`dev-master` version.
+the branch `2.0` will get the `2.0.x-dev` version (the `.x` is added for
+technical reasons, to make sure it is recognized as a branch). The `2.0.x`
+branch would also be valid and be turned into `2.0.x-dev` as well. If the
+branch does not look like a version, it will be `dev-{branchname}`. `master`
+results in a `dev-master` version.
 
 Here are some examples of version branch names:
 
@@ -116,8 +117,8 @@ Here are some examples of version branch names:
 ### Aliases
 
 It is possible to alias branch names to versions. For example, you could alias
-`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in all
-the packages.
+`dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in
+all the packages.
 
 See [Aliases](articles/aliases.md) for more information.
 
@@ -133,7 +134,7 @@ the `.gitignore`.
 
 ## Publishing to a VCS
 
-Once you have a vcs repository (version control system, e.g. git) containing a
+Once you have a VCS repository (version control system, e.g. git) containing a
 `composer.json` file, your library is already composer-installable. In this
 example we will publish the `acme/hello-world` library on GitHub under
 `github.com/username/hello-world`.
@@ -180,11 +181,11 @@ For more details on how package repositories work and what other types are
 available, see [Repositories](05-repositories.md).
 
 That's all. You can now install the dependencies by running Composer's
-`install` command!
+[`install`](03-cli.md#install) command!
 
 **Recap:** Any git/svn/hg repository containing a `composer.json` can be added
 to your project by specifying the package repository and declaring the
-dependency in the `require` field.
+dependency in the [`require`](04-schema.md#require) field.
 
 ## Publishing to packagist
 
@@ -196,15 +197,16 @@ repository for `monolog/monolog`. How did that work? The answer is Packagist.
 
 [Packagist](https://packagist.org/) is the main package repository for
 Composer, and it is enabled by default. Anything that is published on
-Packagist is available automatically through Composer. Since monolog
-[is on packagist](https://packagist.org/packages/monolog/monolog), we can depend
-on it without having to specify any additional repositories.
+Packagist is available automatically through Composer. Since
+[Monolog is on Packagist](https://packagist.org/packages/monolog/monolog), we
+can depend on it without having to specify any additional repositories.
 
 If we wanted to share `hello-world` with the world, we would publish it on
 Packagist as well. Doing so is really easy.
 
-You simply hit the big "Submit Package" button and sign up. Then you submit
-the URL to your VCS repository, at which point Packagist will start crawling
-it. Once it is done, your package will be available to anyone.
+You simply visit [Packagist](https://packagist.org) and hit the "Submit". This
+will prompt you to sign up if you haven't already, and then allows you to
+submit the URL to your VCS repository, at which point Packagist will start
+crawling it. Once it is done, your package will be available to anyone!
 
 ← [Basic usage](01-basic-usage.md) |  [Command-line interface](03-cli.md) →