Reviewed the Assetic cookbook articles

Author: javiereguiluz

Diff for: cookbook/assetic/apply_to_option.rst

@@ -9,7 +9,7 @@ as you'll see here, files that have a specific extension. To show you how
 to handle each option, suppose that you want to use Assetic's CoffeeScript
 filter, which compiles CoffeeScript files into JavaScript.
 
-The main configuration is just the paths to coffee, node and node_modules.
+The main configuration is just the paths to ``coffee``, ``node`` and ``node_modules``.
 An example configuration might look like this:
 
 .. configuration-block::
@@ -102,8 +102,7 @@ You can also combine multiple CoffeeScript files into a single output file:
             <script src="<?php echo $view->escape($url) ?>"></script>
         <?php endforeach ?>
 
-Both the files will now be served up as a single file compiled into regular
-JavaScript.
+Both files will now be served up as a single file compiled into regular JavaScript.
 
 .. _cookbook-assetic-apply-to:
 
@@ -117,10 +116,10 @@ since they will ultimately all be served as JavaScript. Unfortunately just
 adding the JavaScript files to the files to be combined as above will not
 work as the regular JavaScript files will not survive the CoffeeScript compilation.
 
-This problem can be avoided by using the ``apply_to`` option in the config,
-which allows you to specify which filter should always be applied to particular
-file extensions. In this case you can specify that the ``coffee`` filter is
-applied to all ``.coffee`` files:
+This problem can be avoided by using the ``apply_to`` option, which allows you
+to specify which filter should always be applied to particular file extensions.
+In this case you can specify that the ``coffee`` filter is applied to all
+``.coffee`` files:
 
 .. configuration-block::
 
@@ -161,10 +160,10 @@ applied to all ``.coffee`` files:
             ),
         ));
 
-With this, you no longer need to specify the ``coffee`` filter in the template.
-You can also list regular JavaScript files, all of which will be combined
-and rendered as a single JavaScript file (with only the ``.coffee`` files
-being run through the CoffeeScript filter):
+With this option, you no longer need to specify the ``coffee`` filter in the
+template. You can also list regular JavaScript files, all of which will be
+combined and rendered as a single JavaScript file (with only the ``.coffee``
+files being run through the CoffeeScript filter):
 
 .. configuration-block::
 

Diff for: cookbook/assetic/asset_management.rst

@@ -73,9 +73,9 @@ To include JavaScript files, use the ``javascripts`` tag in any template:
 
 .. note::
 
-    If you're using the default block names from the Symfony Standard Edition,
-    the ``javascripts`` tag will most commonly live in the ``javascripts``
-    block:
+    If your application templates use the default block names from the Symfony
+    Standard Edition, the ``javascripts`` tag will most commonly live in the
+    ``javascripts`` block:
 
     .. code-block:: html+jinja
 
