minor #1269 Minor doc tweaks and fixes (javiereguiluz)

This PR was squashed before being merged into the 1.3 branch (closes #1269).

Discussion
----------

Minor doc tweaks and fixes

This past weekend I reviewed the entire doc for 1.3 version and this PR contains tweaks and fixes. If you don't agree with some change, tell me and I'll revert it.

Commits
-------

bcc1a45a Minor doc tweaks and fixes

doc/middlewares.rst

@@ -145,9 +145,9 @@ possible or as late as possible::
 Short-circuiting the Controller
 -------------------------------
 
-If a before middleware returns a Response object, the Request handling is
+If a *before* middleware returns a ``Response`` object, the request handling is
 short-circuited (the next middlewares won't be run, nor the route
-callback), and the Response is passed to the after middlewares right away::
+callback), and the Response is passed to the *after* middlewares right away::
 
     $app->before(function (Request $request) {
         // redirect the user to the login screen if access to the Resource is protected

doc/providers.rst

@@ -52,19 +52,19 @@ There are a few providers that you get out of the box. All of these are within
 the ``Silex\Provider`` namespace:
 
 * :doc:`DoctrineServiceProvider <providers/doctrine>`
+* :doc:`FormServiceProvider <providers/form>`
+* :doc:`HttpCacheServiceProvider <providers/http_cache>`
 * :doc:`MonologServiceProvider <providers/monolog>`
-* :doc:`SessionServiceProvider <providers/session>`
+* :doc:`RememberMeServiceProvider <providers/remember_me>`
+* :doc:`SecurityServiceProvider <providers/security>`
 * :doc:`SerializerServiceProvider <providers/serializer>`
+* :doc:`ServiceControllerServiceProvider <providers/service_controller>`
+* :doc:`SessionServiceProvider <providers/session>`
 * :doc:`SwiftmailerServiceProvider <providers/swiftmailer>`
-* :doc:`TwigServiceProvider <providers/twig>`
 * :doc:`TranslationServiceProvider <providers/translation>`
+* :doc:`TwigServiceProvider <providers/twig>`
 * :doc:`UrlGeneratorServiceProvider <providers/url_generator>`
 * :doc:`ValidatorServiceProvider <providers/validator>`
-* :doc:`HttpCacheServiceProvider <providers/http_cache>`
-* :doc:`FormServiceProvider <providers/form>`
-* :doc:`SecurityServiceProvider <providers/security>`
-* :doc:`RememberMeServiceProvider <providers/remember_me>`
-* :doc:`ServiceControllerServiceProvider <providers/service_controller>`
 
 Third party providers
 ~~~~~~~~~~~~~~~~~~~~~

doc/providers/monolog.rst

@@ -12,8 +12,8 @@ Parameters
 ----------
 
 * **monolog.logfile**: File where logs are written to.
-* **monolog.bubble** = (optional) Whether the messages that are handled can bubble up the stack or not.
-* **monolog.permission** = (optional) File permissions default (null), nothing change.
+* **monolog.bubble**: (optional) Whether the messages that are handled can bubble up the stack or not.
+* **monolog.permission**: (optional) File permissions default (null), nothing change.
 
 * **monolog.level** (optional): Level of logging, defaults
   to ``DEBUG``. Must be one of ``Logger::DEBUG``, ``Logger::INFO``,

doc/providers/security.rst

@@ -74,7 +74,7 @@ Registering
     booted. So, if you want to use it outside of the handling of a request,
     don't forget to call ``boot()`` first::
 
-        $application->boot();
+        $app->boot();
 
 .. caution::
 

doc/services.rst

@@ -2,8 +2,8 @@ Services
 ========
 
 Silex is not only a framework, it is also a service container. It does this by
-extending `Pimple <http://pimple.sensiolabs.org>`_ which provides service
-goodness in just 44 NCLOC.
+extending `Pimple <http://pimple.sensiolabs.org>`_ which provides a very simple
+service container.
 
 Dependency Injection
 --------------------
@@ -70,8 +70,7 @@ the container::
 
     $app['some_parameter'] = 'value';
 
-The array key can be anything, by convention periods are used for
-namespacing::
+The array key can be any value. By convention dots are used for namespacing::
 
     $app['asset.host'] = 'http://cdn.mysite.com/';
 

doc/usage.rst

@@ -44,9 +44,6 @@ definitions, call the ``run`` method on your application::
 
     $app->run();
 
-Then, you have to configure your web server (read the
-:doc:`dedicated chapter <web_servers>` for more information).
-
 .. tip::
 
     When developing a website, you might want to turn on the debug mode to
@@ -339,7 +336,8 @@ converter based on Doctrine ObjectManager::
     }
 
 The service will now be registered in the application, and the
-convert method will be used as converter::
+``convert()`` method will be used as converter (using the syntax
+``service_name:method_name``)::
 
     $app['converter.user'] = $app->share(function () {
         return new UserConverter();
@@ -356,8 +354,8 @@ In some cases you may want to only match certain expressions. You can define
 requirements using regular expressions by calling ``assert`` on the
 ``Controller`` object, which is returned by the routing methods.
 
-The following will make sure the ``id`` argument is numeric, since ``\d+``
-matches any amount of digits::
+The following will make sure the ``id`` argument is a positive integer, since
+``\d+`` matches any amount of digits::
 
     $app->get('/blog/{id}', function ($id) {
         // ...
@@ -555,7 +553,7 @@ View Handlers allow you to intercept a controller result that is not a
 ``Response`` and transform it before it gets returned to the kernel.
 
 To register a view handler, pass a callable (or string that can be resolved to a
-callable) to the view method. The callable should accept some sort of result
+callable) to the ``view()`` method. The callable should accept some sort of result
 from the controller::
 
     $app->view(function (array $controllerResult) use ($app) {
@@ -593,8 +591,8 @@ as the input for the next.
 Redirects
 ---------
 
-You can redirect to another page by returning a redirect response, which you
-can create by calling the ``redirect`` method::
+You can redirect to another page by returning a ``RedirectResponse`` response,
+which you can create by calling the ``redirect`` method::
 
     $app->get('/', function () use ($app) {
         return $app->redirect('/hello');
@@ -612,7 +610,7 @@ round-trip to the browser (as for a redirect), use an internal sub-request::
     use Symfony\Component\HttpKernel\HttpKernelInterface;
 
     $app->get('/', function () use ($app) {
-        // redirect to /hello
+        // forward to /hello
         $subRequest = Request::create('/hello', 'GET');
 
         return $app->handle($subRequest, HttpKernelInterface::SUB_REQUEST);
@@ -672,9 +670,9 @@ after every chunk::
     $stream = function () {
         $fh = fopen('http://www.example.com/', 'rb');
         while (!feof($fh)) {
-          echo fread($fh, 1024);
-          ob_flush();
-          flush();
+            echo fread($fh, 1024);
+            ob_flush();
+            flush();
         }
         fclose($fh);
     };
@@ -761,6 +759,7 @@ Cross-Site-Scripting attacks.
 
       $app->get('/name', function (Silex\Application $app) {
           $name = $app['request']->get('name');
+
           return "You provided the name {$app->escape($name)}.";
       });
 
@@ -772,6 +771,7 @@ Cross-Site-Scripting attacks.
 
       $app->get('/name.json', function (Silex\Application $app) {
           $name = $app['request']->get('name');
+
           return $app->json(array('name' => $name));
       });