Some doc fixes

doc/intro.rst

@@ -2,7 +2,7 @@ Introduction
 ============
 
 Silex is a PHP microframework for PHP 5.3. It is built on the shoulders of
-Symfony2 and Pimple and also inspired by sinatra.
+Symfony2 and Pimple and also inspired by Sinatra_.
 
 A microframework provides the guts for building simple single-file apps. Silex
 aims to be:
@@ -18,10 +18,12 @@ aims to be:
 
 In a nutshell, you define controllers and map them to routes, all in one step.
 
-**Let's go!**::
+Usage
+-----
 
-    // web/index.php
+.. code-block:: php
 
+    // web/index.php
     require_once __DIR__.'/../vendor/autoload.php';
 
     $app = new Silex\Application();
@@ -35,14 +37,21 @@ In a nutshell, you define controllers and map them to routes, all in one step.
 All that is needed to get access to the Framework is to include the
 autoloader.
 
-Next we define a route to ``/hello/{name}`` that matches for ``GET`` requests.
+Next a route for ``/hello/{name}`` that matches for ``GET`` requests is defined.
 When the route matches, the function is executed and the return value is sent
 back to the client.
 
 Finally, the app is run. Visit ``/hello/world`` to see the result. It's really
 that easy!
 
-Installing Silex is as easy as it can get. `Download`_ the archive file,
-extract it, and you're done!
+Installation
+------------
+
+Installing Silex is as easy as it can get. The recommend method is using
+Composer_ and requiring `silex/silex`_.  Another way is to `download`_ the
+archive file and extract it.
 
-.. _Download: http://silex.sensiolabs.org/download
+.. _Sinatra: http://www.sinatrarb.com/
+.. _Composer: http://getcomposer.org/
+.. _`download`: http://silex.sensiolabs.org/download
+.. _`silex/silex`: https://packagist.org/packages/silex/silex

doc/usage.rst

@@ -18,8 +18,8 @@ it, you should have the following directory structure:
     └── web
         └── index.php
 
-If you want more flexibility, use Composer instead. Create a
-``composer.json``:
+If you want more flexibility, use Composer_ instead. Create a
+``composer.json`` file and put this in it:
 
 .. code-block:: json
 
@@ -60,17 +60,16 @@ file and create an instance of ``Silex\Application``. After your controller
 definitions, call the ``run`` method on your application::
 
     // web/index.php
-
     require_once __DIR__.'/../vendor/autoload.php';
 
     $app = new Silex\Application();
 
-    // definitions
+    // ... definitions
 
     $app->run();
 
-Then, you have to configure your web server (read the :doc:`dedicated chapter
-<web_servers>` for more information).
+Then, you have to configure your web server (read the
+:doc:`dedicated chapter <web_servers>` for more information).
 
 .. tip::
 