@@ -108,8 +108,8 @@ that reference images by their relative path. See :ref:`cookbook-assetic-cssrewr
 Including CSS Stylesheets
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To bring in CSS stylesheets, you can use the same methodologies seen
-above, except with the ``stylesheets`` tag:
+To bring in CSS stylesheets, you can use the same technique explained above,
+except with the ``stylesheets`` tag:
 
 .. configuration-block::
 
@@ -130,9 +130,9 @@ above, except with the ``stylesheets`` tag:
 
 .. note::
 
-    If you're using the default block names from the Symfony Standard Edition,
-    the ``stylesheets`` tag will most commonly live in the ``stylesheets``
-    block:
+    If your application templates use the default block names from the Symfony
+    Standard Edition, the ``stylesheets`` tag will most commonly live in the
+    ``stylesheets`` block:
 
     .. code-block:: html+jinja
 
@@ -204,7 +204,7 @@ Combining Assets
 ~~~~~~~~~~~~~~~~
 
 One feature of Assetic is that it will combine many files into one. This helps
-to reduce the number of HTTP requests, which is great for front end performance.
+to reduce the number of HTTP requests, which is great for frontend performance.
 It also allows you to maintain the files more easily by splitting them into
 manageable parts. This can help with re-usability as you can easily split
 project-specific files from those which can be used in other applications,
@@ -350,7 +350,7 @@ Filters
 
 Once they're managed by Assetic, you can apply filters to your assets before
 they are served. This includes filters that compress the output of your assets
-for smaller file sizes (and better front-end optimization). Other filters
+for smaller file sizes (and better frontend optimization). Other filters
 can compile JavaScript file from CoffeeScript files and process SASS into CSS.
 In fact, Assetic has a long list of available filters.
 
@@ -366,8 +366,8 @@ To use a filter, you first need to specify it in the Assetic configuration.
 Adding a filter here doesn't mean it's being used - it just means that it's
 available to use (you'll use the filter below).
 
-For example to use the UglifyJS JavaScript minifier the following config should
-be added:
+For example to use the UglifyJS JavaScript minifier the following configuration
+should be defined:
 
 .. configuration-block::
 
@@ -489,8 +489,8 @@ environment is just too slow.
 
 .. _cookbook-assetic-dump-prod:
 
-Instead, each time you use your app in the ``prod`` environment (and therefore,
-each time you deploy), you should run the following task:
+Instead, each time you use your application in the ``prod`` environment (and therefore,
+each time you deploy), you should run the following command:
 
 .. code-block:: bash
 
@@ -532,7 +532,7 @@ the following change in your ``config_dev.yml`` file:
         ));
 
 Next, since Symfony is no longer generating these assets for you, you'll
-need to dump them manually. To do so, run the following:
+need to dump them manually. To do so, run the following command:
 
 .. code-block:: bash
 
@@ -547,8 +547,8 @@ assets will be regenerated automatically *as they change*:
 
     $ php app/console assetic:watch
 
-The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior 
-versions, you had to use the ``--watch`` option of the ``assetic:dump`` 
+The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior
+versions, you had to use the ``--watch`` option of the ``assetic:dump``
 command for the same behavior.
 
 Since running this command in the ``dev`` environment may generate a bunch

Diff for: cookbook/assetic/jpeg_optimize.rst

@@ -13,8 +13,9 @@ for your end users.
 Using Jpegoptim
 ---------------
 
-`Jpegoptim`_ is a utility for optimizing JPEG files. To use it with Assetic,
-add the following to the Assetic config:
+`Jpegoptim`_ is a utility for optimizing JPEG files. To use it with Assetic, make
+sure to have it already installed on your system and then, configure its location
+using the ``bin`` option of the ``jpegoptim`` filter:
 
 .. configuration-block::
 
@@ -46,11 +47,6 @@ add the following to the Assetic config:
             ),
         ));
 
-.. note::
-
-    Notice that to use jpegoptim, you must have it already installed on your
-    system. The ``bin`` option points to the location of the compiled binary.
-
 It can now be used from a template:
 
 .. configuration-block::
@@ -74,9 +70,9 @@ It can now be used from a template:
 Removing all EXIF Data
 ~~~~~~~~~~~~~~~~~~~~~~
 
-By default, running this filter only removes some of the meta information
-stored in the file. Any EXIF data and comments are not removed, but you can
-remove these by using the ``strip_all`` option:
+By default, the ``jpegoptim`` filter removes some of the meta information stored
+in the image. To remove all EXIF data and comments, set the ``strip_all`` option
+to ``true``:
 
 .. configuration-block::
 
@@ -111,13 +107,13 @@ remove these by using the ``strip_all`` option:
             ),
         ));
 
-Lowering maximum Quality
+Lowering Maximum Quality
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-The quality level of the JPEG is not affected by default. You can gain
-further file size reductions by setting the max quality setting lower than
-the current level of the images. This will of course be at the expense of
-image quality:
+By default, the ``jpegoptim`` filter doesn't alter the quality level of the JPEG
+image. Use the ``max`` option to configure the maximum quality setting (in a
+scale of ``0`` to ``100``). The reduction in the image file size will of course
+be at the expense of its quality:
 
 .. configuration-block::
 
@@ -157,7 +153,7 @@ Shorter Syntax: Twig Function
 
 If you're using Twig, it's possible to achieve all of this with a shorter
 syntax by enabling and using a special Twig function. Start by adding the
-following config:
+following configuration:
 
 .. configuration-block::
 
@@ -206,7 +202,8 @@ The Twig template can now be changed to the following:
 
     <img src="{{ jpegoptim('@AppBundle/Resources/public/images/example.jpg') }}" alt="Example"/>
 
-You can specify the output directory in the config in the following way:
+You can also specify the output directory for images in the Assetic configuration
+file:
 
 .. configuration-block::
 

Diff for: cookbook/assetic/uglifyjs.rst

@@ -16,41 +16,47 @@ talked about briefly.
 Install UglifyJS
 ----------------
 
-UglifyJS is available as an `Node.js`_ npm module and can be installed using
-npm. First, you need to `install Node.js`_. Afterwards you can install UglifyJS
-using npm:
+UglifyJS is available as a `Node.js`_ module. First, you need to `install Node.js`_
+and then, decide the installation method: global or local.
+
+Global Installation
+~~~~~~~~~~~~~~~~~~~
+
+The global installation method makes all your projects use the very same UglifyJS
+version, which simplifies its maintenance. Open your command console and execute
+the following command (you may need to run it as a root user):
 
 .. code-block:: bash
 
     $ npm install -g uglify-js
 
-This command will install UglifyJS globally and you may need to run it as
-a root user.
+Now you can execute the global ``uglifyjs`` command anywhere on your system:
 
-.. note::
+.. code-block:: bash
 
-    It's also possible to install UglifyJS inside your project only. To do
-    this, install it without the ``-g`` option and specify the path where
-    to put the module:
+    $ uglifyjs --help
 
-    .. code-block:: bash
+Local Installation
+~~~~~~~~~~~~~~~~~~
 
-        $ cd /path/to/symfony
-        $ mkdir app/Resources/node_modules
-        $ npm install uglify-js --prefix app/Resources
+It's also possible to install UglifyJS inside your project only, which is useful
+when your project requires an specific UglifyJS version. To do this, install it
+without the ``-g`` option and specify the path where to put the module:
 
-    It is recommended that you install UglifyJS in your ``app/Resources`` folder
-    and add the ``node_modules`` folder to version control. Alternatively,
-    you can create an npm `package.json`_ file and specify your dependencies
-    there.
+.. code-block:: bash
 
-Depending on your installation method, you should either be able to execute
-the ``uglifyjs`` executable globally, or execute the physical file that lives
-in the ``node_modules`` directory:
+    $ cd /path/to/your/symfony/project
+    $ mkdir app/Resources/node_modules
+    $ npm install uglify-js --prefix app/Resources
 
-.. code-block:: bash
+It is recommended that you install UglifyJS in your ``app/Resources`` folder and
+add the ``node_modules`` folder to version control. Alternatively, you can create
+an npm `package.json`_ file and specify your dependencies there.
 
-    $ uglifyjs --help
+Now you can execute the ``uglifyjs`` command that lives in the ``node_modules``
+directory:
+
+.. code-block:: bash
 
     $ ./app/Resources/node_modules/.bin/uglifyjs --help
 
@@ -96,8 +102,7 @@ your JavaScripts:
 .. note::
 
     The path where UglifyJS is installed may vary depending on your system.
-    To find out where npm stores the ``bin`` folder, you can use the following
-    command:
+    To find out where npm stores the ``bin`` folder, execute the following command:
 
     .. code-block:: bash
 
@@ -154,8 +159,8 @@ can configure its location using the ``node`` key:
 Minify your Assets
 ------------------
 
-In order to use UglifyJS on your assets, you need to apply it to them. Since
-your assets are a part of the view layer, this work is done in your templates:
+In order to apply UglifyJS on your assets, add the ``filter`` option in the
+asset tags of your templates to tell Assetic to use the ``uglifyjs2`` filter:
 
 .. configuration-block::
 
@@ -178,8 +183,7 @@ your assets are a part of the view layer, this work is done in your templates:
 
     The above example assumes that you have a bundle called AppBundle and your
     JavaScript files are in the ``Resources/public/js`` directory under your
-    bundle. This isn't important however - you can include your JavaScript
-    files no matter where they are.
+    bundle. However you can include your JavaScript files no matter where they are.
 
 With the addition of the ``uglifyjs2`` filter to the asset tags above, you
 should now see minified JavaScripts coming over the wire much faster.
@@ -216,12 +220,9 @@ and :ref:`dump your assetic assets <cookbook-assetic-dump-prod>`.
 
 .. tip::
 
-    Instead of adding the filter to the asset tags, you can also globally
-    enable it by adding the ``apply_to`` attribute to the filter configuration, for
-    example in the ``uglifyjs2`` filter ``apply_to: "\.js$"``. To only have
-    the filter applied in production, add this to the ``config_prod`` file
-    rather than the common config file. For details on applying filters by
-    file extension, see :ref:`cookbook-assetic-apply-to`.
+    Instead of adding the filters to the asset tags, you can also configure which
+    filters to apply for each file in your application configuration file.
+    See :ref:`cookbook-assetic-apply-to` for more details.
 
 Install, Configure and Use UglifyCSS
 ------------------------------------
@@ -231,8 +232,14 @@ the node package is installed:
 
 .. code-block:: bash
 
+    # global installation
     $ npm install -g uglifycss
 
+    # local installation
+    $ cd /path/to/your/symfony/project
+    $ mkdir app/Resources/node_modules
+    $ npm install uglifycss --prefix app/Resources
+
 Next, add the configuration for this filter:
 
 .. configuration-block::

Diff for: cookbook/assetic/yuicompressor.rst

@@ -4,19 +4,15 @@
 How to Minify JavaScripts and Stylesheets with YUI Compressor
 =============================================================
 
-Yahoo! provides an excellent utility for minifying JavaScripts and stylesheets
-so they travel over the wire faster, the `YUI Compressor`_. Thanks to Assetic,
-you can take advantage of this tool very easily.
-
 .. caution::
 
-    The YUI Compressor is `no longer maintained by Yahoo`_ but by an independent
-    volunteer. Moreover, Yahoo has decided to `stop all new development on YUI`_
-    and to move to other modern alternatives such as Node.js.
+    The YUI Compressor is `no longer maintained by Yahoo`_. That's why you are
+    **strongly advised to avoid using YUI utilities** unless strictly necessary.
+    Read :doc:`/cookbook/assetic/uglifyjs` for a modern and up-to-date alternative.
 
-    That's why you are **strongly advised** to avoid using YUI utilities unless
-    strictly necessary. Read :doc:`/cookbook/assetic/uglifyjs` for a modern and
-    up-to-date alternative.
+Yahoo! provides an excellent utility for minifying JavaScripts and stylesheets
+so they travel over the wire faster, the `YUI Compressor`_. Thanks to Assetic,
+you can take advantage of this tool very easily.
 
 Download the YUI Compressor JAR
 -------------------------------
@@ -170,4 +166,3 @@ apply this filter when debug mode is off.
 .. _`YUI Compressor`: http://developer.yahoo.com/yui/compressor/
 .. _`Download the JAR`: https://github.com/yui/yuicompressor/releases
 .. _`no longer maintained by Yahoo`: http://www.yuiblog.com/blog/2013/01/24/yui-compressor-has-a-new-owner/
-.. _`stop all new development on YUI`: http://yahooeng.tumblr.com/post/96098168666/important-announcement-regarding-yui