Merge pull request #3347 from patrickbkr/problem-solving20

Document `:$win-verbatim-args` argument of `run()` and related functions

Author: patrickbkr

doc/Type/Proc.pod6

@@ -170,11 +170,17 @@ n block <unit> at /tmp/3169qXElwq line 1␤␤»
 
 =head2 method spawn
 
-    method spawn(*@args ($, *@), :$cwd = $*CWD, Hash() :$env = %*ENV --> Bool:D)
+    method spawn(*@args ($, *@), :$cwd = $*CWD, Hash() :$env = %*ENV, :$win-verbatim-args = False --> Bool:D)
 
 Runs the C<Proc> object with the given command, argument list, working directory,
 and environment.
 
+On Windows the flag C<$win-verbatim-args> disables all automatic quoting of
+process arguments. See L<this blog|https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way>
+for more information on windows command quoting. The flag is ignored on all
+other platforms. The flag was introduced in Rakudo version 2020.06 and is not
+present in older releases.
+
 =head2 method shell
 
     method shell($cmd, :$cwd = $*CWD, :$env --> Bool:D)

doc/Type/Proc/Async.pod6

@@ -116,8 +116,10 @@ An example of piping several commands like C<echo "Hello, world" | cat -n>:
 
 =head2 method new
 
-    multi method new(*@ ($path, *@args), :$w, :$enc, :$translate-nl --> Proc::Async:D)
-    multi method new(   :$path, :@args,  :$w, :$enc, :$translate-nl --> Proc::Async:D)
+    multi method new(*@ ($path, *@args), :$w, :$enc, :$translate-nl,
+                     :$win-verbatim-args = False --> Proc::Async:D)
+    multi method new(   :$path, :@args,  :$w, :$enc, :$translate-nl,
+                     :$win-verbatim-args = False --> Proc::Async:D)
 
 Creates a new C<Proc::Async> object with external program name or path
 C<$path> and the command line arguments C<@args>.
@@ -134,6 +136,12 @@ If C<:translate-nl> is set to C<True> (default value), OS-specific
 newline terminators (e.g. C<\r\n> on Windows) will be automatically
 translated to C<\n>.
 
+On Windows the flag C<$win-verbatim-args> disables all automatic quoting of
+process arguments. See L<this blog|https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way>
+for more information on windows command quoting. The flag is ignored on all
+other platforms. The flag was introduced in Rakudo version 2020.06 and is not
+present in older releases.
+
 =head2 method stdout
 
     method stdout(Proc::Async:D: :$bin --> Supply:D)

doc/Type/independent-routines.pod6

@@ -496,7 +496,8 @@ sub run(
     Str:D :$enc = 'UTF-8',
     Str:D :$nl = "\n",
     :$cwd = $*CWD,
-    Hash() :$env = %*ENV
+    Hash() :$env = %*ENV,
+    :$win-verbatim-args = False
 --> Proc:D)
 
 Runs an external command I<without involving a shell> and returns a
@@ -554,7 +555,8 @@ These argument are quite flexible and admit, for instance, handles to
 redirect them. See L<Proc|/type/Proc> and
 L<Proc::Async|/type/Proc::Async> for more details.
 
-See also L<C<new>|/type/Proc#method_new> for more examples.
+See also L<C<new>|/type/Proc#method_new> and L<C<spawn>|/type/Proc#method_spawn>
+for more examples and explanation of all arguments.
 
 =head2 sub shell