Merge pull request #452 from weaverryan/beginning-doc-changes

Proofreading the first and second chapters of the very well-written docs

doc/00-intro.md

@@ -1,23 +1,30 @@
 # Introduction
 
 Composer is a tool for dependency management in PHP. It allows you to declare
-the dependencies of your project and will install them for you.
+the dependent libraries your project needs and it will install them in your
+project for you.
 
 ## Dependency management
 
-One important distinction to make is that composer is not a package manager. It
+Composer is not a package manager. Yes, it deals with "packages" or libraries, but
-deals with packages, but it manages them on a per-project basis. By default it
+it manages them on a per-project basis, installing them in a directory (e.g. `vendor`)
-will never install anything globally. Thus, it is a dependency manager.
+inside your project. By default it will never install anything globally. Thus,
+it is a dependency manager.
 
-This idea is not new by any means. Composer is strongly inspired by
+This idea is not new and Composer is strongly inspired by node's [npm](http://npmjs.org/)
-node's [npm](http://npmjs.org/) and ruby's [bundler](http://gembundler.com/).
+and ruby's [bundler](http://gembundler.com/). But there has not been such a tool
-But there has not been such a tool for PHP so far.
+for PHP.
 
-The problem that composer solves is the following. You have a project that
+The problem that Composer solves is this:
-depends on a number of libraries. Some of those libraries have dependencies of
+
-their own. You declare the things you depend on. Composer will then go ahead
+a) You have a project that depends on a number of libraries.
-and find out which versions of which packages need to be installed, and
+
-install them.
+b) Some of those libraries depend on other libraries .
+
+c) You declare the things you depend on
+
+d) Composer finds out which versions of which packages need to be installed, and
+   installs them (meaning it downloads them into your project).
 
 ## Declaring dependencies
 
@@ -32,37 +39,50 @@ which describes the project's dependencies.
         }
     }
 
-We are simply stating that our project requires the `monolog/monolog` package,
+We are simply stating that our project requires some `monolog/monolog` package,
 any version beginning with `1.0`.
 
 ## Installation
 
-To actually get it, we need to do two things. The first one is installing
+### 1) Downloading the Composer Executable
-composer:
+
+To actually get Composer, we need to do two things. The first one is installing
+Composer (again, this mean downloading it into your project):
 
     $ 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 file is the composer binary.
+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.
 
-You can install composer to a specific directory by using the `--install-dir`
+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):
 
     $ curl -s http://getcomposer.org/installer | php -- --install-dir=bin
 
-After that we run the command for installing all dependencies:
+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
+executable and invoke it without `php`.
+
+### 2) Using Composer
+
+Next, run the command the `install` command to resolve and download dependencies:
 
     $ php composer.phar install
 
-This will download monolog and dump it into `vendor/monolog/monolog`.
+This will download monolog into the `vendor/monolog/monolog` directory.
 
 ## Autoloading
 
-After this you can just add the following line to your bootstrap code to get
+Besides downloading the library, Composer also prepares an autoload file that's
-autoloading:
+capable of autoloading all of the classes in any of the libraries that it
+downloads. To use it, just add the following line to your code's bootstrap
+process:
 
     require 'vendor/.composer/autoload.php';
 
-That's all it takes to have a basic setup.
+Woh! Now start using monolog! To keep learning more about Composer, keep
+reading the "Basic Usage" chapter.
 
 [Basic Usage](01-basic-usage.md) →

doc/01-basic-usage.md

@@ -2,49 +2,36 @@
 
 ## Installation
 
-To install composer, simply run this command on the command line:
+To install Composer, you just need to download the `composer.phar` executable.
 
     $ curl -s http://getcomposer.org/installer | php
 
-This will perform some checks on your environment to make sure you can
+For the details, see the [Introduction](00-intro.md) chapter.
-actually run it.
 
