From 35556da26a337428ecf9786d43de593c1b560e2a Mon Sep 17 00:00:00 2001
From: Nicolas Grekas <nicolas.grekas@gmail.com>
Date: Fri, 6 Dec 2019 11:36:19 +0100
Subject: [PATCH] Update paragraph about portable command lines

---
 components/process.rst | 38 ++++++++++++++++----------------------
 1 file changed, 16 insertions(+), 22 deletions(-)

diff --git a/components/process.rst b/components/process.rst
index 4819c023813..9a53f06080b 100644
--- a/components/process.rst
+++ b/components/process.rst
@@ -112,7 +112,7 @@ Using Features From the OS Shell
 
 Using array of arguments is the recommended way to define commands. This
 saves you from any escaping and allows sending signals seamlessly
-(e.g. to stop processes before completion)::
+(e.g. to stop processes while they run)::
 
     $process = new Process(['/path/command', '--option', 'argument', 'etc.']);
     $process = new Process(['/path/to/php', '--define', 'memory_limit=1024M', '/path/to/script.php']);
@@ -139,6 +139,21 @@ environment variables using the second argument of the ``run()``,
     // On both Unix-like and Windows
     $process->run(null, ['MESSAGE' => 'Something to output']);
 
+To help write command lines that are independent from the operating system,
+you can also write the above code as such::
+
+    // On both Unix-like and Windows
+    $process = Process::fromShellCommandline('echo "${:MESSAGE}"');
+
+This requires using a syntax that is specific to the component: when enclosing
+a variable name into ``"{$:`` and ``}"`` exactly, the process object will
+replace it with its escaped value, or will fail if the variable is not found in
+the list of environment variables attached to the command.
+
+.. versionadded:: 4.4
+
+    Portable command lines were introduced in Symfony 4.4.
+
 Setting Environment Variables for Processes
 -------------------------------------------
 
@@ -368,27 +383,6 @@ instead::
     );
     $process->run();
 
-Using a Prepared Command Line
------------------------------
-
-You can run the process by using a a prepared command line using the
-double bracket notation. You can use a placeholder in order to have a
-process that can only be changed with the values and without changing
-the PHP code::
-
-    use Symfony\Component\Process\Process;
-
-    $process = Process::fromShellCommandline('echo "$name"');
-    $process->run(null, ['name' => 'Elsa']);
-
-.. caution::
-
-    A prepared command line will not be escaped automatically!
-
-.. versionadded:: 4.4
-
-    Prepared command lines were introduced in Symfony 4.4.
-
 Process Timeout
 ---------------