Edited updated dashboard chapter for typos and readability, ref #1524

Broke YML examples up into multiple lines so they're easier to read (I hope the "list of arrays" syntax is common enough for people to understand)

Resources/doc/reference/dashboard.rst

@@ -2,14 +2,14 @@ Dashboard
 =========
 
 The Dashboard is the main landing page. By default it lists your mapped models,
-as defined by you using ``Admin`` services. This is useful to help you start using
+as defined by your ``Admin`` services. This is useful to help you start using
 ``SonataAdminBundle`` right away, but there's much more that you can do to take
 advantage of the Dashboard.
 
 The Dashboard is, by default, available at ``/admin/dashboard``, which is handled by
 the ``SonataAdminBundle:Core:dashboard`` controller action. The default view file for
-this action is ``SonataAdminBundle:Core:dashboard.html.twig``, but you can easily change
-it in your ``config.yml``:
+this action is ``SonataAdminBundle:Core:dashboard.html.twig``, but you can change
+this in your ``config.yml``:
 
 .. code-block:: yaml
 
@@ -19,7 +19,8 @@ it in your ``config.yml``:
             dashboard: SonataAdminBundle:Core:dashboard.html.twig
 
 .. note::
-    This view, like most of ``SonataAdminBundle`` views, extends a global
+
+    This view, like most of the ``SonataAdminBundle`` views, extends a global
     template file, which also contains significant parts to the page. More information
     about this is available in the :doc:`templates` chapter.
 
@@ -27,23 +28,20 @@ Blocks
 ------
 
 The Dashboard is actually built using ``Blocks`` from ``SonataBlockBundle``. You
-can learn more about this bundle and how to build your own Blocks in its `documentation page`_.
-
-An example of a ``Block`` is the above mentioned ``Admin`` list. It is actually implemented as a
-``SonataBlockBundle`` block, that displays your configured ``Admin`` services in a nicely
-formated list.
+can learn more about this bundle and how to build your own Blocks on the 
+`SonataBlock documentation page`_.
 
 The ``Admin`` list
 ------------------
 
-The ``Admin`` list is a ``Block`` that fetches information from the ``Admin`` services ``Pool`` 
-and prints it in the nicely formated list you have on your default Dashboard. 
+The ``Admin`` list is a ``Block`` that fetches information from the ``Admin`` service's
+``Pool`` and prints it in the nicely formated list you have on your default Dashboard. 
 The ``Admin`` list is defined by the ``sonata.admin.block.admin_list`` service, which is
 implemented by the ``Block\AdminListBlockService`` class. It is then rendered using the
 ``SonataAdminBundle:Block:block_admin_list.html.twig`` template file.
 
-Feel free to take a look at these files. You'll find the code rather small and easy to
-understand, and will be a great help when implementing your own blocks.
+Feel free to take a look at these files. You'll find the code rather short and easy to
+understand, and it will be a great help when implementing your own blocks.
 
 Configuring the ``Admin`` list
 ------------------------------
@@ -54,13 +52,15 @@ There are several ways in which you can configure these groups.
 Using the ``Admin`` service declaration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The first, and most commonly
-used, is when defining your ``Admin`` service:
+The first, and most commonly used, method is to set a group when defining your ``Admin`` 
+services:
 
 .. code-block:: xml
 
     <service id="sonata.admin.post" class="Acme\DemoBundle\Admin\PostAdmin">
-          <tag name="sonata.admin" manager_type="orm" group="Content" label="Post"/>
+          <tag name="sonata.admin" manager_type="orm" 
+              group="Content" 
+              label="Post"/>
           <argument />
           <argument>Acme\DemoBundle\Entity\Post</argument>
           <argument />
@@ -72,19 +72,24 @@ used, is when defining your ``Admin`` service:
         sonata.admin.post:
             class: Acme\DemoBundle\Admin\PostAdmin
             tags:
-                - { name: sonata.admin, manager_type: orm, group: "Content", label: "Post" }
+                - name: sonata.admin
+                  manager_type: orm
+                  group: "Content"
+                  label: "Post"
             arguments:
                 - ~
                 - Acme\DemoBundle\Entity\Post
                 - ~
 
