Merge pull request #573 from igorw/improve-docs

Improve docs

doc/01-basic-usage.md

@@ -103,7 +103,7 @@ to those specific versions.
 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 means that anyone who sets up the project will download the exact
-same version of the dependencies. 
+same version of the dependencies.
 
 If no `composer.json` lock file exists, it will read the dependencies and
 versions from `composer.json` and  create the lock file.
@@ -135,16 +135,15 @@ but it makes life quite a bit simpler.
 
 ## Autoloading
 
-For libraries that follow the [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
-naming standard, Composer generates a `vendor/.composer/autoload.php` file
-for autoloading. You can simply include this file and you will get autoloading
-for free.
+For libraries that specify autoload information, Composer generates a
+`vendor/.composer/autoload.php` file. You can simply include this file and you
+will get autoloading for free.
 
     require 'vendor/.composer/autoload.php';
 
-This makes it really easy to use third party code: For monolog, it
-means that we can just start using classes from it, and they will be
-autoloaded.
+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 autoloaded.
 
     $log = new Monolog\Logger('name');
     $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
@@ -160,8 +159,12 @@ 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`
+Composer will register a
+[PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
+autoloader for the `Acme` namespace.
+
+You define 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 an `Acme\Foo` class.
 
 After adding the `autoload` field, you have to re-run `install` to re-generate
@@ -174,6 +177,10 @@ This can be useful for autoloading classes in a test suite, for example.
     $loader = require 'vendor/.composer/autoload.php';
     $loader->add('Acme\Test', __DIR__);
 
+In addition to PSR-0 autoloading, classmap is also supported. This allows
+classes to be autoloaded even if they do not conform to PSR-0. See the
+[autoload reference](04-schema.md#autoload) for more details.
+
 > **Note:** Composer provides its own autoloader. If you don't want to use
 that one, you can just include `vendor/.composer/autoload_namespaces.php`,
 which returns an associative array mapping namespaces to directories.

doc/02-libraries.md

@@ -151,11 +151,11 @@ packagist is available automatically through composer. Since monolog
 [is on packagist](http://packagist.org/packages/monolog/monolog), we can depend
 on it without having to specify any additional repositories.
 
-Assuming we want to share `hello-world` with the world, we would want to
-publish it on packagist as well. And this is really easy.
+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.
 
-← [Basic usage](01-basic-usage.md) |  [Command-line interface](03-cli.md) →
+← [Basic usage](01-basic-usage.md) |  [Command-line interface](03-cli.md) →

doc/03-cli.md

@@ -142,6 +142,34 @@ command. It will replace your `composer.phar` with the latest version.
 
     $ php composer.phar self-update
 
+## create-project
+
+You can use Composer to create new projects from an existing package.
+There are several applications for this:
+
+1. You can deploy application packages.
+2. You can check out any package and start developing on patches for example.
+3. Projects with multiple developers can use this feature to bootstrap the
+   initial application for development.
+
+To create a new project using composer you can use the "create-project" command.
+Pass it a package name, and the directory to create the project in. You can also
+provide a version as third argument, otherwise the latest version is used.
+
+The directory is not allowed to exist, it will be created during installation.
+
+    php composer.phar create-project doctrine/orm path 2.2.0
+
+By default the command checks for the packages on packagist.org.
+
+### Options
+
+* **--repository-url:** Provide a custom repository to search for the package,
+  which will be used instead of packagist. Can be either an HTTP URL pointing
+  to a `composer` repository, or a path to a local `packages.json` file.
+* **--prefer-source:** Get a development version of the code checked out
+  from version control.
+
 ## help
 
 To get more information about a certain command, just use `help`.
@@ -190,4 +218,4 @@ some tools like git or curl will only use the lower-cased `http_proxy` version.
 Alternatively you can also define the git proxy using
 `git config --global http.proxy <proxy url>`.
 
-&larr; [Libraries](02-libraries.md)  |  [Schema](04-schema.md) &rarr;
+&larr; [Libraries](02-libraries.md)  |  [Schema](04-schema.md) &rarr;

doc/04-schema.md

@@ -1,17 +1,27 @@
 # composer.json
 
-This chapter will explain all of the options available in `composer.json`.
+This chapter will explain all of the fields available in `composer.json`.
 
 ## JSON schema
 
 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:
-[`Resources/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json).
+[`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json).
 
-## Package root
+## Root Package
 
-The root of the package definition is a JSON object.
+The root package is the package defined by the `composer.json` at the root of
+your project. It is the main `composer.json` that defines your project
+requirements.
+
+Certain fields only apply when in the root package context. One example of
+this is the `config` field. Only the root package can define configuration.
+The config of dependencies is ignored. This makes the `config` field
+`root-only`.
+
+If you clone one of those dependencies to work on it, then that package is the
+root package. The `composer.json` is identical, but the context is different.
 
 ## Properties
 
@@ -155,7 +165,7 @@ An example:
 
 Optional, but highly recommended.
 
-### Link types
+### Link types <span>(require, recommend, suggest, replace, provide)</span>
 
 Each of these takes an object which maps package names to version constraints.
 
@@ -188,7 +198,7 @@ Optional.
 Autoload mapping for a PHP autoloader.
 
 Currently [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
-autoloading and ClassMap generation are supported.
+autoloading and classmap generation are supported.
 
 Under the `psr-0` key you define a mapping from namespaces to paths, relative to the
 package root.
@@ -212,7 +222,7 @@ you can specify them as an array as such:
     }
 
 You can use the classmap generation support to define autoloading for all libraries
-that do not follow "PSR-0". To configure this you specify all directories
+that do not follow PSR-0. To configure this you specify all directories
 to search for classes.
 
 Example:
@@ -235,6 +245,8 @@ Example:
         "include-path": ["lib/"]
     }
 
+Optional.
+
 ### target-dir
 
 Defines the installation target.
@@ -260,7 +272,7 @@ To do that, `autoload` and `target-dir` are defined as follows:
 
 Optional.
 
-### repositories
+### repositories <span>(root-only)</span>
 
 Custom package repositories to use.
 
@@ -326,7 +338,7 @@ will look from the first to the last repository, and pick the first match.
 By default Packagist is added last which means that custom repositories can
 override packages from it.
 
-### config
+### config <span>(root-only)</span>
 
 A set of configuration options. It is only used for projects.
 
@@ -348,7 +360,7 @@ Example:
         }
     }
 
-### scripts
+### scripts <span>(root-only)</span>
 
 Composer allows you to hook into various parts of the installation process
 through the use of scripts.

doc/05-repositories.md

@@ -274,4 +274,4 @@ You can disable the default Packagist repository by adding this to your
     }
 
 
-← [Schema](04-schema.md)  |  [Community](06-community.md) →
+← [Schema](04-schema.md)  |  [Community](06-community.md) →

doc/06-community.md

@@ -27,4 +27,4 @@ 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.
 
-← [Repositories](05-repositories.md)
+← [Repositories](05-repositories.md)

doc/articles/create-projects.md

@@ -1,23 +0,0 @@
-# Create Projects
-
-You can use Composer to create new projects from an existing package.
-There are several applications for this:
-
-1. You can deploy application packages.
-2. You can check out any package and start developing on patches for example.
-3. Projects with multiple developers can use this feature to bootstrap the initial application for development.
-
-To create a new project using composer you can use the "create-project" command.
-Pass it a package name, and the directory to create the project in. You can also
-provide a version as third argument, otherwise the latest version is used.
-
-The directory is not allowed to exist, it will be created during installation.
-
-    php composer.phar create-project doctrine/orm path 2.2.0
-
-By default the command checks for the packages on packagist.org. To change this behavior
-you can use the --repository-url parameter and either point it to an HTTP url
-for your own packagist repository or to a packages.json file.
-
-If you want to get a development version of the code directly checked out
-from version control you have to add the --prefer-source parameter.

doc/articles/custom-installers.md

@@ -1,5 +1,5 @@
 <!--
-    tagline: Custom installers can be used to modify the way some packages are installed
+    tagline: Modify the way certain types of packages are installed
 -->
 # Setting up and using custom installers
 

doc/articles/handling-private-packages-with-satis.md

@@ -1,3 +1,6 @@
+<!--
+    tagline: Host your own composer repository
+-->
 # Handling private packages with Satis
 
 Satis can be used to host the metadata of your company's private packages, or

doc/articles/packagist-update-schedule.md

@@ -1,25 +0,0 @@
-# Packagist Update Schedule
-
-## How often does Packagist crawl newly added packages?
-
-New packages will be crawled **within ten minutes**.
-
-
-## How often does Packagist crawl existing packages?
-
-Existing packages will be crawled **every hour**.
-
-
-## How often does the Packagist search index update?
-
-The search index is updated **every five minutes**. It will index (or reindex)
-any package that has been crawled since the last time the search
-indexer ran.
-
-
-## Can Packagist be triggered to recrawl a package (on commit or by other means)?
-
-Yes, you can click the "Force update" button on your package page if you are
-logged in as a maintainer. The recommended way is to set up the GitHub hook,
-you can find the URL and instructions on your Packagist
-[profile](http://packagist.org/profile/) page.

doc/articles/vendor-bins.md

@@ -1,3 +1,6 @@
+<!--
+    tagline: Expose command-line scripts from packages
+-->
 # bin and vendor/bin
 
 ## What is a bin?
@@ -99,4 +102,4 @@ An example of the former looks like this:
 
 Running `composer install` for this `composer.json` will result in
 all of the vendor bins being installed in `scripts/` instead of
-`vendor/bin/`.
+`vendor/bin/`.