Expands filehandle explanation closes #2111

doc/Type/IO.pod6

@@ -352,7 +352,9 @@ spurt 'file-that-already-exists', 'new text', :createonly;
 
     sub run(*@args ($, *@) --> Proc)
 
-Runs an external command without involving a shell and returns a L<Proc> object.
+Runs an external command I<without involving a shell> and returns a
+L<Proc> object. By default, the external command will print to standard
+output and error, and read from standard input.
 
     run 'touch', '>foo.txt'; # Create a file named >foo.txt
 
@@ -376,19 +378,33 @@ Note that C<--> is required for many programs to disambiguate between
 command-line arguments and
 L<filenames that begin with hyphens|http://mywiki.wooledge.org/BashPitfalls#Filenames_with_leading_dashes>.
 
-A sunk L<Proc> object for a process that L<exited|/routine/exitcode> unsuccessfully
-will throw. If you wish to ignore such failures, simply use L<run> in non-sink context:
+A sunk L<Proc> object for a process that L<exited|/routine/exitcode>
+unsuccessfully will throw. If you wish to ignore such failures, simply
+use L<run> in non-sink context:
 
     run 'false';     # SUNK! Will throw
     run('false').so; # OK. Evaluates Proc in Bool context; no sinking
 
-To capture output or error you can use the C<:out> or C<:err> arguments respectively:
+If you want to capture standard output or error instead of having it
+printed directly you can use the C<:out> or C<:err> arguments
+respectively, which will make them available using the
+L<C<Proc.out>|/type/Proc> method:
 
     my $proc = run 'echo', 'Perl 6 is Great!', :out, :err;
     $proc.out.slurp(:close).say; # OUTPUT: «Perl 6 is Great!␤»
     $proc.err.slurp(:close).say; # OUTPUT: «␤»
 
-See L<Proc|/type/Proc> and L<Proc::Async|/type/Proc::Async> for more details.
+You can use these arguments to redirect them to a filehandle, thus
+creating a kind of I<pipe>:
+
+    my $ls-alt-handle = open :w, '/tmp/cur-dir-ls-alt.txt';
+    my $proc = run "ls", "-alt", :out($ls-alt-handle);
+    # (The file will contain the output of the ls -alt command)
+
+
+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.
 
 =head2 sub shell
 

doc/Type/Proc/Async.pod6

@@ -8,11 +8,12 @@
 class Proc::Async {}
 =end code
 
-B<Note:> only the MoarVM backend of Rakudo implements C<Proc::Async> at the
-moment.
+B<Note:> only the MoarVM backend of Rakudo implements C<Proc::Async> at
+the moment.
 
-C<Proc::Async> allows you to run external commands asynchronously, capturing
-standard output and error handles, and optionally write to its standard input.
+C<Proc::Async> allows you to run external commands asynchronously,
+capturing standard output and error handles, and optionally write to its
+standard input.
 
 =begin code
 my $file = ‘foo’.IO;
@@ -127,18 +128,20 @@ An example of piping several commands like C<echo "Hello, world" | cat -n>:
     multi method new(*@ ($path, *@args), :$w, :$enc, :$translate-nl --> Proc::Async:D)
     multi method new(   :$path, :@args,  :$w, :$enc, :$translate-nl --> 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>.
+Creates a new C<Proc::Async> object with external program name or path
+C<$path> and the command line arguments C<@args>.
 
 If C<:w> is passed to C<new>, then a pipe to the external program's standard
 input stream (stdin) is opened, to which you can write with C<write> and
 C<say>.
 
-The C<:enc> specifies L<the encoding|/type/IO::Handle#method_encoding> for streams
-(can still be overridden in individual methods) and defaults to C<utf8>.
+The C<:enc> specifies L<the encoding|/type/IO::Handle#method_encoding>
+for streams (can still be overridden in individual methods) and defaults
+to C<utf8>.
 
-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>.
+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>.
 
 =head2 method stdout
 
@@ -186,8 +189,9 @@ along as L<Str|/type/Str>.
     await $promise;
 
 You must call C<stderr> before you call L<#method start>. Otherwise an
-exception of class L<X::Proc::Async::TapBeforeSpawn|/type/X::Proc::Async::TapBeforeSpawn> is
-thrown.
+exception of class
+L<X::Proc::Async::TapBeforeSpawn|/type/X::Proc::Async::TapBeforeSpawn>
+is thrown.
 
 If C<stderr> is not called, the external program's standard error stream is not
 captured at all.
@@ -203,8 +207,8 @@ Use L«C<.Supply>|/type/Proc::Async#method_Supply» for merged STDOUT and STDERR
     multi method bind-stdin(IO::Handle:D $handle)
     multi method bind-stdin(Proc::Async::Pipe:D $pipe)
 
-Sets a handle (which must be opened) or a C<Pipe> as a source of C<STDIN>. The C<STDIN> of
-the target process must be writable or
+Sets a handle (which must be opened) or a C<Pipe> as a source of
+C<STDIN>. The C<STDIN> of the target process must be writable or
 C<X::Proc::Async::BindOrUse> will be thrown.
 
     my $p = Proc::Async.new("cat", :in);
@@ -223,16 +227,18 @@ and will print the content of C</etc/profile> to standard output.
 
     method bind-stdout(IO::Handle:D $handle)
 
-Redirects STDOUT of the target process to a handle (which must be opened).
-If STDOUT is closed L<X::Proc::Async::BindOrUse|/type/x/proc/async/BindOrUse>
-will be thrown.
+Redirects STDOUT of the target process to a handle (which must be
+opened). If STDOUT is closed
+L<X::Proc::Async::BindOrUse|/type/x/proc/async/BindOrUse> will be
+thrown.
 
     my $p = Proc::Async.new("ls", :out);
     my $h = "ls.out".IO.open(:w);
     $p.bind-stdout($h);
     $p.start;
 
-This program will pipe the output of the C<ls> shell command to a file called C<ls.out>, which we are opened for reading.
+This program will pipe the output of the C<ls> shell command to a file
+called C<ls.out>, which we are opened for reading.
 
 =head2 method bind-stderr
 
@@ -416,8 +422,8 @@ The C<Proc::Async> object must be created for writing (with
 C<Proc::Async.new(:w, $path, @args)>). Otherwise an
 L<X::Proc::Async::OpenForWriting> exception will the thrown.
 
-C<start> must have been called before calling method close-stdin, otherwise an
-L<X::Proc::Async::MustBeStarted> exception is thrown.
+C<start> must have been called before calling method close-stdin,
+otherwise an L<X::Proc::Async::MustBeStarted> exception is thrown.
 
 =head2 method kill