-Then it will download `composer.phar` and place it in your working directory.
+To check if Composer is working, just run the PHAR through `php`:
-`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
-executable and invoke it without `php`.
-
-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):
-
-    $ curl -s http://getcomposer.org/installer | php -- --install-dir=bin
-
-To check if composer is working, just run the PHAR through `php`:
 
     $ php composer.phar
 
 This should give you a list of available commands.
 
-> **Note:** You can also perform the checks only without downloading composer
+> **Note:** You can also perform the checks only without downloading Composer
 > by using the `--check` option. For more information, just use `--help`.
 >
 >     $ curl -s http://getcomposer.org/installer | php -- --help
 
-## Project setup
+## `composer.json`: Project Setup
 
-To start using composer in your project, all you need is a `composer.json`
+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
-`require` key. You're simply telling composer which packages your project
+`require` key. You're simply telling Composer which packages your project
 depends on.
 
     {
@@ -53,12 +40,13 @@ depends on.
         }
     }
 
-As you can see, `require` takes an object that maps package names to versions.
+As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`)
+to **package versions** (e.g. `1.0.*`).
 
-## Package names
+### Package Names
 
 The package name consists of a vendor name and the project's name. Often these
-will be identical. The vendor name exists to prevent naming clashes. It allows
+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`.
 
@@ -68,10 +56,10 @@ allows adding more related projects under the same namespace later on. If you
 are maintaining a library, this would make it really easy to split it up into
 smaller decoupled parts.
 
-## Package versions
+### Package Versions
 
-We are also requiring the version `1.0.*` of monolog. This means any version
+We are requiring version `1.0.*` of monolog. This means any version in the `1.0`
-in the `1.0` development branch. It would match `1.0.0`, `1.0.2` and `1.0.20`.
+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.
 
@@ -80,14 +68,14 @@ Version constraints can be specified in a few different ways.
 
 * **Range:** By using comparison operators you can specify ranges of valid
   versions. Valid operators are `>`, `>=`, `<`, `<=`. An example range would be
-  `>=1.0`. You can define multiple of these, separated by comma:   `>=1.0,<2.0`.
+  `>=1.0`. You can define multiple ranges, separated by a comma:   `>=1.0,<2.0`.
 
 * **Wildcard:** You can specify a pattern with a `*` wildcard. `1.0.*` is the
   equivalent of `>=1.0,<1.1-dev`.
 
-## Installing dependencies
+## Installing Dependencies
 
-To fetch the defined dependencies into the local project, you simply run the
+To fetch the defined dependencies into your local project, just run the
 `install` command of `composer.phar`.
 
     $ php composer.phar install
@@ -104,29 +92,33 @@ In case of monolog it will put it into `vendor/monolog/monolog`.
 Another thing that the `install` command does is it adds a `composer.lock`
 file into your project root.
 
-## Lock file
+## `composer.lock` - The Lock File
 
-After installing the dependencies, composer writes the list of the exact
+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 project's `composer.lock` into version control.**
+**Commit your project's `composer.lock` (along with `composer.json`) into version control.**
 
-The reason is that anyone who sets up the project should get the same version.
+This is important because the `install` command checks if a lock file is present,
-The `install` command will check if a lock file is present. If it is, it will
+and if it is, it downloads the versions specified there (regardless of what `composer.json`
-use the versions specified there. If not, it will resolve the dependencies and
+says). This means that anyone who sets up the project will download the exact
-create a lock file.
+same version of the dependencies. 
 
-If any of the dependencies gets a new version, you can update to that version
+If no `composer.json` lock file exists, it will read the dependencies and
-by using the `update` command. This will fetch the latest matching versions and
+versions from `composer.json` and  create the lock file.
-also update the lock file.
+
+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 `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.
 
     $ php composer.phar update
 
 ## Packagist
 
-[Packagist](http://packagist.org/) is the main composer repository. A composer
+[Packagist](http://packagist.org/) is the main Composer repository. A Composer
-repository is basically a package source. A place where you can get packages
+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.
@@ -134,20 +126,20 @@ there.
 If you go to the [packagist website](http://packagist.org/) (packagist.org),
 you can browse and search for packages.
 
-Any open source project using composer should publish their packages on
+Any open source project using Composer should publish their packages on
-packagist.
+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 follow the [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
-naming standard, composer generates a
+naming standard, Composer generates a `vendor/.composer/autoload.php` file
-`vendor/.composer/autoload.php` file for autoloading. You can simply include
+for autoloading. You can simply include this file and you will get autoloading
-this file and you will get autoloading for free.
+for free.
 
     require 'vendor/.composer/autoload.php';
 
-This makes it really easy to use third party code, because you only
+This makes it really easy to use third party code: For monolog, it
-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.