reworking basic usage, added versions article

doc/00-intro.md

@@ -77,15 +77,16 @@ The installer will just check a few PHP settings and then download
 is a PHAR (PHP archive), which is an archive format for PHP which can be run on
 the command line, amongst other things.
 
+Now just run `php composer.phar` in order to run Composer.
+
 You can install Composer to a specific directory by using the `--install-dir`
-option and providing a target directory (it can be an absolute or relative
-path):
+option and additionally (re)name it as well using the `--filename` option:
 
 ```sh
-curl -sS https://getcomposer.org/installer | php -- --install-dir=bin
+curl -sS https://getcomposer.org/installer | php -- --install-dir=bin --filename=composer
 ```
 
-Now just run `php composer.phar` in order to run Composer.
+Now just run `php bin/composer` in order to run Composer.
 
 #### Globally
 

doc/01-basic-usage.md

@@ -1,8 +1,12 @@
 # Basic usage
 
-## Installing
+## Introduction
 
-If you have not yet installed Composer, refer to the [Intro](00-intro.md) chapter.
+If you have not yet installed Composer, refer to the [Intro](00-intro.md)
+chapter. For our basic usage introduction, we will be installing 
+`monolog/monolog`, a logging library. Note that for the sake of simplicity, 
+this introduction will assume you have performed a [local](00-intro.md#locally) 
+install of Composer.
 
 ## `composer.json`: Project Setup
 
@@ -10,9 +14,6 @@ To start using Composer in your project, all you need is a `composer.json`
 file. This file describes the dependencies of your project and may contain
 other metadata as well.
 
-The [JSON format](http://json.org/) is quite easy to write. It allows you to
-define nested structures.
-
 ### The `require` Key
 
 The first (and often only) thing you specify in `composer.json` is the
@@ -27,15 +28,15 @@ depends on.
 }
 ```
 
-As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`)
-to **package versions** (e.g. `1.0.*`).
+As you can see, `require` takes an object that maps **package names**
+(e.g. `monolog/monolog`) to **version constraints** (e.g. `1.0.*`).
 
 ### Package Names
 
 The package name consists of a vendor name and the project's name. Often these
-will be identical - the vendor name just exists to prevent naming clashes. It allows
-two different people to create a library named `json`, which would then just be
-named `igorw/json` and `seldaek/json`.
+will be identical - the vendor name just exists to prevent naming clashes. It
+allows two different people to create a library named `json`, which would then
+just be named `igorw/json` and `seldaek/json`.
 
 Here we are requiring `monolog/monolog`, so the vendor name is the same as the
 project's name. For projects with a unique name this is recommended. It also
@@ -45,53 +46,20 @@ smaller decoupled parts.
 
 ### Package Versions
 
