[symfony#2735] Minor tweaks to the big, nice refactoring of the templating component done by WouterJ

Author: weaverryan

components/templating/helpers/assetshelper.rst

@@ -5,27 +5,30 @@ Assets Helper
 =============
 
 The assets helper's main purpose is to make your application more portable by
-generating assets' paths:
+generating asset paths:
 
 .. code-block:: html+php
 
    <link href="<?php echo $view['assets']->getUrl('css/style.css') ?>" rel="stylesheet">
 
    <img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>">
 
+The assets helper can then be configured to render paths to a CDN or modify
+the paths in case your assets live in a sub-directory if your host (e.g. ``http://example.com/app``).
+
 Configure Paths
 ---------------
 
 By default, the assets helper will prefix all paths with a slash. You can
-extend this by configuring a basepath in the first argument of the
+configure this by passing a base assets path as the first argument of the
 constructor::
 
     use Symfony\Component\Templating\Helper\AssetsHelper;
 
     // ...
     $templateEngine->set(new AssetsHelper('/foo/bar'));
 
-Now, if you use the helper everything will be prefixed with ``/foo/bar``:
+Now, if you use the helper, everything will be prefixed with ``/foo/bar``:
 
 .. code-block:: html+php
 
@@ -63,13 +66,13 @@ second is the version. For instance, ``%s?v=%s`` will be rendered as
 Multiple Packages
 -----------------
 
-Paths are internally handled by packages. The component provides 2 packages by
-default:
+Asset path generation is handled internally by packages. The component provides
+2 packages by default:
 
 * :class:`Symfony\\Component\\Templating\\Asset\\PathPackage`
 * :class:`Symfony\\Component\\Templating\\Asset\\UrlPackage`
 
-You can also have multiple packages::
+You can also use multiple packages::
 
     // ...
     $templateEngine->set(new AssetsHelper());

components/templating/helpers/slotshelper.rst

@@ -5,12 +5,14 @@ Slots Helper
 ============
 
 More often than not, templates in a project share common elements, like the
-well-known header and footer. The static HTML code can be placed in a layout file
-and the dynamic sections are replaced by slots, which are filled by the child
-template; the layout file decorates the child template.
+well-known header and footer. Using this helper, the static HTML code can
+be placed in a layout file along with "slots", which represent the dynamic
+parts that will change on a page-by-page basis. These slots are then filled
+in by different children template. In other words, the layout file decorates
+the child template.
 
 Displaying Slots
-~~~~~~~~~~~~~~~~
+----------------
 
 The slots are accessible by using the slots helper (``$view['slots']``). Use
 :method:`Symfony\\Component\\Templating\\Helper\\SlotsHelper::output` to
@@ -47,7 +49,7 @@ the content of the subtemplate.
         $templateEngine->set(new SlotsHelper());
 
 Extending Templates
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 The :method:`Symfony\\Component\\Templating\\PhpEngine::extend` method is called in the
 sub-template to set its parent template. Then
@@ -72,7 +74,7 @@ is in the ``_content`` slot.
 
 .. note::
 
-    Multiple levels of inheritance is possible: a layout can extend an other
+    Multiple levels of inheritance is possible: a layout can extend another
     layout.
 
 For large slots, there is also an extended syntax:

components/templating/introduction.rst

@@ -26,11 +26,11 @@ Usage
 
 The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point
 of the component. It needs a
-:class:`template name parser <Symfony\\Component\\Templating\\TemplateNameParserInterface>`
+template name parser (:class:`Symfony\\Component\\Templating\\TemplateNameParserInterface`)
 to convert a template name to a
-:class:`template reference <Symfony\\Component\\Templating\\TemplateReferenceInterface>`
-and :class:`template loader <Symfony\\Component\\Templating\\Loader\\LoaderInterface>`
-to find the template associated to a reference::
+template reference (:class:`Symfony\\Component\\Templating\\TemplateReferenceInterface`).
+It also needs a template loader (:class:`Symfony\\Component\\Templating\\Loader\\LoaderInterface`)
+which uses the template reference to actually find and load the template::
 
     use Symfony\Component\Templating\PhpEngine;
     use Symfony\Component\Templating\TemplateNameParser;
@@ -57,16 +57,16 @@ The ``$view`` variable
 
 In all templates parsed by the ``PhpEngine``, you get access to a mysterious
 variable called ``$view``. That variable holds the current ``PhpEngine``
-instance. That means you get access to a bunch of methods that makes your life
+instance. That means you get access to a bunch of methods that make your life
 easier.
 
 Including Templates
 -------------------
 
-The best way to share a snippet of template code is to define a template that
-can then be included into other templates. As the ``$view`` variable is an
+The best way to share a snippet of template code is to create a template that
+can then be included by other templates. As the ``$view`` variable is an
 instance of ``PhpEngine``, you can use the ``render`` method (which was used
-to render the template) inside the template to render another template::
+to render the template originally) inside the template to render another template::
 
     <?php $names = array('Fabien', ...) ?>
     <?php foreach ($names as $name) : ?>
@@ -76,18 +76,20 @@ to render the template) inside the template to render another template::
 Output Escaping
 ---------------
 
-When you display variables to the user, you should escape them using the
+When you render variables, you should probably escape them so that HTML or
+JavaScript code isn't written out to your page. This will prevent things like
+XSS attacks. To do this, use the
 :method:`Symfony\\Component\\Templating\\PhpEngine::escape` method::
 
     <?php echo $view->escape($firstname) ?>
 
 By default, the ``escape()`` method assumes that the variable is outputted
 within an HTML context. The second argument lets you change the context. For
-instance, to output something in a JavaScript script, use the ``js`` context::
+example, to output something inside JavaScript, use the ``js`` context::
 
     <?php echo $view->escape($var, 'js') ?>
 
-The components comes with a HTML and JS escaper. You can register your own
+The component comes with an HTML and JS escaper. You can register your own
 escaper using the
 :method:`Symfony\\Component\\Templating\\PhpEngine::setEscaper` method::
 
@@ -101,10 +103,10 @@ Helpers
 -------
 
 The Templating component can be easily extended via helpers. The component has
-2 build-in helpers:
+2 built-in helpers:
 
-* :doc:`/components/helpers/assetshelper`
-* :doc:`/components/helpers/slotshelper`
+* :doc:`/components/templating/helpers/assetshelper`
+* :doc:`/components/templating/helpers/slotshelper`
 
 Before you can use these helpers, you need to register them using
 :method:`Symfony\\Component\\Templating\\PhpEngine::set`::