-In these examples, notice the ``group`` tag, stating that this particular ``Admin`` service
-belongs to the ``Content`` group. 
+In these examples, notice the ``group`` tag, stating that this particular ``Admin`` 
+service belongs to the ``Content`` group. 
                 
 .. code-block:: xml
 
     <service id="sonata.admin.post" class="Acme\DemoBundle\Admin\PostAdmin">
-          <tag name="sonata.admin" manager_type="orm" group="acme.admin.group.content" label="acme.admin.model.post" label_catalogue="AcmeDemoBundle"/>
+          <tag name="sonata.admin" manager_type="orm" 
+              group="acme.admin.group.content" 
+              label="acme.admin.model.post" label_catalogue="AcmeDemoBundle"/>
           <argument />
           <argument>Acme\DemoBundle\Entity\Post</argument>
           <argument />
@@ -96,25 +101,31 @@ belongs to the ``Content`` group.
         sonata.admin.post:
             class: Acme\DemoBundle\Admin\PostAdmin
             tags:
-                - { name: sonata.admin, manager_type: orm, group: "acme.admin.group.content", label: "acme.admin.model.post",  label_catalogue: "AcmeDemoBundle" }
+                - name: sonata.admin
+                  manager_type: orm
+                  group: "acme.admin.group.content"
+                  label: "acme.admin.model.post"
+                  label_catalogue: "AcmeDemoBundle"
             arguments:
                 - ~
                 - Acme\DemoBundle\Entity\Post
                 - ~
 
-The provided labels are actually translated by ``SonataAdminBundle``, using the given
-``label_catalogue``. So, you can use the above examples to support multilanguage
+In this example, the labels are translated by ``SonataAdminBundle``, using the given
+``label_catalogue``. So, you can use the above examples to support multiple languages
 in your project.
 
 .. note::
-    You can use ``parameters`` as group names in both scenarios.
+
+    You can use parameters (e.g. ``%acme_admin.group_post%``) for the group names 
+    in either scenario.
 
 Using the ``config.yml``
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can also configure the ``Admin`` list in your ``config.yml`` file. This
-configuration method overrides the configuration defined as part of the
-``Admin`` services declaration.
+configuration method overrides the any settings defined in the Admin service
+declarations.
 
 .. code-block:: yaml
 
@@ -135,29 +146,31 @@ configuration method overrides the configuration defined as part of the
                 acme.admin.group.misc: ~
 
 .. note::
-    This is an academic, full configuration example, meaning that in real cases, you may
-    not need to use all the displayed options. Default values can be used by either 
-    leaving them out of the configuration or by using the ``~`` value in the respective option.
+
+    This is an academic, full configuration, example. In real cases, you will usually
+    not need to use all the displayed options. To use a default value for any setting
+    either leave out that key or use the ``~`` value for that option.
 
 This configuration specifies that the ``acme.admin.group.content`` group uses the
 ``acme.admin.group.content`` label, which is translated using the ``AcmeDemoBundle``
-translation catalogue. In other words, it's the same configuration that we declared
-previously, on the ``Admin`` service.
+translation catalogue (the same label and translation configuration that we declared 
+previously, in the service definition example).
 
 It also states that the ``acme.admin.group.content`` group contains just the 
 ``sonata.admin.post`` ``Admin`` mapping, meaning that any other ``Admin`` services
 declared as belonging to this group will not be displayed here.
 
-Secondly, we declare a ``acme.admin.group.blog`` as having all its default items 
-(by default we mean the ones specified in the ``Admin`` services declaration), plus
-an additional ``sonata.admin.page`` mapping, that was not initially part of this group.
-We also use the ``roles`` option here, used to specify that , instead of being visible
-to everyone, only users with ``ROLE_ONE`` or ``ROLE_TWO`` will be able to see this group. 
-Users with ``ROLE_SUPER_ADMIN`` are always able to see groups that would otherwise be
-hidden by this configuration option. 
+Secondly, we declare a ``acme.admin.group.blog`` group as having all its default items 
+(i.e. the ones specified in the ``Admin`` service declarations), plus an *additional* 
+``sonata.admin.page`` mapping, that was not initially part of this group.
+
+We also use the ``roles`` option here, which means that only users with the ``ROLE_ONE`` 
+or ``ROLE_TWO`` privileges will be able to see this group, as opposed to the default setting
+which allows everyone to see a given group. Users with ``ROLE_SUPER_ADMIN`` are always 
+able to see groups that would otherwise be hidden by this configuration option. 
 
