Update doc about IDE file link format

Author: nicolas-grekas

reference/configuration/framework.rst

@@ -204,21 +204,20 @@ ide
 
 **type**: ``string`` **default**: ``null``
 
-If you're using an IDE like TextMate or Mac Vim, then Symfony can turn all
-of the file paths in an exception message into a link, which will open that
-file in your IDE.
+Symfony can turn file paths seen in dumps and in exception messages into links
+that will open in your preferred text editor or IDE.
 
-Symfony contains preconfigured URLs for some popular IDEs, you can set them
-using the following keys:
+Since every developer uses a different IDE, the recommended way to enable this
+feature is to configure it on a system level. This can be done by setting the
+``xdebug.file_link_format`` option in your ``php.ini`` configuration file.
 
-* ``textmate``
-* ``macvim``
-* ``emacs``
-* ``sublime``
+Alternatively, you can use this ``ide`` configuration key.
 
-You can also specify a custom URL string. If you do this, all percentage
-signs (``%``) must be doubled to escape that character. For example, if
-you use PHPstorm on the Mac OS platform, you will do something like:
+In both cases, the expected configuration value is a URL template that should
+contain an ``%f`` where the file path is expected and ``%l`` for the line. When
+using the ``ide`` configuration key, percentages signs (``%``) must be escaped by
+doubling them. For example, if you use PHPstorm on the Mac OS platform, you will
+do something like:
 
 .. configuration-block::
 
@@ -248,18 +247,28 @@ you use PHPstorm on the Mac OS platform, you will do something like:
             'ide' => 'phpstorm://open?file=%%f&line=%%l',
         ));
 
+.. versionadded:: 3.2
+
+    When running your app in a container or in a virtual machine, you can tell
+    Symfony to map path prefixes from the guest to the host. This map should be
+    specified after a ``#`` using URL-encoding::
+
+        phpstorm://open?file=%%f&line=%%l#/guest/path1/=/host/path2/&/guest/path2/=/host/path2/&...
+
 .. tip::
 
-    If you're on a Windows PC, you can install the `PhpStormProtocol`_ to
-    be able to use this.
+    Symfony contains preconfigured URLs for some popular IDEs, you can set them
+    using the following values:
 
-Of course, since every developer uses a different IDE, it's better to set
-this on a system level. This can be done by setting the ``xdebug.file_link_format``
-in the ``php.ini`` configuration to the URL string.
+    * ``textmate``
+    * ``macvim``
+    * ``emacs``
+    * ``sublime``
 
-If you don't use Xdebug, another way is to set this URL string in the
-``SYMFONY__TEMPLATING__HELPER__CODE__FILE_LINK_FORMAT`` environment variable.
-If any of these configurations values are set, the ``ide`` option will be ignored.
+.. tip::
+
+    If you're on a Windows PC, you can install the `PhpStormProtocol`_ to
+    be able to use this.
 
 .. _reference-framework-test: