tweaked the README files

src/Symfony/Bridge/Doctrine/README.md

@@ -1,7 +1,8 @@
 Doctrine Bridge
 ===============
 
-Provides integration for Doctrine with various Symfony2 components.
+Provides integration for [Doctrine](http://www.doctrine-project.org/) with
+various Symfony2 components.
 
 Resources
 ---------

src/Symfony/Bridge/Twig/README.md

@@ -1,7 +1,8 @@
 Twig Bridge
 ===========
 
-Provides integration for Twig with various Symfony2 components.
+Provides integration for [Twig](http://twig.sensiolabs.org/) with various
+Symfony2 components.
 
 Resources
 ---------

src/Symfony/Component/BrowserKit/README.md

@@ -1,11 +1,17 @@
 BrowserKit Component
 ====================
 
-This component provides classes to simulate a browser for testing.
+BrowserKit simulates the behavior of a web browser.
+
+The component only provide an abstract client and does not provide any
+"default" backend for the HTTP layer.
 
 Resources
 ---------
 
-Unit tests:
+For a simple implementation of a browser based on an HTTP layer, have a look
+at [Goutte](https://github.com/fabpot/Goutte).
 
-https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/BrowserKit
+For an implementation based on HttpKernelInterface, have a look at the
+[Client](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/Client.php)
+provided by the HttpKernel component.

src/Symfony/Component/ClassLoader/README.md

@@ -1,41 +1,60 @@
 ClassLoader Component
 =====================
 
-The ClassLoader component provides an autoloader that implements the PSR-0 standard
-(which is a standard way to autoload namespaced classes as available in PHP 5.3).
-It is also able to load classes that use the PEAR naming convention. It is really
-flexible as it can look for classes in different directories based on a sub-namespace.
-You can even give more than one directory for one namespace:
-
-```
-require_once __DIR__.'/src/Symfony/Component/ClassLoader/UniversalClassLoader.php';
-
-use Symfony\Component\ClassLoader\UniversalClassLoader;
-
-$loader = new UniversalClassLoader();
-$loader->registerNamespaces(array(
-    'Symfony'          => array(__DIR__.'/src', __DIR__.'/symfony/src'),
-    'Doctrine\\Common' => __DIR__.'/vendor/doctrine-common/lib',
-    'Doctrine\\DBAL'   => __DIR__.'/vendor/doctrine-dbal/lib',
-    'Doctrine'         => __DIR__.'/vendor/doctrine/lib',
-    'Monolog'          => __DIR__.'/vendor/monolog/src',
-));
-$loader->registerPrefixes(array(
-    'Twig_' => __DIR__.'/vendor/twig/lib',
-));
-$loader->register();
-```
-
-Most of the time, the Symfony2 ClassLoader is all you need to autoload all your project classes.
-And for better performance, you can use an APC cached version of the universal class loader or
-the map class loader.
-
-Furthermore it provides tools to aggregate classes into a single file, which is especially
-useful to improve performance on servers that do not provide byte caches.
-
-Resources
----------
-
-Unit tests:
-
-https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/ClassLoader
+ClassLoader loads your project classes automatically if they follow some
+standard PHP conventions.
+
+The Universal ClassLoader is able to autoload classes that implement the PSR-0
+standard or the PEAR naming convention.
+
+First, register the autoloader:
+
+    require_once __DIR__.'/src/Symfony/Component/ClassLoader/UniversalClassLoader.php';
+
+    use Symfony\Component\ClassLoader\UniversalClassLoader;
+
+    $loader = new UniversalClassLoader();
+    $loader->register();
+
+Then, register some namespaces with the `registerNamespace()` method:
+
+    $loader->registerNamespace('Symfony', __DIR__.'/src');
+    $loader->registerNamespace('Monolog', __DIR__.'/vendor/monolog/src');
+
+The `registerNamespace()` method takes a namespace prefix and a path where to
+look for the classes as arguments.
+
+You can also register a sub-namespaces:
+
+    $loader->registerNamespace('Doctrine\\Common', __DIR__.'/vendor/doctrine-common/lib');
+
+The order of registration is significant and the first registered namespace
+takes precedence over later registered one.
+
+You can also register more than one path for a given namespace:
+
+    $loader->registerNamespace('Symfony', array(__DIR__.'/src', __DIR__.'/symfony/src'));
+
+Alternatively, you can use the `registerNamespaces()` method to register more
+than one namespace at once:
+
+    $loader->registerNamespaces(array(
+        'Symfony'          => array(__DIR__.'/src', __DIR__.'/symfony/src'),
+        'Doctrine\\Common' => __DIR__.'/vendor/doctrine-common/lib',
+        'Doctrine'         => __DIR__.'/vendor/doctrine/lib',
+        'Monolog'          => __DIR__.'/vendor/monolog/src',
+    ));
+
+For better performance, you can use the APC based version of the universal
+class loader:
+
+    require_once __DIR__.'/src/Symfony/Component/ClassLoader/UniversalClassLoader.php';
+    require_once __DIR__.'/src/Symfony/Component/ClassLoader/ApcUniversalClassLoader.php';
+
+    use Symfony\Component\ClassLoader\ApcUniversalClassLoader;
+
+    $loader = new ApcUniversalClassLoader('apc.prefix.');
+
+Furthermore, the component provides tools to aggregate classes into a single
+file, which is especially useful to improve performance on servers that do not
+provide byte caches.

src/Symfony/Component/Config/README.md

@@ -1,10 +1,10 @@
 Config Component
 ================
 
-This component provides infrastructure from loading configurations from different
-data sources and optionally monitoring these data sources for changes. There are
-additional tools for validating, normalizing and handling of defaults that can
-optionally be used to convert from different formats to arrays.
+Config provides the infrastructure for loading configurations from different
+data sources and optionally monitoring these data sources for changes. There
+are additional tools for validating, normalizing and handling of defaults that
+can optionally be used to convert from different formats to arrays.
 
 Resources
 ---------

src/Symfony/Component/Console/README.md

@@ -1,40 +1,44 @@
 Console Component
 =================
 
-Even if we are talking about a web framework, having some tools to manage
-your project from the command line is nice. In Symfony2, we use the console
-to generate CRUDs, update the database schema, etc. It's not required, but
-it is really convenient and it can boost your productivity a lot.
-
-This example shows how to create a command line tool very easily:
-
-```
-use Symfony\Component\Console\Application;
-use Symfony\Component\Console\Input\InputInterface;
-use Symfony\Component\Console\Input\InputArgument;
-use Symfony\Component\Console\Input\InputOption;
-use Symfony\Component\Console\Output\OutputInterface;
-
-$console = new Application();
-$console
-    ->register('ls')
-    ->setDefinition(array(
-        new InputArgument('dir', InputArgument::REQUIRED, 'Directory name'),
-    ))
-    ->setDescription('Displays the files in the given directory')
-    ->setCode(function (InputInterface $input, OutputInterface $output) {
-        $dir = $input->getArgument('dir');
-
-        $output->writeln(sprintf('Dir listing for <info>%s</info>', $dir));
-    })
-;
-
-$console->run();
-```
-
-With only 10 lines of code or so, you have access to a lot of features like output
-coloring, input and output abstractions (so that you can easily unit-test your
-commands), validation, automatic help messages, and a lot more. It's really powerful.
+Console eases the creation of beautiful and testable command line interfaces.
+
+The Application object manages the CLI application:
+
+    use Symfony\Component\Console\Application;
+
+    $console = new Application();
+    $console->run();
+
+The ``run()`` method parses the arguments and options passed on the command
+line and executes the right command.
+
+Registering a new command can easily be done via the ``register()`` method,
+which returns a ``Command`` instance:
+
+    use Symfony\Component\Console\Input\InputInterface;
+    use Symfony\Component\Console\Input\InputArgument;
+    use Symfony\Component\Console\Input\InputOption;
+    use Symfony\Component\Console\Output\OutputInterface;
+
+    $console
+        ->register('ls')
+        ->setDefinition(array(
+            new InputArgument('dir', InputArgument::REQUIRED, 'Directory name'),
+        ))
+        ->setDescription('Displays the files in the given directory')
+        ->setCode(function (InputInterface $input, OutputInterface $output) {
+            $dir = $input->getArgument('dir');
+
+            $output->writeln(sprintf('Dir listing for <info>%s</info>', $dir));
+        })
+    ;
+
+You can also register new commands via classes.
+
+The component provides a lot of features like output coloring, input and
+output abstractions (so that you can easily unit-test your commands),
+validation, automatic help messages, ...
 
 Resources
 ---------

src/Symfony/Component/CssSelector/README.md

@@ -1,38 +1,23 @@
 CssSelector Component
 =====================
 
-This component is a port of the Python lxml library, which is copyright Infrae
-and distributed under the BSD license.
-
-Current code is a port of http://codespeak.net/svn/lxml/trunk/src/lxml/cssselect.py@71545
-
-Using CSS selectors is far easier than using XPath.
-
-Its only goal is to convert a CSS selector to its XPath equivalent:
-
-```
-use Symfony\Component\CssSelector\CssSelector;
-
-print CssSelector::toXPath('div.item > h4 > a');
-```
+CssSelector converts CSS selectors to XPath expressions.
 
-That way, you can just use CSS Selectors with the DomCrawler instead of XPath:
+The component only goal is to convert CSS selectors to their XPath
+equivalents:
 
-```
-use Symfony\Component\DomCrawler\Crawler;
+    use Symfony\Component\CssSelector\CssSelector;
 
-$crawler = new Crawler();
-$crawler->addContent('<html><body><p>Hello World!</p></body></html>');
-
-print $crawler->filter('body > p')->text();
-```
-
-By the way, that's one example of a component (DomCrawler) that relies
-on another one (CssSelector) for some optional features.
+    print CssSelector::toXPath('div.item > h4 > a');
 
 Resources
 ---------
 
 Unit tests:
 
 https://github.com/symfony/symfony/tree/master/tests/Symfony/Tests/Component/CssSelector
+
+This component is a port of the Python lxml library, which is copyright Infrae
+and distributed under the BSD license.
+
+Current code is a port of http://codespeak.net/svn/lxml/trunk/src/lxml/cssselect.py@71545

src/Symfony/Component/DependencyInjection/README.md

@@ -1,22 +1,22 @@
 DependencyInjection Component
 =============================
 
-Even the DependencyInjection component is really easy. It has many features, but its core
-is simple to use. See how easy it is to configure a service that relies on another service:
-
-```
-use Symfony\Component\DependencyInjection\ContainerBuilder;
-use Symfony\Component\DependencyInjection\Reference;
-
-$sc = new ContainerBuilder();
-$sc
-    ->register('foo', '%foo.class%')
-    ->addArgument(new Reference('bar'))
-;
-$sc->setParameter('foo.class', 'Foo');
-
-$sc->get('foo');
-```
+DependencyInjection manages your services via a robust and flexible Dependency
+Injection Container.
+
+Here is a simple example that shows how to register services and parameters:
+
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use Symfony\Component\DependencyInjection\Reference;
+
+    $sc = new ContainerBuilder();
+    $sc
+        ->register('foo', '%foo.class%')
+        ->addArgument(new Reference('bar'))
+    ;
+    $sc->setParameter('foo.class', 'Foo');
+
+    $sc->get('foo');
 
 Resources
 ---------

src/Symfony/Component/DomCrawler/README.md

@@ -1,17 +1,26 @@
 DomCrawler Component
 ====================
 
-If you are familiar with jQuery, DomCrawler is a PHP equivalent.
-It allows you to navigate the DOM of an HTML or XML document:
+DomCrawler eases DOM navigation for HTML and XML documents.
 
-```
-use Symfony\Component\DomCrawler\Crawler;
+If you are familiar with jQuery, DomCrawler is a PHP equivalent:
 
-$crawler = new Crawler();
-$crawler->addContent('<html><body><p>Hello World!</p></body></html>');
+    use Symfony\Component\DomCrawler\Crawler;
 
-print $crawler->filterXPath('descendant-or-self::body/p')->text();
-```
+    $crawler = new Crawler();
+    $crawler->addContent('<html><body><p>Hello World!</p></body></html>');
+
+    print $crawler->filterXPath('descendant-or-self::body/p')->text();
+
+If you are also using the CssSelector component, you can use CSS Selectors
+instead of XPath expressions:
+
+    use Symfony\Component\DomCrawler\Crawler;
+
+    $crawler = new Crawler();
+    $crawler->addContent('<html><body><p>Hello World!</p></body></html>');
+
+    print $crawler->filter('body > p')->text();
 
 Resources
 ---------

src/Symfony/Component/EventDispatcher/README.md

@@ -1,18 +1,19 @@
 EventDispatcher Component
 =========================
 
-```
-use Symfony\Component\EventDispatcher\EventDispatcher;
-use Symfony\Component\EventDispatcher\Event;
+EventDispatcher implements a lightweight version of the Observer design
+pattern.
 
-$dispatcher = new EventDispatcher();
+    use Symfony\Component\EventDispatcher\EventDispatcher;
+    use Symfony\Component\EventDispatcher\Event;
 
-$dispatcher->addListener('event_name', function (Event $event) {
-    // ...
-});
+    $dispatcher = new EventDispatcher();
 
-$dispatcher->dispatch('event_name');
-```
+    $dispatcher->addListener('event_name', function (Event $event) {
+        // ...
+    });
+
+    $dispatcher->dispatch('event_name');
 
 Resources
 ---------