@@ -81,9 +80,9 @@ Then, you have to configure your web server (read the :doc:`dedicated chapter
 
 .. tip::
 
-    If your application is hosted behind a reverse proxy at address $ip, and you
-    want Silex to trust the ``X-Forwarded-For*`` headers, you will need to run
-    your application like this::
+    If your application is hosted behind a reverse proxy at address ``$ip``,
+    and you want Silex to trust the ``X-Forwarded-For*`` headers, you will
+    need to run your application like this::
 
         use Symfony\Component\HttpFoundation\Request;
 
@@ -109,7 +108,7 @@ A route pattern consists of:
 The controller is defined using a closure like this::
 
     function () {
-        // do something
+        // ... do something
     }
 
 Closures are anonymous functions that may import state from outside of their
@@ -119,13 +118,13 @@ import local variables of that function.
 
 .. note::
 
-    Closures that do not import scope are referred to as lambdas. Because in
-    PHP all anonymous functions are instances of the ``Closure`` class, we
-    will not make a distinction here.
+    Closures that do not import scope are referred to as lambdas. Because all
+    anonymous functions are instances of the ``Closure`` class in PHP, the
+    documentation will not make a distinction here.
 
 The return value of the closure becomes the content of the page.
 
-Example GET route
+Example GET Route
 ~~~~~~~~~~~~~~~~~
 
 Here is an example definition of a ``GET`` route::
@@ -151,10 +150,10 @@ Here is an example definition of a ``GET`` route::
 
 Visiting ``/blog`` will return a list of blog post titles. The ``use``
 statement means something different in this context. It tells the closure to
-import the $blogPosts variable from the outer scope. This allows you to use it
-from within the closure.
+import the ``$blogPosts`` variable from the outer scope. This allows you to
+use it from within the closure.
 
-Dynamic routing
+Dynamic Routing
 ~~~~~~~~~~~~~~~
 
 Now, you can create another controller for viewing individual blog posts::
@@ -176,15 +175,15 @@ closure.
 The current ``Application`` is automatically injected by Silex to the Closure
 thanks to the type hinting.
 
-When the post does not exist, we are using ``abort()`` to stop the request
-early. It actually throws an exception, which we will see how to handle later
+When the post does not exist, you are using ``abort()`` to stop the request
+early. It actually throws an exception, which you will see how to handle later
 on.
 
-Example POST route
+Example POST Route
 ~~~~~~~~~~~~~~~~~~
 
 POST routes signify the creation of a resource. An example for this is a
-feedback form. We will use the ``mail`` function to send an e-mail::
+feedback form. You will use the ``mail`` function to send an e-mail::
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
@@ -204,14 +203,12 @@ It is pretty straightforward.
     included that you can use instead of ``mail()``.
 
 The current ``request`` is automatically injected by Silex to the Closure
-thanks to the type hinting. It is an instance of `Request
-<http://api.symfony.com/master/Symfony/Component/HttpFoundation/Request.html>`_,
-so you can fetch variables using the request ``get`` method.
+thanks to the type hinting. It is an instance of
+Request_, so you can fetch variables using the request ``get`` method.
 
-Instead of returning a string we are returning an instance of `Response
-<http://api.symfony.com/master/Symfony/Component/HttpFoundation/Response.html>`_.
-This allows setting an HTTP status code, in this case it is set to ``201
-Created``.
+Instead of returning a string you are returning an instance of Response_.
+This allows setting an HTTP status code, in this case it is set to
+``201 Created``.
 
 .. note::
 
@@ -225,11 +222,11 @@ You can create controllers for most HTTP methods. Just call one of these
 methods on your application: ``get``, ``post``, ``put``, ``delete``::
 
     $app->put('/blog/{id}', function ($id) {
-        ...
+        // ...
     });
 
     $app->delete('/blog/{id}', function ($id) {
-        ...
+        // ...
     });
 
 .. tip::
@@ -237,15 +234,17 @@ methods on your application: ``get``, ``post``, ``put``, ``delete``::
     Forms in most web browsers do not directly support the use of other HTTP
     methods. To use methods other than GET and POST you can utilize a special
     form field with a name of ``_method``. The form's ``method`` attribute must
-    be set to POST when using this field::
+    be set to POST when using this field:
+
+    .. code-block:: html
 
         <form action="/my/target/route/" method="post">
-            ...
+            <!-- ... -->
             <input type="hidden" id="_method" name="_method" value="PUT" />
         </form>
 
-    If using Symfony Components 2.2+ you will need to explicitly enable this
-    method override::
+    If you are using Symfony Components 2.2+, you will need to explicitly
+    enable this method override::
 
         use Symfony\Component\HttpFoundation\Request;
 
@@ -256,16 +255,16 @@ You can also call ``match``, which will match all methods. This can be
 restricted via the ``method`` method::
 
     $app->match('/blog', function () {
-        ...
+        // ...
     });
 
     $app->match('/blog', function () {
-        ...
+        // ...
     })
     ->method('PATCH');
 
     $app->match('/blog', function () {
-        ...
+        // ...
     })
     ->method('PUT|POST');
 
@@ -274,35 +273,34 @@ restricted via the ``method`` method::
     The order in which the routes are defined is significant. The first
     matching route will be used, so place more generic routes at the bottom.
 
-
-Route variables
+Route Variables
 ~~~~~~~~~~~~~~~
 
 As it has been shown before you can define variable parts in a route like
 this::
 
     $app->get('/blog/{id}', function ($id) {
-        ...
+        // ...
     });
 
 It is also possible to have more than one variable part, just make sure the
 closure arguments match the names of the variable parts::
 
     $app->get('/blog/{postId}/{commentId}', function ($postId, $commentId) {
-        ...
+        // ...
     });
 
-While it's not suggested, you could also do this (note the switched
+While it's not recommend, you could also do this (note the switched
 arguments)::
 
     $app->get('/blog/{postId}/{commentId}', function ($commentId, $postId) {
-        ...
+        // ...
     });
 
 You can also ask for the current Request and Application objects::
 
     $app->get('/blog/{id}', function (Application $app, Request $request, $id) {
-        ...
+        // ...
     });
 
 .. note::
@@ -311,10 +309,10 @@ You can also ask for the current Request and Application objects::
     based on the type hinting and not on the variable name::
 
         $app->get('/blog/{id}', function (Application $foo, Request $bar, $id) {
-            ...
+            // ...
         });
 