-The third group keeps all the default values, as declared on the ``Admin`` service
-declaration.
+The third group, ``acme.admin.group.misc``, is set up as a group which uses all its 
+default values, as declared in the service declarations.
 
 
 Adding more Blocks
@@ -171,8 +184,8 @@ you can create and add more blocks to it.
    :alt: Dashboard
    :width: 500
    
-In this screenshot, you can see how, besides the ``Admin`` list block on the left, we added 
-a text block and a RSS feed block to the right. The configuration for this scenario would be:
+In this screenshot, in addition to the default ``Admin`` list block on the left, we added 
+a text block and RSS feed block on the right. The configuration for this scenario would be:
 
 .. code-block:: yaml
 
@@ -180,12 +193,29 @@ a text block and a RSS feed block to the right. The configuration for this scena
     sonata_admin:
         dashboard:
             blocks:
-                - { position: left,  type: sonata.admin.block.admin_list }
-                - { position: right, type: sonata.block.service.text, settings: { content: "<h2>Welcome to the Sonata Admin</h2> <p>This is a <code>sonata.block.service.text</code> from the Block Bundle, you can create and add new block in these area by configuring the <code>sonata_admin</code> section.</p> <br /> For instance, here a RSS feed parser (<code>sonata.block.service.rss</code>):"} }
-                - { position: right, type: sonata.block.service.rss, settings: { title: Sonata Project's Feeds, url: http://sonata-project.org/blog/archive.rss }}
+                - 
+                    position: left
+                    type: sonata.admin.block.admin_list
+                - 
+                    position: right
+                    type: sonata.block.service.text
+                    settings:
+                        content: >
+                            <h2>Welcome to the Sonata Admin</h2>
+                            <p>This is a <code>sonata.block.service.text</code> from the Block 
+                            Bundle, you can create and add new block in these area by configuring 
+                            the <code>sonata_admin</code> section.</p> <br /> For instance, here 
+                            a RSS feed parser (<code>sonata.block.service.rss</code>):
+                -
+                    position: right
+                    type: sonata.block.service.rss
+                    settings:
+                        title: Sonata Project's Feeds
+                        url: http://sonata-project.org/blog/archive.rss
 
 
 .. note::
+
     Blocks may accept/require additional settings to be passed in order to
     work properly. Refer to the associated documentation/implementation to
     get more information on each block's options and requirements.
@@ -193,9 +223,10 @@ a text block and a RSS feed block to the right. The configuration for this scena
 Display two ``Admin`` list blocks with different dashboard groups
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The same block can have multiple instances, and displayed multiple time
-across the Dashboard. An particular example is the ``Admin`` list block,
-which can be configured to better fit this scenario.
+The same block can have multiple instances, and be displayed multiple times
+across the Dashboard using different configuration settings for each instance.
+A particular example is the ``Admin`` list block, which can be configured to 
+suit this scenario.
 
 .. code-block:: yaml
 
@@ -204,8 +235,16 @@ which can be configured to better fit this scenario.
         dashboard:
             blocks:
                 # display two dashboard blocks
-                - { position: left,  type: sonata.admin.block.admin_list, settings: { groups: [sonata_page1, sonata_page2] } }
-                - { position: right, type: sonata.admin.block.admin_list, settings: { groups: [sonata_page3] } }
+                -
+                    position: left
+                    type: sonata.admin.block.admin_list
+                    settings:
+                        groups: [sonata_page1, sonata_page2]
+                -
+                    position: right
+                    type: sonata.admin.block.admin_list
+                    settings:
+                        groups: [sonata_page3]
 
             groups:
                 sonata_page1:
@@ -219,7 +258,7 @@ which can be configured to better fit this scenario.
                     items:
                         - sonata.page.admin.myitem4
 
-In this example, you would have two ``Admin`` list blocks on your dashboard, each of
-them containing just the respectively configured groups.
+In this example, you would have two ``admin_list`` blocks on your dashboard, each 
+of them containing just the respectively configured groups.
 
-.. _`documentation page`:  http://sonata-project.org/bundles/block/master/doc/index.html
+.. _`SonataBlock documentation page`:  http://sonata-project.org/bundles/block/master/doc/index.html