escapeshellcmd: add warning about spaces in paths on Windows

It is a known issue that spaces are not escaped in shell commands, which can be especially problematic on Windows.
This adds a warning about this behaviour to the function, including a way to solve this in userland code.

Ref: https://bugs.php.net/bug.php?id=43261 (last two comments)

Also see: squizlabs/PHP_CodeSniffer#3214

reference/exec/functions/escapeshellcmd.xml

@@ -86,6 +86,20 @@ system($escaped_command);
      <function>escapeshellarg</function> should be used instead.
     </para>
    </warning>
+   <warning xmlns="http://docbook.org/ns/docbook">
+    <para>
+     Spaces will not be escaped by <function>escapeshellcmd</function>
+     which can be problematic on Windows with paths like:
+     <literal>C:\Program Files\ProgramName\program.exe</literal>.
+     This can be mitigated using the following code snippet:
+    <programlisting role="php">
+<![CDATA[
+<?php
+$cmd = preg_replace('`(?<!^) `', '^ ', escapeshellcmd($cmd));
+]]>
+    </programlisting>
+    </para>
+   </warning>
  </refsect1>
 
  <refsect1 role="seealso">