feature #5574 [2.7] Update Twig docs for asset features (javiereguiluz, WouterJ)

This PR was merged into the 2.7 branch.

Discussion
----------

[2.7] Update Twig docs for asset features

Finishes #5171

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.7+
| Fixed tickets | #4982 (partially)

Commits
-------

0cd7e6c Correctly document new twig functions
bc18ff1 Updated Twig template to take into account asset() function changes

Author: xabbuh

book/templating.rst

@@ -1067,46 +1067,12 @@ assets won't be loaded from cache after being deployed. For example, ``/images/l
 look like ``/images/logo.png?v2``. For more information, see the :ref:`reference-framework-assets-version`
 configuration option.
 
-.. _`book-templating-version-by-asset`:
+If you need absolute URLs for assets, use the ``absolute_url()`` Twig function
+as follows:
 
-If you need to set a version for a specific asset, you can set the ``version`` argument
-if you are using Twig (or the fourth argument if you are using PHP) to the desired version:
+.. code-block:: html+jinja
 
-.. configuration-block::
-
-    .. code-block:: html+jinja
-
-        <img src="{{ asset('images/logo.png', version='3.0') }}" alt="Symfony!" />
-
-    .. code-block:: html+php
-
-        <img src="<?php echo $view['assets']->getUrl(
-            'images/logo.png',
-            null,
-            false,
-            '3.0'
-        ) ?>" alt="Symfony!" />
-
-If you don't give a version or pass ``null``, the default package version
-(from :ref:`reference-framework-assets-version`) will be used. If you pass ``false``,
-versioned URL will be deactivated for this asset.
-
-If you need absolute URLs for assets, you can use the ``absolute_url`` function
-if you are using Twig (or the third argument if you are using PHP) to ``true``:
-
-.. configuration-block::
-
-    .. code-block:: html+jinja
-
-        <img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />
-
-    .. code-block:: html+php
-
-        <img src="<?php echo $view['assets']->getUrl(
-            'images/logo.png',
-            null,
-            true
-        ) ?>" alt="Symfony!" />
+    <img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />
 
 .. index::
    single: Templating; Including stylesheets and JavaScripts

reference/configuration/framework.rst

@@ -1081,10 +1081,6 @@ Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
 this feature, you **must** manually increment the ``version`` value
 before each deployment so that the query parameters change.
 
-It's also possible to set the version value on an asset-by-asset basis (instead
-of using the global version - e.g. ``v2`` - set here). See
-:ref:`Versioning by Asset <book-templating-version-by-asset>` for details.
-
 You can also control how the query string works via the `version_format`_
 option.
 

reference/twig_reference.rst

@@ -111,7 +111,8 @@ asset
 
 Returns a public path to ``path``, which takes into account the base path
 set for the package and the URL path. More information in
-:ref:`book-templating-assets`. For asset versioning, see :ref:`reference-framework-assets-version`.
+:ref:`book-templating-assets`. For asset versioning, see
+:ref:`reference-framework-assets-version`.
 
 assets_version
 ~~~~~~~~~~~~~~
@@ -362,8 +363,8 @@ information in :ref:`book-templating-pages`.
 absolute_url
 ~~~~~~~~~~~~
 
-.. versionadded:: 2.6
-     The ``absolute_url`` function was introduced in Symfony 2.7
+.. versionadded:: 2.7
+    The ``absolute_url()`` function was introduced in Symfony 2.7.
 
 .. code-block:: jinja
 
@@ -372,18 +373,23 @@ absolute_url
 ``path``
     **type**: ``string``
 
-Returns the absolute URL for the given absolute path. This is useful to convert
-an existing path:
+Returns the absolute URL from the passed relative path. For example, assume
+you're on the following page in your app:
+``http://example.com/products/hover-board``.
 
 .. code-block:: jinja
 
-    {{ absolute_url(asset(path)) }}
+    {{ absolute_url('/human.txt') }}
+    {# http://example.com/human.txt #}
+
+    {{ absolute_url('products_icon.png') }}
+    {# http://example.com/products/products_icon.png #}
 
 relative_path
 ~~~~~~~~~~~~~
 
-.. versionadded:: 2.6
-     The ``relative_path`` function was introduced in Symfony 2.7
+.. versionadded:: 2.7
+    The ``relative_path()`` function was introduced in Symfony 2.7.
 
 .. code-block:: jinja
 
@@ -392,10 +398,17 @@ relative_path
 ``path``
     **type**: ``string``
 
-Returns a relative path for the given absolute path (based on the current
-request path). For instance, if the current path is
-``/article/news/welcome.html``, the relative path for ``/article/image.png`` is
-``../images.png``.
+Returns the relative path from the passed absolute URL. For example, assume
+you're on the following page in your app:
+``http://example.com/products/hover-board``.
+
+.. code-block:: jinja
+
+    {{ relative_path('http://example.com/human.txt') }}
+    {# ../human.txt #}
+
+    {{ relative_path('http://example.com/products/products_icon.png') }}
+    {# products_icon.png #}
 
 expression
 ~~~~~~~~~~