-Route variables converters
+Route Variables Converters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Before injecting the route variables into the controller, you can apply some
@@ -360,33 +358,33 @@ The following will make sure the ``id`` argument is numeric, since ``\d+``
 matches any amount of digits::
 
     $app->get('/blog/{id}', function ($id) {
-        ...
+        // ...
     })
     ->assert('id', '\d+');
 
 You can also chain these calls::
 
     $app->get('/blog/{postId}/{commentId}', function ($postId, $commentId) {
-        ...
+        // ...
     })
     ->assert('postId', '\d+')
     ->assert('commentId', '\d+');
 
-Default values
+Default Values
 ~~~~~~~~~~~~~~
 
 You can define a default value for any route variable by calling ``value`` on
 the ``Controller`` object::
 
     $app->get('/{pageName}', function ($pageName) {
-        ...
+        // ...
     })
     ->value('pageName', 'index');
 
 This will allow matching ``/``, in which case the ``pageName`` variable will
 have the value ``index``.
 
-Named routes
+Named Routes
 ~~~~~~~~~~~~
 
 Some providers (such as ``UrlGeneratorProvider``) can make use of named
@@ -395,45 +393,44 @@ really be used. You can give a route a name by calling ``bind`` on the
 ``Controller`` object that is returned by the routing methods::
 
     $app->get('/', function () {
-        ...
+        // ...
     })
     ->bind('homepage');
 
     $app->get('/blog/{id}', function ($id) {
-        ...
+        // ...
     })
     ->bind('blog_post');
 
-
 .. note::
 
     It only makes sense to name routes if you use providers that make use of
     the ``RouteCollection``.
 
-Controllers in classes
+Controllers in Classes
 ~~~~~~~~~~~~~~~~~~~~~~
 
 If you don't want to use anonymous functions, you can also define your
 controllers as methods. By using the ``ControllerClass::methodName`` syntax,
 you can tell Silex to lazily create the controller object for you::
 
-    $app->get('/', 'Igorw\Foo::bar');
+    $app->get('/', 'Acme\Foo::bar');
 
     use Silex\Application;
     use Symfony\Component\HttpFoundation\Request;
 
-    namespace Igorw
+    namespace Acme
     {
         class Foo
         {
             public function bar(Request $request, Application $app)
             {
-                ...
+                // ...
             }
         }
     }
 
-This will load the ``Igorw\Foo`` class on demand, create an instance and call
+This will load the ``Acme\Foo`` class on demand, create an instance and call
 the ``bar`` method to get the response. You can use ``Request`` and
 ``Silex\Application`` type hints to get ``$request`` and ``$app`` injected.
 
@@ -463,9 +460,9 @@ the defaults for new controllers.
 
     The global configuration does not apply to controller providers you might
     mount as they have their own global configuration (read the 
-    :doc:`dedicated chapter<organizing_controllers>` for more information).
+    :doc:`dedicated chapter <organizing_controllers>` for more information).
 
-Error handlers
+Error Handlers
 --------------
 
 If some part of your code throws an exception you will want to display some
@@ -511,7 +508,7 @@ You can restrict an error handler to only handle some Exception classes by
 setting a more specific type hint for the Closure argument::
 
     $app->error(function (\LogicException $e, $code) {
-        // this handler will only \LogicException exceptions
+        // this handler will only handle \LogicException exceptions
         // and exceptions that extends \LogicException
     });
 
@@ -521,8 +518,7 @@ once a response is returned, the following handlers are ignored.
 
 .. note::
 
-    Silex ships with a provider for `Monolog
-    <https://github.com/Seldaek/monolog>`_ which handles logging of errors.
+    Silex ships with a provider for Monolog_ which handles logging of errors.
     Check out the *Providers* chapter for details.
 
 .. tip::
@@ -540,7 +536,7 @@ once a response is returned, the following handlers are ignored.
                 return;
             }
 
-            // logic to handle the error and return a Response
+            // ... logic to handle the error and return a Response
         });
 
 The error handlers are also called when you use ``abort`` to abort a request
@@ -605,6 +601,7 @@ response for you::
 
         if (!$user) {
             $error = array('message' => 'The user was not found.');
+
             return $app->json($error, 404);
         }
 
@@ -744,3 +741,7 @@ to prevent Cross-Site-Scripting attacks.
       });
 
 .. _download: http://silex.sensiolabs.org/download
+.. _Composer: http://getcomposer.org/
+.. _Request: http://api.symfony.com/master/Symfony/Component/HttpFoundation/Request.html
+.. _Response: http://api.symfony.com/master/Symfony/Component/HttpFoundation/Response.html
+.. _Monolog: https://github.com/Seldaek/monolog