-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 would match `1.0.0`,
-`1.0.2` or `1.0.20`.
-
-Version constraints can be specified in a few different ways.
-
-Name           | Example                                                                  | Description
--------------- | ------------------------------------------------------------------------ | -----------
-Exact version  | `1.0.2`                                                                  | You can specify the exact version of a package.
-Range          | `>=1.0` `>=1.0 <2.0` <code>&gt;=1.0 &lt;1.1 &#124;&#124; &gt;=1.2</code> | By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`, `!=`. <br />You can define multiple ranges. Ranges separated by a space (<code> </code>) or comma (`,`) will be treated as a **logical AND**. A double pipe (<code>&#124;&#124;</code>) will be treated as a **logical OR**. AND has higher precedence than OR.
-Hyphen Range   | `1.0 - 2.0`                                                              | Inclusive set of versions. Partial versions on the right include are completed with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the `2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to `>=1.0.0 <=2.1.0`.
-Wildcard       | `1.0.*`                                                                  | You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0 <1.1`.
-Tilde Operator | `~1.2`                                                                   | Very useful for projects that follow semantic versioning. `~1.2` is equivalent to `>=1.2 <2.0`. For more details, read the next section below.
-Caret Operator | `^1.2.3`                                                                 | Very useful for projects that follow semantic versioning. `^1.2.3` is equivalent to `>=1.2.3 <2.0`. For more details, read the next section below.
-
-### Next Significant Release (Tilde and Caret Operators)
-
-The `~` operator is best explained by example: `~1.2` is equivalent to
-`>=1.2 <2.0.0`, while `~1.2.3` is equivalent to `>=1.2.3 <1.3.0`. As you can see
-it is mostly useful for projects respecting [semantic
-versioning](http://semver.org/). A common usage would be to mark the minimum
-minor version you depend on, like `~1.2` (which allows anything up to, but not
-including, 2.0). Since in theory there should be no backwards compatibility
-breaks until 2.0, that works well. Another way of looking at it is that using
-`~` specifies a minimum version, but allows the last digit specified to go up.
-
-The `^` operator behaves very similarly but it sticks closer to semantic
-versioning, and will always allow non-breaking updates. For example `^1.2.3`
-is equivalent to `>=1.2.3 <2.0.0` as none of the releases until 2.0 should
-break backwards compatibility. For pre-1.0 versions it also acts with safety
-in mind and treats `^0.3` as `>=0.3.0 <0.4.0`
-
-> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint
-> like `~1.2` would not install it. As said above `~1.2` only means the `.2`
-> can change but the `1.` part is fixed.
-
-> **Note:** The `~` operator has an exception on its behavior for the major
-> release number. This means for example that `~1` is the same as `~1.0` as
-> it will not allow the major number to increase trying to keep backwards
-> compatibility.
+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
+equivalent of saying versions that match `>=1.0 <1.1`.
+
+Version constraints can be specified in several ways, read 
+[versions](articles/versions.md) for more in-depth information on this topic.
 
 ### Stability
 
-By default only stable releases are taken into consideration. If you would like
-to also get RC, beta, alpha or dev versions of your dependencies you can do
-so using [stability flags](04-schema.md#package-links). To change that for all
-packages instead of doing per dependency you can also use the
+By default only stable releases are taken into consideration. If you would
+like to also get RC, beta, alpha or dev versions of your dependencies you can
+do so using [stability flags](04-schema.md#package-links). To change that for
+all packages instead of doing per dependency you can also use the
 [minimum-stability](04-schema.md#minimum-stability) setting.
 
 If you are using range comparisons when selecting non-stable packages, and you
@@ -119,15 +87,15 @@ the `minimum-stability` setting and each package's stability flags.
 
 ### Test version constraints
 
-You can test version constraints using [semver.mwl.be](http://semver.mwl.be). Fill in
-a package name and it will autofill the default version constraint which Composer would add
-to your `composer.json` file. You can adjust the version constraint and the tool will highlight
-all releases that match.
+You can test version constraints using [semver.mwl.be](http://semver.mwl.be).
+Fill in a package name and it will autofill the default version constraint
+which Composer would add to your `composer.json` file. You can adjust the
+version constraint and the tool will highlight all releases that match.
 
 ## Installing Dependencies
 
-To fetch the defined dependencies into your local project, just run the
-`install` command of `composer.phar`.
+To install the defined dependencies for your project, just run the
+`install` command.
 
 ```sh
 php composer.phar install
@@ -139,11 +107,10 @@ 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
+> `vendor` in 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.
+You will notice the `install` command also created a `composer.lock` file.
 
 ## `composer.lock` - The Lock File
 
@@ -151,72 +118,72 @@ After installing the dependencies, Composer writes the list of the exact
 versions it installed into a `composer.lock` file. This locks the project
 to those specific versions.
 
-**Commit your application's `composer.lock` (along with `composer.json`) into version control.**
+**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` 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
-developers in your team, everything and everyone runs on the same dependencies, which
-mitigates the potential for bugs affecting only some parts of the deployments. Even if you
-develop alone, in six months when reinstalling the project you can feel confident the
-dependencies installed are still working even if your dependencies released
-many new versions since then.
+This means that anyone who sets up the project will download the exact same
+version of the dependencies. Your CI server, production machines, other
+developers in your team, everything and everyone runs on the same dependencies,
+which mitigates the potential for bugs affecting only some parts of the
+deployments. Even if you develop alone, in six months when reinstalling the
+project you can feel confident the dependencies installed are still working even
+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.
+versions from `composer.json` and  create the lock file after executing the
+`update` or the `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.
+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.
 
 ```sh
 php composer.phar update
 ```
-> **Note:** Composer will display a Warning when executing an `install` command if 
- `composer.lock` and `composer.json` are not synchronized.
- 
+> **Note:** Composer will display a Warning when executing an `install` command
+> if `composer.lock` and `composer.json` are not synchronized.
+
 If you only want to install or update one dependency, you can whitelist them:
 
 ```sh
 php composer.phar update monolog/monolog [...]
 ```
 
-> **Note:** For libraries it is not necessarily recommended to commit the lock file,
-> see also: [Libraries - Lock file](02-libraries.md#lock-file).
+> **Note:** For libraries it is not necessarily recommended to commit the lock
+> file, see also: [Libraries - Lock file](02-libraries.md#lock-file).
 
 ## Packagist
 
 [Packagist](https://packagist.org/) is the main Composer repository. A Composer
 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.
+means that you can automatically `require` any package that is available there.
 
 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.
+packagist. A library doesn't need to be on packagist to be used by Composer, but
+it makes life quite a bit simpler.
 
 ## Autoloading
 
 For libraries that specify autoload information, Composer generates a
-`vendor/autoload.php` file. You can simply include this file and you
-will get autoloading for free.
+`vendor/autoload.php` file. You can simply include this file and you will get
+autoloading for free.
 
 ```php
 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 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.
 
 ```php
 $log = new Monolog\Logger('name');
@@ -243,8 +210,8 @@ 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` field, you have to re-run `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.
@@ -256,11 +223,11 @@ $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.
+classes to be autoloaded even if they do not conform to PSR-4. 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_*.php` files,
-which return associative arrays allowing you to configure your own autoloader.
+> **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
+> associative arrays allowing you to configure your own autoloader.
 
 &larr; [Intro](00-intro.md)  |  [Libraries](02-libraries.md) &rarr;

doc/articles/versions.md

@@ -0,0 +1,99 @@
+<!--
+    tagline: The multitude of possibilities that are called version constraints.
+-->
+
+# Versions
+
+## Basic Constraints
+
+### Exact
+
+You can specify the exact version of a package. This will tell Composer to 
+install this version and this version only. If other dependencies require
+a different version, the solver will ultimately fail and abort any install
+or update procedures.
+
+Example: `1.0.2`
+
+### Range
+
+By using comparison operators you can specify ranges of valid versions. Valid 
+operators are `>`, `>=`, `<`, `<=`, `!=`. <br />You can define multiple ranges. 
+Ranges separated by a space (<code> </code>) or comma (`,`) will be treated as 
+a **logical AND**. A double pipe (<code>&#124;&#124;</code>) will be treated as 
+a **logical OR**. AND has higher precedence than OR.
+
+Example: `>=1.0` `>=1.0 <2.0` `>=1.0 <1.1 || >=1.2`
+
+### Range (Hyphen)
+
+Inclusive set of versions. Partial versions on the right include are completed 
+with a wildcard. For example `1.0 - 2.0` is equivalent to `>=1.0.0 <2.1` as the 
+`2.0` becomes `2.0.*`. On the other hand `1.0.0 - 2.1.0` is equivalent to 
+`>=1.0.0 <=2.1.0`.
+
+Example: `1.0 - 2.0`
+
+### Wildcard
+
+You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of 
+`>=1.0 <1.1`.
+
+Example: `1.0.*`
+
+## Next Significant Release Operators
+
+### Tilde
+
+The `~` operator is best explained by example: `~1.2` is equivalent to
+`>=1.2 <2.0.0`, while `~1.2.3` is equivalent to `>=1.2.3 <1.3.0`. As you can see
+it is mostly useful for projects respecting [semantic
+versioning](http://semver.org/). A common usage would be to mark the minimum
+minor version you depend on, like `~1.2` (which allows anything up to, but not
+including, 2.0). Since in theory there should be no backwards compatibility
+breaks until 2.0, that works well. Another way of looking at it is that using
+`~` specifies a minimum version, but allows the last digit specified to go up.
+
+Example: `~1.2`
+
+> **Note:** Though `2.0-beta.1` is strictly before `2.0`, a version constraint
+> like `~1.2` would not install it. As said above `~1.2` only means the `.2`
+> can change but the `1.` part is fixed.
+
+> **Note:** The `~` operator has an exception on its behavior for the major
+> release number. This means for example that `~1` is the same as `~1.0` as
+> it will not allow the major number to increase trying to keep backwards
+> compatibility.
+
+### Caret
+
+The `^` operator behaves very similarly but it sticks closer to semantic
+versioning, and will always allow non-breaking updates. For example `^1.2.3`
+is equivalent to `>=1.2.3 <2.0.0` as none of the releases until 2.0 should
+break backwards compatibility. For pre-1.0 versions it also acts with safety
+in mind and treats `^0.3` as `>=0.3.0 <0.4.0`.
+
+Example: `^1.2.3`
+
+## Stability
+
+If you are using a constraint that does not explicitly define a stability,
+Composer will default interally to `-dev` or `-stable`, depending on the
+operator(s) used. This happens transparently.
+
+If you wish to explicitly consider only the stable release in the comparison,
+add the suffix `-stable`.
+
+Examples:
+
+ Constraint         | Internally
+----------------------------------------------
+ `1.2.3`            | `=1.2.3.0-stable`
+ `>1.2`             | `>1.2.0.0-stable`
+ `>=1.2`            | `>=1.2.0.0-dev`
+ `>=1.2-stable`     | `>=1.2.0.0-stable`
+ `<1.3`             | `<1.3.0.0-dev`
+ `<=1.3`            | `<=1.3.0.0-stable`
+ `1 - 2`            | `>=1.0.0.0-dev <3.0.0.0-dev`
+ `~1.3`             | `>=1.3.0.0-dev <2.0.0.0-dev`
+ `1.4.*`            | `>=1.4.0.0-dev <1.5.0.0-dev`